Uma ferramenta de mock de API headless cria um falso funcional da sua API a partir de uma especificação ou configuração, e o executa a partir da linha de comando sem uma janela para clicar. Isso é exatamente o que você precisa dentro de um pipeline de CI, um container Docker, ou um script de desenvolvimento frontend. Este guia explica o que "headless" significa para mocking, mostra as opções headless reais (Prism, WireMock, Mockoon CLI), e aborda onde o Apidog se encaixa. Se você quer o conceito primeiro, comece com o que é uma API mock.
O que "headless" significa para um mock de API
Um servidor mock responde a requisições HTTP com respostas falsas, porém realistas, para que um frontend ou um conjunto de testes possa rodar antes que o backend real exista. "Headless" significa apenas que o mock roda sem uma interface gráfica. Você o inicia com um comando, o aponta para uma especificação ou arquivo de dados, e ele escuta em uma porta.
Isso importa porque os lugares onde você mais deseja um mock são lugares sem tela:
- Um job de CI que precisa de um backend estável para testar.
- Um container Docker em uma stack
docker-compose. - O terminal de um colega de equipe que deseja o mock rodando em segundo plano.
- Um ambiente de preview efêmero criado por pull request.
Uma ferramenta de mock com GUI é boa para projetar respostas no seu laptop. Mas no momento em que você precisa desse mock em um pipeline, você precisa de um modo headless: uma flag de CLI, uma imagem Docker, ou uma URL hospedada que qualquer job possa acessar.
Mocks baseados em especificação vs. baseados em configuração
Ferramentas de mock headless se dividem em dois grupos, e a diferença molda todo o seu fluxo de trabalho.
Ferramentas baseadas em especificação leem seu documento OpenAPI e servem respostas diretamente a partir dele. O esquema é a fonte da verdade. Adicione um campo à especificação, e o mock o retorna. Isso mantém o mock honesto porque ele não pode se desviar muito do contrato.
Ferramentas baseadas em configuração armazenam respostas em seu próprio formato (arquivos JSON, stubs gravados, regras escritas à mão). Elas são flexíveis e boas para casos de uso que a especificação não cobre, mas você mantém essa configuração manualmente, e ela pode se desviar da API real.
A maioria das equipes prefere o baseado em especificação para o caminho feliz e substituições baseadas em configuração para casos incomuns. As melhores configurações de mocking de API suportam ambos.
As opções de mock headless, honestamente
Aqui estão as ferramentas que vale a pena conhecer. Cada uma roda sem GUI, e cada uma tem pontos fortes reais.
Prism (Stoplight)
O Prism transforma um arquivo OpenAPI 2/3 ou de Postman Collection em um servidor mock a partir de um único comando:
prism mock openapi.yaml
Ele escuta em http://127.0.0.1:4010 por padrão. Por padrão, ele retorna exemplos estáticos da sua especificação. Adicione -d (dinâmico) e o Prism gera dados aleatórios, mas válidos, a partir do esquema, com suporte a Faker via extensão x-faker. É de código aberto, leve e genuinamente focado na especificação. Se o seu contrato vive em um único arquivo OpenAPI e você quer um mock CLI puro, o Prism é uma ótima escolha.
WireMock
WireMock é um servidor mock HTTP maduro, baseado em Java. Você executa o jar standalone:
java -jar wiremock-standalone-3.x.x.jar --port 9099
Seu modelo principal é o stubbing: você define regras de correspondência de requisições e as respostas que elas retornam, via uma API JSON ou arquivos JSON. Ele também grava e reproduz o tráfego de um serviço real, o que é útil quando você não tem uma especificação, mas tem um backend funcional para capturar. WireMock se destaca para correspondência de requisições complexas, cenários com estado e stacks pesadas em JVM.
Mockoon CLI
O Mockoon é um aplicativo de desktop com um CLI complementar para uso headless. O CLI executa os ambientes de mock que você constrói, em servidores, em CI, ou em qualquer lugar onde você não possa abrir o aplicativo de desktop:
mockoon-cli start --data ./environment.json --port 3000
Ele oferece uma imagem Docker oficial e um comando dockerize que gera um Dockerfile para uma imagem de mock autocontida. Mockoon é baseado em configuração (você constrói ambientes na GUI e depois os executa headless), com templating, regras de resposta e modo proxy. Bom para quem gosta de projetar visualmente e implantar headless.
Servidor mock Apidog
O Apidog é uma plataforma de API tudo-em-um, e seu servidor mock é baseado em esquema por padrão. Quando você define ou importa uma API, o Apidog gera um mock sem configuração extra. Seu Smart Mock lê nomes e tipos de campos para produzir dados realistas: ele reconhece itens como email, avatar, username, phone, date e IP, e os preenche com valores sensatos em vez de placeholders string. Para controle total, você pode usar expressões Faker.js como {{$person.fullName}} ou {{$number.int(min=1,max=100)}}, além de regras de mock personalizadas para condições de requisição específicas.
Para uso headless, o Apidog expõe uma URL de Cloud Mock (https://mock.apidog.com/...) que qualquer job de CI ou colega de equipe pode acessar sem rodar nada localmente. Um mock local também roda em 127.0.0.1, e você pode vinculá-lo ao seu IP de intranet para que outras máquinas o acessem. Como o mock é derivado do mesmo projeto que contém o design da sua API, documentação e testes, ele permanece alinhado com o contrato em vez de se desviar para um arquivo de configuração separado.
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 puro baseado em especificação |
| WireMock | Regras de stub / gravações | Jar standalone | Templating de resposta | Correspondência complexa, stacks JVM, gravação/reprodução |
| Mockoon CLI | Ambientes construídos na GUI | mockoon-cli start + Docker |
Auxiliares de templating | Design visual, implantação headless |
| Apidog | Esquema de API no projeto | URL de Cloud Mock + servidor local | Smart Mock + Faker.js | Mocks baseados em esquema vinculados a design, docs e testes |
Não há um único vencedor. O Prism é o mais limpo se toda a sua API for um único arquivo OpenAPI. O WireMock se destaca na profundidade de correspondência de requisições. O Mockoon é ótimo se você prefere construir visualmente. O Apidog se encaixa para equipes que querem o mock, o contrato, a documentação e os testes em um só lugar para que não se desviem. Para um campo mais amplo, veja nosso resumo das melhores ferramentas de mock de API.
Executando um mock headless em CI
O padrão é o mesmo em todas as ferramentas. Você inicia o mock, aponta seus testes para ele e o encerra.
Um mock CLI baseado em especificação tem esta aparência em uma etapa do pipeline:
# inicia o mock em segundo plano
prism mock ./openapi.yaml &
MOCK_PID=$!
# executa seus testes de frontend ou API contra http://127.0.0.1:4010
npm test
# limpa
kill $MOCK_PID
Com o Apidog, você pode pular a execução de qualquer coisa apontando os testes para a URL do Cloud Mock, ou rodar um mock local da mesma forma. O mock responde a partir do seu esquema atual, então quando o contrato muda, o mock muda junto.
O próximo passo natural é testar contra esse mock a partir da linha de comando. O CLI do Apidog (apidog-cli) é ele próprio headless: apidog run executa seus cenários de teste em CI, suporta execuções baseadas em dados de CSV ou JSON, e escreve relatórios CLI, HTML ou JSON. O passo a passo em testar uma API REST da linha de comando mostra o ciclo completo, e o guia completo do CLI abrange as flags. Se você usou o Newman, a comparação Apidog CLI vs Postman CLI mapeia os conceitos.
Mocks e agentes de codificação de IA
Se você escreve código com Cursor, Claude ou VS Code, seu agente se beneficia de conhecer o contrato da API por trás de um mock. O servidor MCP do Apidog permite que um agente de IA leia suas especificações de API diretamente, para que possa criar código cliente que corresponda ao esquema que seu mock já está servindo. Isso mantém a saída do agente e as respostas do seu mock apontadas para o mesmo contrato.
Perguntas frequentes
Um mock headless é o mesmo que um servidor mock?
Sim, com um detalhe. Um servidor mock é qualquer processo que responde a requisições com respostas falsas. "Headless" especifica que ele roda sem uma GUI, iniciado por um comando ou hospedado em uma URL, de modo que funciona em CI, Docker e scripts. Todas as ferramentas aqui podem rodar headless.
Posso gerar um mock headless a partir da minha especificação OpenAPI?
Sim. O Prism lê OpenAPI diretamente, e o Apidog gera um mock a partir do esquema em seu projeto. Mocks baseados em especificação economizam esforço e permanecem mais próximos do contrato, já que o mock reflete o que a especificação diz em vez de uma configuração mantida separadamente. Veja nosso guia de mocking de API para o fluxo de trabalho completo.
Como os mocks headless retornam dados realistas em vez de placeholders?
Cada ferramenta possui um motor de dados. O modo dinâmico do Prism e x-faker geram valores a partir do esquema. O Smart Mock do Apidog corresponde nomes de campos como email ou phone a valores sensatos, e você pode usar expressões Faker.js para um controle mais preciso. Sem um desses, os mocks tendem a retornar strings vazias e zeros.
Preciso rodar um servidor, ou posso usar uma URL de mock hospedada?
Ambos funcionam. WireMock, Prism e Mockoon CLI rodam um processo que você gerencia. O Apidog adiciona uma URL de Cloud Mock hospedada que qualquer job de CI ou colega de equipe pode chamar sem nenhuma configuração local, o que remove uma parte móvel do pipeline.
Conclusão
Uma ferramenta de mock de API headless é a diferença entre um mock que o ajuda a navegar localmente e um que realmente roda no seu pipeline. Prism, WireMock e Mockoon CLI fazem isso bem para seus respectivos estilos de trabalho. Se você quer que o mock permaneça vinculado ao design da sua API, documentação e testes, em vez de viver em sua própria configuração que se desvia, o Apidog mantém tudo isso em um único projeto, com um mock baseado em esquema que roda localmente ou a partir de uma URL hospedada. Baixe o Apidog para criar um mock a partir da sua especificação e apontar seu CI para ele.