Integração básica em CI com GitHub Actions: pipeline de testes e artefatos

O que significa integrar testes de API em CI com GitHub Actions

Integração contínua, ou CI, é a prática de executar verificações automáticas sempre que o código muda, para detectar problemas cedo e manter um padrão mínimo de qualidade. No contexto de QA de APIs com Postman, a integração básica em CI normalmente significa: ao abrir um Pull Request ou fazer push para uma branch, o pipeline executa seus testes (via Newman), gera relatórios e publica artefatos para consulta. Assim, o time consegue validar rapidamente se uma mudança no backend quebrou endpoints, contratos, regras de negócio ou fluxos críticos.

Em GitHub Actions, um “pipeline” é definido por um arquivo YAML dentro do repositório, em .github/workflows/. Esse arquivo descreve quando o workflow roda (gatilhos), em qual ambiente (runner), quais passos executar (checkout, instalar dependências, rodar Newman) e o que fazer com os resultados (falhar o job, anexar relatórios como artefatos, comentar no PR, etc.).

Pré-requisitos do repositório para rodar Newman no pipeline

Para uma integração básica, você precisa que o repositório contenha (ou consiga obter durante o pipeline) os arquivos necessários para execução: a collection exportada do Postman (JSON) e, se aplicável, um environment (JSON). Uma organização comum é criar uma pasta postman/ com subpastas como collections/, environments/ e data/. Exemplo de estrutura:

postman/collections/api-tests.postman_collection.json postman/environments/staging.postman_environment.json postman/reports/

Além disso, o pipeline precisa de Node.js (para instalar e executar o Newman) e, se você quiser relatórios HTML/JUnit, de um ou mais “reporters” do Newman. Em CI, é comum gerar: um relatório JUnit (para integração com ferramentas de testes) e um HTML (para leitura humana). Mesmo que você não use uma ferramenta externa, anexar HTML como artefato já resolve a necessidade de inspeção.

Gatilhos do workflow: quando rodar os testes

Os gatilhos mais usados são push e pull_request. Uma configuração típica roda em PRs para a branch principal e também em pushes diretos. Você pode restringir por paths (por exemplo, só rodar quando mudar algo em postman/ ou no backend), mas no começo é mais simples rodar sempre que houver PR para a branch principal.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

on:  pull_request:    branches: [ "main" ]  push:    branches: [ "main" ]

Se o seu time usa branches como develop e main, você pode rodar em develop para feedback rápido e manter main como “gate” mais rígido.

Definindo o job: runner, checkout e Node.js

Um job é um conjunto de passos que roda em um runner. O runner mais comum é ubuntu-latest, por ser rápido e ter bom suporte. Os primeiros passos quase sempre incluem: baixar o código do repositório (checkout) e configurar a versão do Node.js. Exemplo:

jobs:  api-tests:    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v4      - name: Setup Node        uses: actions/setup-node@v4        with:          node-version: "20"

Fixar a versão do Node ajuda a reduzir variações entre execuções. Se você já usa Node no projeto, alinhe com a versão do projeto. Caso contrário, escolha uma LTS recente.

Instalando Newman e reporters no pipeline

Você pode instalar Newman globalmente (com npm install -g) ou como dependência do projeto (com package.json). Para uma integração básica e rápida, a instalação global costuma ser suficiente. Para maior reprodutibilidade, prefira dependência do projeto e use npm ci.

Exemplo com instalação global e reporters comuns:

- name: Install Newman  run: npm install -g newman newman-reporter-htmlextra

O newman-reporter-htmlextra gera um HTML mais amigável. Se você também quiser JUnit, o Newman já suporta --reporters junit sem pacote extra, mas você precisa definir o arquivo de saída. Exemplo de reporters combinados: --reporters cli,htmlextra,junit.

Executando a collection no CI: comando Newman com parâmetros

O coração do pipeline é o comando do Newman. Em CI, você quer garantir que: a execução falhe quando houver teste falhando, os relatórios sejam gerados em um diretório conhecido e variáveis sensíveis não fiquem hardcoded. Um comando típico:

- name: Run API tests (Newman)  run: |    mkdir -p postman/reports    newman run postman/collections/api-tests.postman_collection.json \      --environment postman/environments/staging.postman_environment.json \      --reporters cli,htmlextra,junit \      --reporter-htmlextra-export postman/reports/newman-report.html \      --reporter-junit-export postman/reports/newman-report.xml \      --color on

Alguns detalhes importantes: o Newman retorna código de saída diferente de zero quando há falhas, o que faz o job falhar automaticamente. Isso é desejável para que o PR não seja aprovado com regressões. O diretório de relatórios deve ser criado antes para evitar erros de escrita.

Segredos e variáveis no GitHub Actions: como injetar tokens e URLs

Em CI, você raramente quer usar o mesmo ambiente local. Normalmente, você aponta para um ambiente de teste (staging) e injeta credenciais via Secrets do GitHub. A ideia é: o environment do Postman pode conter placeholders, e o pipeline substitui valores via variáveis de ambiente ou via parâmetros do Newman.

Uma abordagem prática é usar --env-var para sobrescrever variáveis do environment durante a execução. Exemplo:

- name: Run API tests with secrets  env:    BASE_URL: ${{ secrets.STAGING_BASE_URL }}    API_TOKEN: ${{ secrets.STAGING_API_TOKEN }}  run: |    mkdir -p postman/reports    newman run postman/collections/api-tests.postman_collection.json \      --environment postman/environments/staging.postman_environment.json \      --env-var baseUrl="$BASE_URL" \      --env-var apiToken="$API_TOKEN" \      --reporters cli,htmlextra,junit \      --reporter-htmlextra-export postman/reports/newman-report.html \      --reporter-junit-export postman/reports/newman-report.xml

Com isso, você evita commitar tokens no repositório e mantém o mesmo arquivo de environment para diferentes execuções. No GitHub, cadastre os segredos em Settings > Secrets and variables > Actions. Use nomes claros e separados por ambiente (por exemplo, STAGING_*, QA_*).

Publicando artefatos: anexando relatórios do Newman ao workflow

Artefatos são arquivos gerados durante o job que você quer baixar depois, como relatórios HTML, XML, logs e evidências. Em GitHub Actions, você publica artefatos com actions/upload-artifact. Isso é especialmente útil porque o log do console pode ser insuficiente para analisar falhas complexas, enquanto o HTML mostra requests, responses e asserts de forma organizada (dependendo do reporter).

Exemplo de upload:

- name: Upload Newman reports  if: always()  uses: actions/upload-artifact@v4  with:    name: newman-reports    path: postman/reports/

O if: always() é um detalhe crítico: mesmo que os testes falhem, você ainda quer o relatório como evidência para depurar. Sem isso, o job pode abortar e você perde o HTML/XML.

Pipeline completo: exemplo de workflow YAML mínimo e funcional

A seguir, um exemplo completo e direto, combinando gatilhos, setup, execução e artefatos. Ajuste nomes de arquivos e variáveis conforme seu repositório:

name: API Tests (Postman/Newman) on:  pull_request:    branches: [ "main" ]  push:    branches: [ "main" ] jobs:  api-tests:    runs-on: ubuntu-latest    steps:      - name: Checkout        uses: actions/checkout@v4      - name: Setup Node        uses: actions/setup-node@v4        with:          node-version: "20"      - name: Install Newman and reporter        run: npm install -g newman newman-reporter-htmlextra      - name: Run Newman        env:          BASE_URL: ${{ secrets.STAGING_BASE_URL }}          API_TOKEN: ${{ secrets.STAGING_API_TOKEN }}        run: |          mkdir -p postman/reports          newman run postman/collections/api-tests.postman_collection.json \            --environment postman/environments/staging.postman_environment.json \            --env-var baseUrl="$BASE_URL" \            --env-var apiToken="$API_TOKEN" \            --reporters cli,htmlextra,junit \            --reporter-htmlextra-export postman/reports/newman-report.html \            --reporter-junit-export postman/reports/newman-report.xml      - name: Upload reports        if: always()        uses: actions/upload-artifact@v4        with:          name: newman-reports          path: postman/reports/

Salve esse arquivo como .github/workflows/api-tests.yml. Ao abrir um PR para main, o GitHub Actions executará o job e exibirá o status no PR. Se falhar, o PR ficará com status vermelho, e você poderá baixar os artefatos na aba do workflow.

Boas práticas para tornar o pipeline confiável (sem complicar demais)

1) Timeouts e instabilidade de rede

Em CI, instabilidades de rede e latência podem causar falsos negativos. Se sua API ou ambiente de staging é mais lento, considere ajustar timeouts do Newman. Você pode usar opções como --timeout-request e --timeout para evitar falhas por tempo insuficiente. Exemplo:

newman run ... --timeout-request 30000 --timeout 180000

Evite timeouts exagerados, pois mascaram problemas reais e deixam o pipeline lento. Ajuste com base em medições do seu ambiente.

2) Separar “smoke” de “regressão”

Mesmo em uma integração básica, é útil pensar em dois níveis: um conjunto pequeno de testes críticos (smoke) para rodar em todo PR, e uma regressão completa para rodar em horários programados ou antes de releases. Sem repetir como organizar collections, a ideia prática em CI é ter duas collections (ou duas execuções) e dois workflows diferentes, ou um único workflow com jobs distintos. Exemplo de gatilho agendado:

on:  schedule:    - cron: "0 3 * * *"

Isso roda diariamente às 03:00 UTC. Você pode manter o PR rápido e ainda ter cobertura ampla em rotina.

3) Tornar falhas mais fáceis de diagnosticar

Quando um teste falha, você quer identificar rapidamente qual request, qual assert e qual resposta causou o problema. O HTML extra ajuda, mas você também pode salvar o output do console em arquivo para anexar como artefato. Exemplo:

- name: Run Newman (save log)  if: always()  run: |    mkdir -p postman/reports    set -o pipefail    newman run postman/collections/api-tests.postman_collection.json \      --environment postman/environments/staging.postman_environment.json \      --reporters cli,htmlextra,junit \      --reporter-htmlextra-export postman/reports/newman-report.html \      --reporter-junit-export postman/reports/newman-report.xml | tee postman/reports/newman-console.log

O set -o pipefail garante que o job falhe corretamente mesmo usando tee.

4) Cache de dependências (opcional)

Para pipelines mais rápidos, você pode cachear dependências. Se você instalar Newman globalmente, o ganho é menor. Se você usar package.json e npm ci, o cache do npm pode reduzir tempo. Em uma integração básica, implemente cache apenas se o tempo do pipeline estiver atrapalhando o fluxo do time.

Artefatos e rastreabilidade: o que guardar e por quanto tempo

O GitHub Actions permite definir retenção de artefatos (dependendo do plano e configurações). Para rastreabilidade de QA, os artefatos mais úteis são: relatório HTML, relatório JUnit XML e log do console. Com isso, você consegue comparar execuções e entender se a falha é regressão real, instabilidade ou mudança esperada.

Se você precisa de rastreabilidade por PR, mantenha o nome do artefato estável (por exemplo, newman-reports) e confie no histórico do workflow. Se precisa de rastreabilidade por ambiente, inclua o ambiente no nome do artefato (por exemplo, newman-reports-staging).

Variações comuns: matrix de ambientes e execução paralela

Uma evolução natural é rodar a mesma collection em mais de um ambiente (por exemplo, staging e QA) usando matrix. Isso ainda é “básico” em termos de GitHub Actions, mas já adiciona valor sem exigir ferramentas externas. Exemplo simplificado:

strategy:  matrix:    env: [ "staging", "qa" ]

Então você seleciona secrets diferentes por ambiente. Como o GitHub Secrets não permite indexação dinâmica simples, uma prática é criar jobs separados por ambiente ou usar Environments do GitHub (com approvals e secrets por environment). Para manter simples, comece com um ambiente e só depois expanda.

Checklist de implementação rápida

• Criar pasta .github/workflows/ e adicionar um YAML com gatilhos em pull_request e push.
• Garantir que a collection e o environment estejam versionados no repositório (ou baixados no pipeline).
• Configurar secrets no repositório: URL base e tokens necessários para o ambiente de CI.
• Instalar Newman e reporter HTML extra no job.
• Executar Newman com --env-var para injetar secrets e com export de relatórios para postman/reports/.
• Fazer upload de artefatos com if: always() para não perder evidências quando falhar.