SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor · Atualizado 2026-10-30

Mock de API e testes self-hosted em um VPS

WireMock simula dependencias com stubs versionados no Git, enquanto Hurl executa testes no CI. Rode ambos no VPS com Docker Compose e preserve relatorios apos rebuild.

Dois trabalhos que partilham um repositório

O mocking e os testes de API self-hosted são dois trabalhos diferentes, e tratá-los como um só pode desperdiçar uma semana. Um mock server substitui uma dependência que não pode ser chamada a partir do CI: um fornecedor de pagamentos, uma API de um parceiro, um upstream com limite de pedidos ou um serviço que outra equipa ainda não disponibilizou. Um executor de testes de API chama os seus próprios endpoints por uma ordem fixa e valida as respostas, transportando valores de uma resposta para o pedido seguinte.

Algumas ferramentas fazem os dois trabalhos. A função principal de um mock server é responder a pedidos. Um executor de testes não assume o que um fornecedor de pagamentos devolve quando um cartão é recusado. A maioria das equipas que já aluga um servidor acaba por executar uma ferramenta de cada tipo, iniciadas pelo mesmo ficheiro Docker Compose e revistas no mesmo pull request.

Por que hospedar internamente o mocking e os testes de APIs?

Os seus fixtures têm dados com a estrutura dos dados de produção. O corpo de um pedido num teste de API é um registo real de cliente com o nome alterado, ou com o nome inalterado porque ninguém o verificou. Os stubs gravados são ainda piores: a gravação através de um proxy armazena exatamente o que o upstream devolveu, por isso um diretório de stubs criado por gravação contém tokens ativos e endereços de email de clientes até alguém ler todos os ficheiros. Num serviço alojado, esses dados tornam-se um incidente de outra entidade e uma divulgação da sua responsabilidade.

A segunda razão é a acessibilidade. Um serviço ligado a um endereço privado precisa de uma ligação de rede privada antes de um runner alojado poder aceder-lhe. Cada solução alternativa tem um custo. Publicar a API na Internet para a testar elimina a razão pela qual ela era privada. Um túnel ou uma cópia pública de staging é outro sistema para manter, e uma cópia de staging fica divergente da produção entre releases. Os runners alojados pelo GitHub também permitem acesso privado através de uma overlay WireGuard ou de uma Azure Virtual Network. Um runner na mesma rede privada chama o serviço diretamente e não precisa de nada disso. Esse é o argumento prático por trás de um runner self-hosted do GitHub Actions.

Que servidor mock autoalojado deve executar?

Cada um destes servidores é executado como um contentor numa máquina que controla. A questão importante é qual trata como fonte de verdade, porque isso determina se recriar o contentor não custa nada ou custa uma tarde de trabalho.

  • WireMock mantém cada stub como um ficheiro JSON num diretório mappings/, com corpos de resposta grandes em __files/. A imagem é wiremock/wiremock, o diretório raiz dentro do contentor é /home/wiremock e também funciona como proxy de gravação. Os ficheiros em disco permitem manter o mock no git, como qualquer outro código.
  • Mockoon CLI mantém uma API mock completa num único ficheiro de dados JSON. Instale-o com npm install -g @mockoon/cli e inicie-o com mockoon-cli start --data ./data-file.json, ou execute a imagem mockoon/cli com esse ficheiro montado por bind. A aplicação de desktop edita o mesmo ficheiro, por isso é possível criar a configuração numa interface gráfica e fazer commit do resultado sem perder compatibilidade.
  • MockServer é executado a partir da imagem mockserver/mockserver e escuta na porta 1080. As expectativas são recebidas através da sua própria API REST, o que é útil a partir do código de testes, mas cria riscos na implementação: por predefinição, uma expectativa criada através de uma chamada HTTP desaparece quando o contentor reinicia. Use o ficheiro de inicialização JSON para stubs que devem ser permanentes. Para manter alterações feitas em runtime, ative persistExpectations, persista o ficheiro de saída fora do contentor e carregue-o através de initializationJsonPath no arranque.
  • Prism cria o mock a partir do seu documento OpenAPI, em vez de usar ficheiros de stubs separados. Instale-o com npm install -g @stoplight/prism-cli e execute-o com prism mock openapi.yaml. Num contentor, adicione -h 0.0.0.0, porque o Prism faz bind a localhost por predefinição e, caso contrário, não fica acessível a partir do exterior do contentor.
  • Microcks é a opção mais completa: uma interface Web que importa documentos OpenAPI e coleções Postman, depois disponibiliza-os como mocks e executa testes de contrato. Uma instalação completa precisa de MongoDB e Keycloak, além de Kafka para as funcionalidades assíncronas. A imagem microcks-uber tudo-em-um inclui um MongoDB em memória, que o projeto documenta como adequado para utilização efémera. Por isso, trate como descartável tudo o que for criado nessa interface e mantenha os artefactos de origem no git.

Qual executor de testes de API self-hosted deve utilizar?

O trabalho consiste numa sequência: autenticar, criar um pedido, lê-lo novamente e confirmar que o estado mudou. Para isso, é necessário capturar um valor de uma resposta e utilizá-lo no pedido seguinte. Uma ferramenta que não consegue manter o estado entre chamadas faz uma verificação de integridade, não um teste de API.

  • Hurl executa ficheiros de texto simples com pedidos HTTP a partir de um único binário. Uma secção [Captures] extrai valores de uma resposta, uma secção [Asserts] verifica-os e --test transforma o processo num executor de testes com um resumo e um código de saída. A versão 8.0.1 é a atual em agosto de 2026.
  • Bruno CLI executa uma pasta de ficheiros .bru. Instale-o com npm install -g @usebruno/cli e execute-o com bru run folder --env Local --reporter-junit results.xml. Por conceção, o formato da coleção consiste em ficheiros de texto num diretório, pelo que as diferenças são legíveis durante a revisão.
  • Newman executa coleções do Postman fora do Postman: npm install -g newman e, depois, newman run collection.json -r cli,junit --reporter-junit-export results.xml. O problema está no formato. O Newman executa coleções exportadas no formato JSON v2.1. Atualmente, o Postman também suporta um formato de coleção v3 e fluxos de trabalho Native Git através do Postman CLI. A documentação do Postman indica que o Newman não receberá mais atualizações nem correções e recomenda migrar os scripts e os pipelines de CI para o Postman CLI.
  • Schemathesis faz um tipo diferente de verificação. Lê um esquema OpenAPI e gera casos que tentam produzir respostas que o esquema indica serem impossíveis: uvx schemathesis run https://your.api/openapi.json. Encontra falhas e violações do contrato, mas não conhece as regras de negócio. Por isso, deve ser utilizado em conjunto com uma suite de testes baseada em scripts, não como substituto.
  • Hoppscotch self-hosted é a opção com interface web e requer uma instância de Postgres. Compreenda esta consequência antes de o instalar: as coleções ficam armazenadas numa base de dados, não no seu repositório.

Há uma opção a evitar. O Step CI continua a aparecer em listas de ferramentas e o seu formato de fluxo de trabalho YAML é legível, mas o repositório recebeu o último commit em agosto de 2024. Um programa colocado entre o seu CI e a sua API é um local inadequado para código sem manutenção.

Coloque o servidor simulado atrás da firewall

A configuração abaixo executa o WireMock como substituto de um fornecedor de pagamentos. Se o formato do ficheiro Compose for novo para si, Docker Compose num VPS explica os comandos de gestão do ciclo de vida assumidos nesta secção.

services:
  mock-payments:
    image: wiremock/wiremock:3.13.2
    command: ["--verbose"]
    volumes:
      - ./mocks/payments:/home/wiremock
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

O prefixo 127.0.0.1: da porta é a parte importante. Um 8080:8080 simples publica o servidor simulado em todas as interfaces, incluindo o seu IP público, e este continua acessível mesmo quando o ufw nega essa porta, porque o Docker encaminha o tráfego publicado através da tabela nat antes de este chegar às regras INPUT do ufw. Faça o bind ao endereço de loopback para manter a porta publicada acessível apenas a partir do host, usando a rede bridge predefinida do Docker no Engine 28.0.0 ou posterior. As versões mais antigas permitem que hosts na mesma rede de camada 2 acedam a portas publicadas no localhost. Fazer o bind a um endereço de uma interface privada continua a permitir o acesso a partir de redes que conseguem encaminhar tráfego para esse endereço.

O serviço em teste aponta depois para o servidor simulado. Quando o serviço é executado no mesmo projeto Compose, o URL base do servidor simulado é http://mock-payments:8080, porque o Compose resolve os nomes dos serviços na sua própria rede. Quando o serviço é executado no host, é http://127.0.0.1:8080. Defina esse valor através de uma variável de ambiente, nunca no código, para evitar que o URL de teste seja enviado para produção.

Os stubs ficam em ./mocks/payments/mappings/, um ficheiro JSON por stub.

{
  "request": {
    "method": "POST",
    "urlPath": "/v1/charges",
    "bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
  },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
  }
}

Inicie o serviço e confirme depois o que foi efetivamente carregado.

docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings

--wait aguarda até o contentor indicar que está saudável. Isto funciona porque a imagem WireMock fornece um HEALTHCHECK para o seu endpoint /__admin/health. A chamada mappings lista todos os stubs que o servidor leu. Se um stub criado por si não aparecer nessa lista, nunca foi carregado: confirme que o ficheiro está em mappings/, e não na raiz montada, e confirme que o JSON é válido.

Quando chega um pedido e nenhum stub corresponde, o WireMock responde com 404. Se encontrar uma correspondência próxima, o corpo começa por Request was not matched, seguido de uma diferença em relação ao stub mais próximo. Sem mapeamentos de stubs, o corpo é No response could be served as there are no stub mappings in this WireMock instance. Leia a diferença quando estiver presente antes de alterar qualquer coisa, porque ela identifica o campo exato que difere. Normalmente, trata-se de um caminho com /v1/charge, enquanto o stub indica /v1/charges.

Escreva o teste como uma sequência com estado transferido entre chamadas

Os ficheiros Hurl são texto simples. Instale o pacote deb a partir dos releases do projeto.

VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.deb

Uma suite que testa a sua própria API contra o mock está em tests/checkout.hurl.

POST {{base_url}}/orders
Content-Type: application/json
{
  "sku": "ssd-1tb",
  "amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"

GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"

O bloco [Captures] é o que transforma isto num teste de API, em vez de duas requisições não relacionadas. order_id é lido da primeira resposta e interpolado no URL da segunda. A asserção em charge_id é o objetivo de todo o exercício: prova que o seu serviço chamou o fornecedor de pagamentos e armazenou o que recebeu. O valor usado na comparação é o que escreveu no stub do WireMock. Um único ficheiro cobre agora as duas partes do fluxo.

hurl --test --variable base_url=http://127.0.0.1:3000 \
  --report-junit reports/junit.xml \
  --report-json reports/json \
  tests/

Uma execução bem-sucedida imprime uma linha por ficheiro e um resumo.

tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files:    1
Executed requests: 2 (30.1/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          64 ms

Uma falha imprime error: Assert failure com o ficheiro e o número da linha, depois o valor obtido e o valor esperado. Em seguida, hurl termina com um código diferente de zero, para que a CI seja interrompida. Se status ler pending quando esperava paid, o seu serviço não processou a resposta do mock. O próximo elemento a consultar é o diário de requisições do WireMock em /__admin/requests, que mostra se a chamada chegou ao mock.

Dispare o conjunto de testes a partir do seu próprio runner de CI

Com um runner registado na mesma máquina, o fluxo é curto. O runner é um processo comum no host, por isso docker e hurl têm de estar instalados nesse host. Nada é herdado de uma imagem alojada.

name: api-tests
on: [push]
jobs:
  hurl:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Start the mock
        run: docker compose up -d --wait mock-payments
      - name: Run the suite
        run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
      - name: Archive the reports
        if: always()
        run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
      - name: Stop the mock
        if: always()
        run: docker compose down

if: always() na etapa de arquivamento é importante. Sem essa opção, uma execução de testes falhada ignora a cópia, e perde exatamente o relatório que queria consultar. A cópia também tem de ser colocada fora do workspace, porque actions/checkout@v4 executa git clean -ffdx por predefinição antes de obter o código, removendo os relatórios não rastreados do diretório do repositório no checkout seguinte.

Conserve os resultados, não apenas a última execução

Um ficheiro XML JUnit por commit responde a uma pergunta: passou? Não responde a partir de quando um endpoint começou a ficar mais lento, porque nada lê esses ficheiros depois de deixar de os abrir. Para obter uma tendência, acrescente uma linha por execução a uma base de dados pequena no mesmo servidor. Uma única tabela com o SHA do commit, o nome do ficheiro, o número de testes aprovados, o número de testes falhados e a duração é suficiente. SQLite em produção num VPS é uma opção razoável: um ficheiro, nenhum processo de servidor e todo o histórico incluído na cópia de segurança que já faz. Analise a saída --report-json do Hurl para obter dados detalhados da execução; tanto JSON como XML JUnit são formatos legíveis por máquinas.

O que tem de sobreviver à reconstrução de um contentor

As definições dos mocks e as suites de testes são código-fonte. Devem ficar num repositório junto do serviço que descrevem e ser alteradas no mesmo pull request que altera um endpoint. Um stub editado numa interface Web, ou uma expectativa enviada ao MockServer através da respetiva API REST em runtime, precisa de uma exportação ou de uma configuração de persistência para sobreviver a uma reconstrução. Execute docker compose down e a memória do contentor e as camadas graváveis são perdidas; os dados armazenados em bind mounts ou named volumes sobrevivem. Se os seus repositórios também forem executados no seu próprio hardware, um servidor Git self-hosted mantém os fixtures e o serviço dentro do mesmo limite de confiança.

Seguem as regras práticas. Fixe as tags das imagens, porque latest pode alterar a forma como o seu mock corresponde aos pedidos sem qualquer alteração no repositório, e é muito difícil relacionar essa falha com a respetiva causa. Monte os diretórios de stubs como apenas de leitura quando a ferramenta não precisar de escrever neles. Nunca coloque os stubs de um mock num named Docker volume, porque o volume passa a ser a fonte de verdade e a cópia no Git fica silenciosamente desatualizada.

Há mais uma regra, que costuma causar problemas. Se criar stubs através da gravação de tráfego real por um proxy, leia todos os ficheiros gerados antes de os submeter. Uma gravação contém exatamente o que o upstream devolveu, incluindo bearer tokens e endereços de email de clientes. Ao submetê-la, coloca esses dados permanentemente no repositório, porque o Git mantém o conteúdo eliminado no histórico.

FAQ

Qual é a diferença entre um servidor mock de API e um executor de testes de API?

Um servidor mock responde a pedidos. Ele substitui uma dependência que não pode ser chamada a partir do CI; algumas ferramentas também executam testes de contrato e comunicam os respetivos resultados. Um executor de testes de API envia pedidos para o seu próprio serviço, valida as respostas, transporta valores de uma chamada para a seguinte e termina com código diferente de zero quando uma validação falha. Resolvem problemas diferentes e, numa configuração típica, são executados em simultâneo: o executor chama o seu serviço enquanto o seu serviço chama o mock.

Posso testar uma API interna a partir de um executor de CI alojado?

Sim, com uma rede privada. Os executors alojados pelo GitHub suportam uma sobreposição WireGuard ou uma Azure Virtual Network para aceder a recursos privados sem publicar a API. Publicar a API, executar um túnel ou manter uma cópia pública de staging são outras opções, mas cada uma acrescenta um sistema que pode falhar ou expor dados. Um executor na mesma rede privada chama o serviço diretamente. Essa é a principal razão prática para as equipas alojarem este trabalho na própria infraestrutura.

Onde devem ficar os stubs mock e as suites de testes de API?

No git, junto do serviço que descrevem. As ferramentas que armazenam definições como ficheiros, como o diretório mappings/ do WireMock, o ficheiro de dados do Mockoon, os ficheiros Hurl e a pasta .bru do Bruno, permitem revisão de código e uma reconstrução do contentor sem custo adicional. As ferramentas que armazenam definições numa base de dados ou numa interface web precisam de um plano de cópias de segurança e de uma etapa de exportação. A exportação é a parte que as pessoas esquecem até o contentor já ter desaparecido.

Porque é que o meu mock devolve 404 quando o stub parece correto?

O WireMock serve um stub apenas quando o pedido corresponde aos seus matchers configurados. Um pedido sem correspondência recebe 404; quando existe uma correspondência próxima, o corpo começa por Request was not matched, seguido de uma diferença em relação ao stub mais próximo, e essa diferença identifica o campo que diverge. Sem mapeamentos de stubs, o corpo explica que a instância não tem nenhum. As causas comuns incluem uma barra final no caminho, um cabeçalho Content-Type exigido pelo stub que o cliente não enviou, urlPath utilizado onde o stub precisa de urlPathPattern para um segmento variável e um matcher de corpo que não corresponde ao payload. Verifique primeiro /__admin/requests para confirmar que o pedido chegou ao mock.

Ainda preciso de mocks se tiver um ambiente de staging?

Sim, por dois motivos. Uma cópia de staging de um upstream que não controla também pode ficar indisponível e aplicar limites de pedidos. Nesse caso, a suite falha por motivos que não têm relação com o seu código. Além disso, o ambiente não consegue produzir as respostas que mais precisa de testar, como um cartão recusado ou um timeout do gateway. Um mock devolve essas respostas quando necessário e à velocidade da rede local. Assim, uma suite que demora minutos contra um sandbox pode demorar segundos. Mantenha o staging para a verificação final antes do release e use mocks no CI.

Este artigo foi útil?