DEV Community

Cover image for Ferramenta de Mock de API Headless para CI: Servidores Mock sem GUI
Lucas
Lucas

Posted on • Originally published at apidog.com

Ferramenta de Mock de API Headless para CI: Servidores Mock sem GUI

Uma ferramenta de mock de API headless cria uma versão falsa, funcional e automatizável da sua API a partir de uma especificação ou configuração. Ela roda sem interface gráfica, normalmente via CLI, Docker, CI/CD ou URL hospedada. Use esse tipo de mock quando precisar testar frontend, contratos ou pipelines sem depender do backend real. Se você quer revisar o conceito antes, veja o que é uma API mock.

Experimente o Apidog hoje

O que "headless" significa para um mock de API

Um servidor mock responde a requisições HTTP com dados falsos, mas compatíveis com o contrato da API. O modo headless significa que esse servidor roda sem GUI: você inicia com um comando, aponta para uma especificação ou arquivo de configuração e expõe uma porta ou URL.

Na prática, isso permite usar mocks em ambientes sem tela, como:

  • jobs de CI que precisam de um backend previsível;
  • containers Docker em uma stack docker-compose;
  • scripts locais de desenvolvimento frontend;
  • ambientes de preview criados por pull request;
  • testes automatizados de contrato ou regressão.

Exemplo de fluxo típico:

# inicia o mock
mock-server --spec ./openapi.yaml --port 4010

# frontend ou testes usam:
# http://127.0.0.1:4010
Enter fullscreen mode Exit fullscreen mode

Uma GUI é útil para desenhar respostas durante o design. Mas, quando o mock precisa rodar no pipeline, você precisa de um modo automatizável: CLI, imagem Docker ou URL hospedada.

Mocks baseados em especificação vs. mocks baseados em configuração

Antes de escolher uma ferramenta, defina a fonte da verdade do mock.

Mock baseado em especificação

Ferramentas baseadas em especificação leem um contrato, geralmente OpenAPI, e geram respostas a partir dele.

Exemplo:

paths:
  /users:
    get:
      responses:
        "200":
          description: Lista de usuários
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    email:
                      type: string
                      format: email
Enter fullscreen mode Exit fullscreen mode

Vantagens:

  • o mock acompanha o contrato;
  • menos configuração duplicada;
  • ideal para validar frontend antes do backend;
  • bom para times que usam design-first.

Mock baseado em configuração

Ferramentas baseadas em configuração usam arquivos próprios, regras, stubs ou respostas gravadas.

Exemplo simplificado:

{
  "request": {
    "method": "GET",
    "url": "/users"
  },
  "response": {
    "status": 200,
    "body": [
      {
        "id": 1,
        "email": "ana@example.com"
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Vantagens:

  • maior controle sobre cenários específicos;
  • bom para simular erros, estados e regras complexas;
  • útil quando não existe OpenAPI confiável.

Na maioria dos projetos, o caminho prático é combinar os dois: usar especificação para o fluxo principal e regras customizadas para exceções. Veja também este guia de mocking de API.

Opções reais para mock headless

Abaixo estão ferramentas que rodam sem GUI e podem ser usadas em scripts, CI ou Docker.

Prism

O Prism transforma um arquivo OpenAPI 2/3 ou uma Postman Collection em um servidor mock com um comando:

prism mock openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Por padrão, ele sobe em:

http://127.0.0.1:4010
Enter fullscreen mode Exit fullscreen mode

Para usar dados dinâmicos gerados a partir do schema:

prism mock openapi.yaml -d
Enter fullscreen mode Exit fullscreen mode

Quando usar Prism:

  • você já tem um arquivo OpenAPI;
  • quer um mock simples via CLI;
  • prefere que a especificação seja a fonte da verdade;
  • precisa rodar rápido em CI ou localmente.

Exemplo em pipeline:

npx @stoplight/prism-cli mock ./openapi.yaml &
MOCK_PID=$!

npm test

kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

O Prism também suporta geração de dados com Faker via extensão x-faker.

WireMock

WireMock é um servidor mock HTTP maduro, baseado em Java. Ele funciona bem quando você precisa de stubs detalhados, correspondência complexa de requisições ou gravação/reprodução de tráfego.

Para iniciar:

java -jar wiremock-standalone-3.x.x.jar --port 9099
Enter fullscreen mode Exit fullscreen mode

Exemplo de stub:

{
  "request": {
    "method": "GET",
    "url": "/users/1"
  },
  "response": {
    "status": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "jsonBody": {
      "id": 1,
      "name": "Ana"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Quando usar WireMock:

  • você precisa simular cenários com estado;
  • quer gravar tráfego de um backend real;
  • precisa de regras avançadas de matching;
  • seu stack já usa JVM;
  • você quer controlar cada resposta manualmente.

WireMock é menos “OpenAPI-first” e mais orientado a stubs. Isso dá flexibilidade, mas também exige manter a configuração alinhada com a API real.

Mockoon CLI

O Mockoon combina uma aplicação desktop com um CLI para execução headless. Você desenha o ambiente na GUI e roda esse ambiente via terminal, CI ou Docker.

Exemplo:

mockoon-cli start --data ./environment.json --port 3000
Enter fullscreen mode Exit fullscreen mode

Também é possível usar Docker. O Mockoon oferece imagem oficial e comando dockerize para gerar uma imagem autocontida do mock.

Quando usar Mockoon CLI:

  • você prefere configurar endpoints visualmente;
  • quer versionar um arquivo de ambiente;
  • precisa rodar o mesmo mock em CI;
  • quer templating, regras de resposta e proxy mode.

Exemplo de uso em desenvolvimento frontend:

mockoon-cli start --data ./mockoon-env.json --port 3000

# app frontend
VITE_API_URL=http://localhost:3000 npm run dev
Enter fullscreen mode Exit fullscreen mode

Servidor mock do Apidog

O Apidog é uma plataforma de API que inclui design, documentação, testes e mock no mesmo projeto. O servidor mock é baseado em schema por padrão: ao definir ou importar uma API, o Apidog pode gerar o mock sem configuração separada.

O Smart Mock usa nomes e tipos de campos para gerar dados mais realistas. Por exemplo, campos como:

email
avatar
username
phone
date
IP
Enter fullscreen mode Exit fullscreen mode

podem receber valores coerentes em vez de placeholders como string.

Para maior controle, você pode usar expressões Faker.js, por exemplo:

{{$person.fullName}}
{{$number.int(min=1,max=100)}}
Enter fullscreen mode Exit fullscreen mode

Também é possível criar regras de mock customizadas para condições específicas de requisição.

Para uso headless, há duas opções práticas:

  1. usar uma URL de Cloud Mock, como https://mock.apidog.com/...;
  2. rodar um mock local em 127.0.0.1 e, se necessário, vinculá-lo ao IP da intranet.

Isso permite que CI, colegas de equipe ou ambientes de preview consumam o mesmo mock sem manter arquivos duplicados de stub. Como o mock vem do mesmo projeto que contém design, documentação e testes, ele tende a permanecer mais alinhado ao contrato.

Comparação

Ferramenta Fonte da verdade Execução headless Dados realistas Melhor para
Prism Arquivo OpenAPI / Postman prism mock spec.yaml Modo dinâmico (-d) + x-faker Mocking CLI simples baseado em especificação
WireMock Regras de stub / gravações Jar standalone Templating de resposta Matching complexo, JVM, gravação/reprodução
Mockoon CLI Ambientes criados na GUI mockoon-cli start + Docker Auxiliares de templating Design visual com implantação headless
Apidog Schema de API no projeto Cloud Mock + servidor local Smart Mock + Faker.js Mocks vinculados a design, docs e testes

Escolha de forma pragmática:

  • use Prism se sua API está bem descrita em um único OpenAPI;
  • use WireMock se você precisa de regras complexas, estados ou replay;
  • use Mockoon CLI se o time prefere configurar visualmente e rodar headless;
  • use Apidog se quer mock, contrato, documentação e testes no mesmo fluxo.

Para uma visão mais ampla, veja a lista de melhores ferramentas de mock de API.

Como rodar um mock headless em CI

O padrão é sempre o mesmo:

  1. iniciar o mock;
  2. apontar os testes para a URL do mock;
  3. executar testes;
  4. encerrar o processo.

Exemplo com Prism:

# inicia o mock em segundo plano
prism mock ./openapi.yaml &
MOCK_PID=$!

# configura a URL usada pelos testes
export API_BASE_URL=http://127.0.0.1:4010

# executa testes
npm test

# encerra o mock
kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

Exemplo em GitHub Actions:

name: frontend-tests

on:
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Start mock server
        run: |
          npx @stoplight/prism-cli mock ./openapi.yaml &
          echo $! > mock.pid

      - name: Run tests
        env:
          API_BASE_URL: http://127.0.0.1:4010
        run: npm test

      - name: Stop mock server
        if: always()
        run: kill $(cat mock.pid)
Enter fullscreen mode Exit fullscreen mode

Com o Apidog, você pode evitar iniciar um processo local e apontar os testes diretamente para a URL de Cloud Mock. Isso reduz uma dependência dentro do pipeline.

Exemplo conceitual:

export API_BASE_URL=https://mock.apidog.com/your-project/your-endpoint

npm test
Enter fullscreen mode Exit fullscreen mode

Se o contrato muda dentro do projeto, o mock acompanha o schema definido ali.

Como combinar mock headless com testes de API

Depois que o mock está disponível, você pode usá-lo para validar clientes, integrações e cenários de API.

Um fluxo comum:

# 1. sobe o mock
prism mock ./openapi.yaml &
MOCK_PID=$!

# 2. executa testes de contrato ou integração
npm run test:api

# 3. encerra o mock
kill $MOCK_PID
Enter fullscreen mode Exit fullscreen mode

No ecossistema do Apidog, o apidog-cli também roda em modo headless. Com apidog run, você pode executar cenários de teste em CI, usar dados de CSV ou JSON e gerar relatórios em CLI, HTML ou JSON.

Referências úteis:

Mocks e agentes de codificação de IA

Se você usa Cursor, Claude ou VS Code com agentes de IA, o contrato da API precisa estar acessível para gerar código cliente correto.

O servidor MCP do Apidog permite que agentes de IA leiam especificações de API diretamente. Isso ajuda o agente a criar chamadas HTTP, tipos e clientes alinhados ao mesmo schema usado pelo mock.

O benefício prático é reduzir divergência:

schema da API
   ↓
mock
   ↓
testes
   ↓
código gerado pelo agente
Enter fullscreen mode Exit fullscreen mode

Quando todos usam o mesmo contrato, fica mais fácil detectar mudanças incompatíveis antes de chegar ao backend real.

Perguntas frequentes

Um mock headless é o mesmo que um servidor mock?

Sim, com uma diferença de execução. Um servidor mock é qualquer processo que responde com dados falsos. “Headless” indica que ele roda sem GUI, via comando, Docker ou URL hospedada. Isso o torna adequado para CI, scripts e ambientes automatizados.

Posso gerar um mock headless a partir da minha especificação OpenAPI?

Sim. O Prism lê OpenAPI diretamente. O Apidog também gera mocks a partir do schema do projeto. Esse modelo reduz configuração manual e mantém o mock mais próximo do contrato. Para o fluxo completo, veja o guia de mocking de API.

Como retornar dados realistas em vez de placeholders?

Depende da ferramenta. O Prism pode gerar dados dinâmicos com -d e x-faker. O Apidog usa Smart Mock para mapear nomes de campos como email, phone e avatar para valores coerentes, além de suportar expressões Faker.js. Sem esse tipo de motor, o mock tende a retornar valores genéricos como string, 0 ou arrays vazios.

Preciso rodar um servidor local?

Não necessariamente. Prism, WireMock e Mockoon CLI rodam processos que você gerencia localmente, em Docker ou no CI. O Apidog também oferece uma URL de Cloud Mock hospedada, que pode ser consumida por pipelines e colegas sem subir servidor local.

Conclusão

Um mock de API headless transforma o mock em parte do fluxo de engenharia: ele roda em CI, Docker, scripts e ambientes de preview. Prism, WireMock e Mockoon CLI resolvem bem esse problema em estilos diferentes. Se você quer manter mock, contrato, documentação e testes no mesmo projeto, o Apidog oferece mocks baseados em schema com execução local ou URL hospedada. Baixe o Apidog para criar um mock a partir da sua especificação e usá-lo no seu pipeline.

Top comments (0)