Se você mantém um arquivo OpenAPI, mas seu serviço em execução se afasta lentamente dele, o Specmatic foi construído exatamente para essa lacuna. Ele trata sua especificação como um contrato executável, então testa um serviço real contra ela e executa a mesma especificação como um stub inteligente. Este guia explica o que o Specmatic faz, como o teste de contrato difere do teste baseado em exemplos e onde a ferramenta se encaixa, com uma nota sobre como ela se compara a uma abordagem de plataforma mais ampla como o teste de contrato de API do Apidog. Para o formato de especificação por trás de tudo isso, a Especificação OpenAPI é a fonte de verdade da qual o Specmatic lê.
O que é o Specmatic
Specmatic é uma ferramenta de código aberto para desenvolvimento orientado a contratos. A ideia central é simples: sua especificação de API é o contrato, e o Specmatic torna esse contrato executável. Aponte-o para um arquivo OpenAPI e ele pode realizar duas tarefas complementares.
- Execute a especificação como testes contra um serviço em tempo real, verificando se o serviço cumpre todos os caminhos, códigos de status e esquemas prometidos pela especificação.
- Execute a especificação como um servidor stub, para que os consumidores possam desenvolver contra um mock que responde exatamente como o contrato diz.
Ambas as tarefas leem o mesmo arquivo. Não há uma "definição de teste" e uma "especificação" separadas para manter sincronizadas, o que é o objetivo principal. O Specmatic também vai além do OpenAPI. A versão 2.0 adicionou GraphQL e gRPC, e ele suporta AsyncAPI para contratos de eventos estilo Kafka, além de formatos como WSDL e Avro. Para a maioria das equipes, porém, o ponto de entrada é um arquivo OpenAPI YAML ou JSON simples.
Você o executa a partir da linha de comando ou de uma imagem Docker, então ele se integra ao CI sem muita cerimônia. A empresa por trás dele oferece complementos comerciais, mas o motor de contrato em si é gratuito e de código aberto.
Teste de contrato vs. teste baseado em exemplos
Esta é a distinção que mais confunde as pessoas, por isso vale a pena ser preciso.
O teste baseado em exemplos é o que você faz na maioria dos clientes de API. Você escreve uma requisição, você verifica a resposta que recebeu, talvez você cheque um código de status e um ou dois campos. Cada teste é um exemplo escrito à mão. Se sua especificação tiver 40 endpoints, você escreve e mantém muitos exemplos, e lacunas são fáceis de serem perdidas.
O teste de contrato inverte o modelo. Em vez de verificar exemplos específicos, você verifica se o serviço corresponde ao contrato. O Specmatic lê o esquema e gera testes a partir dele. Ele verifica se as respostas estão em conformidade com os tipos declarados, se os campos obrigatórios estão presentes, se os códigos de status se alinham e se o serviço rejeita requisições malformadas da maneira que a especificação implica. Você não escreve as verificações uma por uma. A especificação é a verificação.
| Aspecto | Teste baseado em exemplos | Teste de contrato com Specmatic |
|---|---|---|
| Fonte da verdade | Casos de teste escritos à mão | A própria especificação OpenAPI |
| O que você mantém | Cada requisição e verificação | A especificação, que você já mantém |
| Cobertura | Apenas o que você lembrou de escrever | Cada operação declarada pela especificação |
| Detecção de desvio | Manual | Automática quando a especificação muda |
| Falha típica | Um exemplo específico quebrou | O serviço não corresponde mais ao contrato |
Há um segundo eixo que vale a pena nomear. O teste de contrato vem em diferentes sabores, e o Specmatic se encaixa em um específico. O teste de contrato orientado ao consumidor no estilo Pact tem os consumidores publicando suas expectativas em um broker, e os provedores verificam contra essas expectativas. O Specmatic faz o teste orientado a contratos: a especificação é o contrato único que ambas as partes concordam, e o Specmatic valida o provedor contra ele e simula o provedor para os consumidores. Não é um broker Pact, e não gerencia pactos publicados por consumidores. Se você deseja uma visão mais ampla, veja esta visão geral das ferramentas de teste de contrato e mocking de API.
Como o Specmatic funciona
Você pode instalar a CLI diretamente ou puxar a imagem Docker. Docker é a escolha comum em CI porque evita a configuração de tempo de execução local.
Executando testes de contrato
O comando de teste aponta o Specmatic para uma especificação e um serviço em execução. Uma execução local mínima se parece com isto.
# CLI Nativa
specmatic test api.yaml --testBaseURL=http://localhost:8080
# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
test api.yaml --testBaseURL=http://host.docker.internal:8080
O Specmatic lê `api.yaml`, gera requisições para as operações que descreve, as envia para a URL base e valida cada resposta contra o esquema. Um teste falho significa que o serviço e o contrato discordam. Você corrige um ou outro. Esse é o ciclo.
Executando a especificação como um stub
O servidor stub é a outra metade. Inicie-o e o Specmatic serve respostas que correspondem ao contrato, para que um front-end ou um serviço downstream possa desenvolver contra ele antes que o backend real exista.
specmatic stub api.yaml --port=9000
Por padrão, ele gera respostas válidas para o esquema em tempo real. Você também pode salvar exemplos concretos em um diretório `_examples` ao lado da especificação, e o stub retornará esses exemplos quando uma requisição corresponder. Isso oferece dados realistas e controláveis sem a necessidade de configurar um backend real. Se você estiver comparando opções de stub e mock entre ferramentas, o resumo de servidores mock e de teste de contrato coloca o Specmatic em contexto.
O Specmatic também pode ajudar você a criar a especificação em primeiro lugar. Ele pode atuar como um proxy na frente de um serviço existente, capturar tráfego real e gerar um documento OpenAPI mais arquivos de exemplo a partir do que ele vê. Isso é útil quando você tem um serviço, mas ainda não tem uma especificação.
O modelo de especificação como contrato e stub
É por isso que executar um único arquivo como teste e stub é importante. Quando a especificação é o contrato, o lado do teste e o lado do stub nunca podem discordar, porque eles leem o mesmo documento.
- A equipe do provedor executa `specmatic test` no CI. Se eles alterarem a API sem atualizar a especificação, os testes de contrato falharão.
- A equipe do consumidor executa `specmatic stub` localmente. Eles desenvolvem contra respostas que têm garantia de corresponder ao mesmo contrato.
Assim, a especificação se torna um acordo vivo, e não um documento obsoleto em que ninguém confia. Essa é a diferença entre um stub e um mock mais rico, e vale a pena entender as ideias subjacentes em stubbing vs. mocking de API antes de projetar um fluxo de trabalho em torno disso.
O Specmatic também adiciona verificação de compatibilidade com versões anteriores. O comando `backward-compatibility-check` inicia um stub a partir da nova versão de uma especificação, gera testes da versão anterior e os executa contra o novo stub. Se algo que costumava funcionar não funciona mais, você descobre antes de fazer o deploy. Essa é uma forte barreira de segurança para microsserviços que são implantados independentemente, e é um sabor da ideia mais ampla abordada no teste de contrato bidirecional.
Onde o Specmatic se encaixa
O Specmatic conquista seu lugar quando estas condições são verdadeiras para sua equipe:
- Sua especificação OpenAPI (ou AsyncAPI, GraphQL, gRPC) é real e razoavelmente completa.
- Você tem equipes ou serviços provedores e consumidores separados que precisam permanecer sincronizados.
- Você deseja que o desvio da especificação falhe em uma compilação automaticamente, e não seja detectado na revisão.
- Você se sente confortável com um fluxo de trabalho focado em CLI e CI.
É menos adequado se você não mantém uma especificação, se deseja um espaço de trabalho visual para projetar e explorar APIs, ou se deseja uma única ferramenta para lidar também com depuração ad hoc, documentação e colaboração em equipe. O Specmatic é focado no motor de contrato, e faz esse trabalho bem.
Esse foco também é onde uma plataforma como o Apidog assume uma forma diferente. O Apidog é orientado a esquemas da mesma forma: ele lê sua especificação OpenAPI, valida respostas contra o esquema e inicializa um servidor mock a partir de sua especificação OpenAPI sem código. A diferença honesta é o escopo. O Specmatic é uma ferramenta de contrato afiada e nativa da CLI. O Apidog integra design, teste, mocking e documentação em um único espaço de trabalho com um editor visual, para que a especificação, os testes e o mock vivam juntos e permaneçam sincronizados enquanto você trabalha. O Apidog também não é um broker de contrato orientado ao consumidor no estilo Pact, então se sua equipe precisa especificamente de um broker Pact, nenhuma das ferramentas é isso.
Se você deseja gerar testes executáveis diretamente de uma especificação dentro desse tipo de espaço de trabalho, veja como o Apidog lida com a geração de coleções de testes de API a partir de especificações OpenAPI.
Perguntas frequentes
O Specmatic é gratuito?
Sim. O motor de contrato central é de código aberto e gratuito para uso a partir da CLI ou Docker. Existem ofertas comerciais em torno dele, mas você pode executar testes de contrato e servidores stub a partir de especificações OpenAPI sem pagar. Verifique o site oficial e o GitHub para obter detalhes atuais sobre os níveis pagos.
O Specmatic funciona apenas com OpenAPI?
Não. OpenAPI é o ponto de entrada mais comum, mas o Specmatic também suporta AsyncAPI para contratos orientados a eventos, além de GraphQL e gRPC desde a versão 2.0, juntamente com formatos como WSDL e Avro. O modelo é o mesmo em todos eles: a especificação é o contrato executável. Se você é novo no formato, comece com este tutorial de Especificação OpenAPI.
O Specmatic é o mesmo que o Pact?
Não exatamente. Pact é orientado ao consumidor: os consumidores publicam expectativas em um broker e os provedores as verificam. Specmatic é orientado a contratos: a especificação é o contrato único compartilhado, e o Specmatic valida o provedor contra ele enquanto simula o provedor para os consumidores. Ambos reduzem surpresas de integração, mas organizam o contrato de forma diferente.
O Specmatic pode gerar uma especificação OpenAPI para mim?
Sim. O Specmatic pode ser executado como um proxy na frente de um serviço existente, capturar tráfego real de requisições e respostas, e gerar um documento OpenAPI mais arquivos de exemplo a partir dele. Isso é útil quando você tem um serviço funcionando, mas ainda não tem uma especificação formal para testar.
Conclusão
O Specmatic responde a um problema específico e real: manter um serviço em execução honesto em relação à especificação OpenAPI que ele deveria seguir. Ao tornar a especificação executável, ele oferece testes de contrato e um stub correspondente a partir de um único arquivo, com verificações de compatibilidade com versões anteriores. Se você vive no terminal e no CI e mantém uma especificação sólida, é um encaixe perfeito.
Se você preferir ter o contrato, os testes, o mock e a documentação em um único espaço de trabalho visual que lê o mesmo arquivo OpenAPI, experimente o Apidog. Ele valida respostas contra seu esquema, simula endpoints sem código e transforma especificações em coleções de testes executáveis. Baixe o Apidog para apontá-lo para sua especificação e ver o ciclo completo de design a teste em um só lugar.