qa-api-swagger

Projeto de testes automatizados de API, com foco em documentação de contrato via OpenAPI/Swagger. A API sob teste é a GoRest, um serviço público de testes com um recurso REST completo de usuários, posts, comments e todos.

Este repositório é construído de forma incremental: começa com um conjunto pequeno de testes e cresce ao longo do tempo, cobrindo mais endpoints, cenários e ferramentas.

Objetivo

Demonstrar, na prática:

• Escrita de especificação OpenAPI 3.0 a partir da observação do comportamento real de uma API (a GoRest não publica uma spec oficial).
• Testes de API automatizados com Jest, cobrindo cenários positivos e negativos.
• Validação de contrato (contract testing): as respostas da API são checadas contra a especificação OpenAPI em tempo de execução, via jest-openapi.
• CI/CD com GitHub Actions, validando a spec, o lint e os testes em todo push e pull request.
• Documentação de casos de teste (docs/test-plan.md) e de defeitos observados na API sob teste (issues do repositório).
• Uma coleção Postman, gerada a partir da mesma especificação OpenAPI e executada via Newman, como forma alternativa de rodar os testes de contrato.
• Uma instância do Swagger UI publicada via GitHub Pages, renderizando a especificação diretamente do repositório.
• Testes orientados a schema com Schemathesis (property-based testing), gerando casos de teste automaticamente a partir da spec OpenAPI - já encontrou e documentou defeitos reais na API sob teste.
• Relatórios de teste em HTML, gerados a cada execução do Jest e do Newman e publicados como artefato do CI.
• Testes de segurança inspirados no OWASP API Security Top 10 (autenticação inválida, mass assignment, tratamento de entrada, observação de rate limiting), com um recorte que nunca toca dado de terceiros nem faz varredura agressiva contra o sandbox público.

Estrutura

openapi/       especificação OpenAPI dos recursos testados
src/           cliente HTTP usado pelos testes Jest
tests/         casos de teste (Jest)
postman/       collection e environment do Postman/Newman
scripts/       script de execução da collection via Newman
swagger-ui/    página estática do Swagger UI, publicada via GitHub Pages
schema-tests/  testes orientados a schema (Schemathesis)
docs/          plano de testes e documentação
.github/       workflows de CI, deploy do Pages e testes de schema

Como rodar localmente

Pré-requisitos: Node.js 20+.

npm install
npm run validate:openapi   # valida a especificação OpenAPI
npm run lint                # lint do código
npm test                    # executa os testes

Os testes de leitura (GET) não exigem token de autenticação. Os testes de escrita (POST/PUT/DELETE) exigem um token pessoal da GoRest: copie .env.example para .env e preencha GOREST_TOKEN com um token pessoal da GoRest. Sem o token, esses testes são pulados automaticamente, tanto localmente quanto no CI.

npm install já configura um hook de pre-commit (via husky

• lint-staged) que roda eslint --fix nos arquivos .js staged antes de cada commit local - erros que o --fix não resolve automaticamente bloqueiam o commit.

Postman / Newman

A coleção em postman/gorest.postman_collection.json cobre os mesmos cenários dos testes Jest (leitura e escrita, positivos e negativos), com asserções via scripts de teste do Postman.

npm run postman:run             # roda tudo; sem GOREST_TOKEN, pula as pastas de escrita
npm run postman:run:read-only   # roda só as pastas de leitura, mesmo com token configurado

Nota de segurança: o newman e seus reporters (incluindo newman-reporter-htmlextra) trazem dependências transitivas (ex.: handlebars, via postman-runtime) com vulnerabilidades conhecidas reportadas pelo npm audit. São as versões mais recentes disponíveis dos pacotes; o risco é aceito aqui porque rodam só localmente/no CI, como devDependency, contra uma API pública de teste - não em produção. O Dependabot está configurado para abrir PR assim que uma versão corrigida existir.

Swagger UI

A especificação em openapi/gorest-openapi.yaml é renderizada ao vivo em https://thomastds.github.io/qa-api-swagger/, via Swagger UI. A página (swagger-ui/index.html) carrega o Swagger UI por CDN e aponta para o arquivo da spec direto no branch main do repositório - qualquer merge que altere a spec atualiza a documentação publicada automaticamente, via o workflow pages.yml.

Testes orientados a schema (Schemathesis)

Além dos testes escritos manualmente, schema-tests/ usa o Schemathesis para gerar casos de teste automaticamente a partir de openapi/gorest-openapi.yaml, via property-based testing - útil para achar combinações de entrada que não foram pensadas manualmente.

pip install -r schema-tests/requirements.txt
bash schema-tests/run.sh

Restrito de propósito a operações GET, com poucos exemplos por operação e rate limit conservador, para não gerar carga de escrita nem estourar limites no sandbox público da GoRest. Roda semanalmente e sob demanda via schema-tests.yml - não em todo push/PR, porque tende a encontrar comportamentos permanentes da API de terceiros (não regressões deste repositório), e não faz sentido um check que falha sempre por um motivo fora do nosso controle.

Já encontrou e confirmou defeitos reais: reforçou a issue #3 (filtros com valor fora do enum aceitos silenciosamente) e descobriu a issue #9 (respostas 405 sem o header Allow exigido pela RFC 9110).

Relatórios de teste (HTML)

Tanto npm test quanto npm run postman:run/postman:run:read-only geram relatórios em HTML localmente, em reports/ (pasta ignorada pelo git):

• reports/jest/index.html - via jest-html-reporters.
• reports/newman/index.html - via newman-reporter-htmlextra.

O header Authorization é explicitamente omitido do relatório do Newman (skipHeaders em scripts/run-newman.js), para que o token real nunca apareça no HTML gerado, mesmo rodando a suíte completa autenticada localmente.

No CI, esses relatórios são publicados como artefato (test-reports) a cada execução - inclusive quando os testes falham, o que ajuda a depurar o motivo de uma falha diretamente pelo GitHub Actions, sem precisar reproduzir localmente.

Cobertura de testes

npm test gera cobertura automaticamente (via --coverage, configurado em jest.config.js), publicada no Codecov a cada execução do CI.

Vale um esclarecimento: como este é um projeto de testes de API, quase toda a lógica testada vive na API sob teste (a GoRest), não no código deste repositório. collectCoverageFrom mede apenas src/apiClient.js - o único arquivo de código próprio - então o percentual reflete o quão exercitado está esse cliente HTTP, e não o quão bem a GoRest está testada (isso é medido pela quantidade e variedade de casos em docs/test-plan.md, não por cobertura de linhas).

CI/CD

Todo push e pull request para main dispara um workflow que:

1. Valida a especificação OpenAPI (swagger-cli validate).
2. Roda o lint (eslint).
3. Executa a suíte de testes (jest), gerando cobertura.
4. Publica a cobertura no Codecov.
5. Executa a coleção Postman via Newman, restrita às pastas de leitura (para não duplicar carga de escrita no sandbox público da GoRest a cada execução - a cobertura de escrita já é validada pelos testes Jest).
6. Publica os relatórios HTML gerados como artefato do workflow.

Pull requests exigem esses checks passando, mas o merge é sempre manual - não há auto-merge configurado neste repositório.

Detalhes sobre o fluxo de branches, padrão de commits e como configurar o ambiente estão em CONTRIBUTING.md.

Dependências

O Dependabot verifica semanalmente três conjuntos de dependências e abre PR quando há atualização: pacotes npm (raiz do projeto), pip (schema-tests/requirements.txt) e as actions usadas nos workflows do GitHub Actions. Atualizações menores/patch do npm são agrupadas em um único PR para reduzir ruído. Alertas de vulnerabilidade e correções automáticas de segurança também estão habilitados no repositório - como em todo o resto do projeto, esses PRs passam pelos checks do CI e são mergeados manualmente, um a um.

Para reportar uma vulnerabilidade (ou entender o que está fora de escopo, como comportamentos da GoRest em si), ver SECURITY.md.

Outro projeto relacionado

Para testes de API sobre o restful-booker, veja o repositório correspondente no meu perfil do GitHub.