Automatizar os testes de API em integração contínua

Um cenário construído na interface executa-se tal e qual no seu pipeline. Este guia cobre a passagem à escala.

Pré-requisitos

• Um plano Pro ou Enterprise.
• Um token de organização (rstk_…) a colocar no cofre de segredos da sua CI. (A criação deste token em autosserviço a partir do painel de controlo chega em breve.)

O princípio

RESTORM_TOKEN=$RESTORM_TOKEN restorm \
  --open ./api.restorm \
  --run "Tests de fumée" \
  --headless \
  --all-logs \
  --out run.log \
  --param baseUrl=$BASE_URL

Código de saída 0 = sucesso, 1 = falha do cenário, 2 = erro de invocação, 3 = direito recusado.

É necessário um ecrã virtual

O Restorm é uma aplicação de computador: mesmo sem janela, precisa de um servidor de visualização. Num runner Linux, prefixe com xvfb-run -a.

xvfb-run -a restorm --open ./api.restorm --run "Tests de fumée" --headless

Os segredos

Nunca escreva um segredo no projeto. Declare as suas variáveis sensíveis com a fonte de segredo variável de ambiente; o cofre da sua CI injeta-as, o Restorm lê-as. Consulte Segredos.

env:
  API_TOKEN: ${{ secrets.API_TOKEN }}

Parametrizar por ambiente

Duas abordagens complementares:

1. Um parâmetro de cenário do tipo environment: --param Env=staging. O mesmo cenário corre contra qualquer alvo.
2. Parâmetros simples: --param baseUrl=…, --param tenant=….

A conversão segue o tipo declarado do parâmetro, e uma conversão impossível faz falhar o arranque imediatamente em vez de executar com um valor errado. Consulte Variáveis e dados.

Publicar o registo

--out run.log escreve o registo em tempo real. Publique-o como artefacto, inclusive quando o job falha — é precisamente aí que serve.

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: journal-restorm
    path: run.log

Escrever cenários legíveis em CI

Alguns hábitos que mudam tudo quando aparece um job vermelho às 3 da manhã:

• Mensagens de asserção explícitas. O campo message da ação Assert é o que aparecerá no registo: escreva aí o que era esperado.
• Registo nas etapas-chave. Sem --all-logs, só são emitidas as entradas da ação Log: é o seu fio narrativo.
• Validação de esquema em vez de asserção campo a campo. Ligue a saída errors de Validação de esquema a um Log: obtém a lista precisa das violações.
• Throw nas saídas else críticas, para que o código de saída reflita a falha.
• Retry em torno das chamadas de rede instáveis, em vez de aceitar testes intermitentes. Consulte Controlo.

Limpar

Encadeie a limpeza na porta done do cenário principal: done espera que todo o subgrafo esteja terminado. Consulte Portas e ligações.

Armadilhas a conhecer

Armadilha	Solução
O job fica à espera de uma entrada	Forneça todos os parâmetros com --param; em headless, nada pode ser pedido
Uma ação Toast não aparece	É normal: não tem efeito em headless. Use Log
O servidor MCP não aparece	É intencional: sem ecrã real, nunca arranca
Saída 3	O token ou o plano — a mensagem indica qual dos quatro casos
O ficheiro de projeto mudou de lugar	--open aceita um caminho relativo ao repositório: mantenha-o relativo

Exemplos completos

Os pipelines de GitHub Actions e de GitLab CI estão em Execução headless e CI.