Execução headless e integração contínua

Um cenário construído na interface executa-se sem janela a partir da linha de comandos. É o caminho que transforma os seus testes de API numa etapa de pipeline.

restorm \
  --open ./projet.restorm \
  --run "Find pets by status" \
  --headless \
  --param status=available

Edição Pro

A execução headless está incluída nas edições Pro e Enterprise. Requer um token de organização, fornecido na variável de ambiente RESTORM_TOKEN. Ver Planos e capacidades.

Os argumentos

Argumento	Função
--open <path>, -o	O projeto a abrir. Obrigatório com --run
--run <target>	O cenário a executar. A sua presença ativa o modo linha de comandos
--by <name|id>	Como --run designa o cenário: pelo nome (predefinição) ou pelo identificador
--headless	Nenhuma janela. Sem ele, a janela aparece enquanto o registo corre na consola
--param name=value	Um valor para um parâmetro de entrada do cenário (uma caixa Input / Param). Repetível
--all-logs	Inclui as entradas do motor; por predefinição só são emitidas as da ação Log
--out <file>	Escreve também o registo num ficheiro, em tempo real
--clear-settings, -cls	Reinicia as preferências antes do lançamento

Um --param mal formado (sem =) é sinalizado na saída de erro e ignorado. name= (valor vazio) é aceite.

Os valores são convertidos segundo o tipo declarado do parâmetro — ver Variáveis e dados.

--param visa as entradas do cenário, não as variáveis de ambiente

--param alimenta as caixas Input / Param declaradas no cenário — não modifica uma variável de ambiente. Assim, o --param status=available acima só funciona porque o cenário expõe um parâmetro de entrada chamado status. Querer sobrepor o URL de base com --param baseUrl=… não teria nenhum efeito se baseUrl for uma variável de ambiente: um valor que vive num ambiente não é sobreponível na linha de comandos. Para tornar um valor desses comandável a partir da CI, exponha-o como parâmetro de entrada do cenário (uma caixa Input / Param) e ligue-o onde precisar dele.

Os códigos de saída

Código	Significado
0	O cenário terminou corretamente
1	Falha, cancelamento ou erro do motor
2	Alvo não encontrado, ficheiro --out inacessível ou --run sem --open
3	Direito recusado: RESTORM_TOKEN ausente, inválido ou revogado, plano insuficiente ou ponto de verificação inalcançável

É esta convenção que torna o resultado diretamente utilizável por um runner de CI.

A saída

O registo é escrito na saída standard, uma entrada de cada vez, assim que é produzida, sob a forma de uma sequência YAML:

- message: "🔵 [2026-07-29 10:30:00.123] Commande créée"
  data: { id: 4271 }

Os níveis são prefixados por um círculo colorido: ⚪ debug, 🔵 info, 🟠 warn, 🔴 error. As linhas nunca são cortadas — a saída continua a poder ser filtrada com grep. Os erros saem pela saída de erro standard.

É exatamente o texto que o botão “copiar o registo” da interface produz: o mesmo formato de ambos os lados.

Os segredos na CI

Use a fonte de segredo variável de ambiente: o segredo é injetado pelo cofre da sua CI, o Restorm limita-se a lê-lo e nada é escrito no projeto. Ver Segredos.

Fixe a versão

O canal de transferência publica ficheiros versionados (restorm_<version>_amd64.deb): não existe nenhum alias latest. Fixe a versão no seu pipeline — é de qualquer modo o que se quer na CI, para que uma nova versão não altere o comportamento de um job sem revisão. Os nomes de ficheiro exatos da última versão estão enumerados no manifesto latest-linux.yml do mesmo canal.

Instalar o Restorm no runner

• A partir do npm — npm i -g restorm-cli@<versão> e depois restorm …. A compilação oficial é transferida uma única vez, verificada pela soma de verificação publicada e guardada em cache, pelo que as tarefas seguintes na mesma máquina não transferem nada. O número de versão do pacote npm é a versão do Restorm que ele executa: fixar um fixa o outro.
• A partir do pacote do sistema (.deb, .rpm), como nos exemplos abaixo — a melhor opção se construir a sua própria imagem de runner, já que a tarefa deixa de transferir seja o que for.

A action oficial do GitHub

No GitHub, a Monsieur-Dev/restorm-action reúne tudo o que esta página descreve num único passo: instala o Restorm através do restorm-cli (uma transferência verificada por soma de verificação e guardada em cache entre tarefas), envolve-o em xvfb, executa o seu cenário sem interface e traduz cada código de saída num erro de tarefa com nome.

- uses: Monsieur-Dev/restorm-action@v1
  with:
    project: ./api.restorm
    scenario: Smoke tests
    params: |
      status=available
  env:
    RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}

A tag da action fixa a versão do Restorm (@v1.2.3 executa o Restorm 1.2.3), ou passe uma entrada version: explícita. Todas as entradas estão documentadas no README do repositório. A receita manual abaixo continua disponível para quem quiser controlo total.

GitHub Actions

name: Tests d'API
on: [push]

jobs:
  api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Installer Restorm
        env:
          RESTORM_VERSION: '1.4.2' # a versão que quiser fixar
        run: |
          curl -sSL -o restorm.deb \
            "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
          sudo apt-get install -y ./restorm.deb

      - name: Exécuter les tests de fumée
        env:
          RESTORM_TOKEN: ${{ secrets.RESTORM_TOKEN }}
          API_TOKEN: ${{ secrets.API_TOKEN }}
        run: |
          xvfb-run -a restorm \
            --open ./api.restorm \
            --run "Find pets by status" \
            --headless \
            --all-logs \
            --out run.log \
            --param status=available

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

GitLab CI

tests-api:
  image: ubuntu:24.04
  variables:
    RESTORM_TOKEN: $RESTORM_TOKEN
    RESTORM_VERSION: '1.4.2' # a versão que quiser fixar
  before_script:
    - apt-get update && apt-get install -y curl xvfb
    - curl -sSL -o restorm.deb "https://dl.restorm.app/restorm_${RESTORM_VERSION}_amd64.deb"
    - apt-get install -y ./restorm.deb
  script:
    - >
      xvfb-run -a restorm
      --open ./api.restorm
      --run "Find pets by status"
      --headless --all-logs --out run.log
      --param status=$PET_STATUS
  artifacts:
    when: always
    paths: [run.log]

O que muda em modo headless

• As ações Toast não fazem nada; a execução prossegue normalmente.
• Os parâmetros não podem ser pedidos interativamente: forneça-os todos com --param ou deixe-os assumir o seu valor predefinido.
• O servidor MCP nunca arranca numa máquina sem ecrã, qualquer que seja a definição.

Obter um token

O token RESTORM_TOKEN (prefixado rstk_) gera-se a partir do painel de controlo da sua conta. Está associado à organização, não a uma pessoa: é o token que se coloca no cofre da CI. Ver Contas e ligação.