Você quer testes de API que sejam legíveis como inglês simples, que vivam no Git ao lado do seu código e que rodem em qualquer pipeline de CI. O Karate foi construído exatamente para isso. Ele usa uma linguagem de domínio específico (DSL) para que você escreva testes como etapas Dado / Quando / Então em vez de métodos Java. Este guia explica o que é o Karate, como funcionam seus arquivos de feature e um exemplo executável.
O Que É o Karate
Karate é um framework de automação de testes de API de código aberto, baseado em Java. Você descreve cada teste como um cenário em um arquivo .feature usando Gherkin, a mesma estrutura Dado/Quando/Então que vem do Desenvolvimento Orientado a Comportamento (Behavior-Driven Development). A diferença para ferramentas como Cucumber é que você não escreve código de cola (glue code) para a definição das etapas. O Karate já vem com etapas HTTP, asserções e manipulação de JSON integradas, de modo que um teste de API funcional não precisa de Java.
O projeto inclui mais do que apenas testes de API. O repositório contém módulos para mocks, testes de performance (via Gatling) e automação de UI. Para este guia, o foco é o núcleo de testes de API, que é o que a maioria das equipes procura primeiro.
Como os testes são arquivos de texto simples, eles versionam bem. Um diff de pull request mostra exatamente qual asserção foi alterada. Isso funciona bem com revisões de código e com um workflow baseado em código, nativo do Git.
Se você é novo no estilo Dado/Quando/Então, nosso guia sobre Behavior-Driven Development explica de onde ele vem e por que as equipes o utilizam.
Como Funciona: Arquivos de Feature e karate-config.js
Um teste Karate começa com um arquivo de feature. Cada arquivo tem um bloco Funcionalidade: e um ou mais blocos Cenário:. Dentro de um cenário, você configura a requisição com Dado, a executa com Quando e faz as asserções com Então.
Funcionalidade: API de Usuário
Cenário: Listar todos os usuários
Dado url 'https://jsonplaceholder.typicode.com'
E caminho 'users'
Quando método get
Então status 200
E match response == '#[10]'
Leia de cima para baixo. url define o endereço base. path anexa o recurso. method get envia a requisição. status 200 verifica o código HTTP. A última linha afirma que a resposta é um array JSON com exatamente 10 itens. O #[10] é um marcador do Karate, não JavaScript. Mais sobre esses marcadores na seção de asserções.
O Gherkin aqui é o padrão Dado/Quando/Então. Se você quiser uma análise mais aprofundada dessa sintaxe, consulte nosso guia Gherkin para BDD e testes de API.
A maioria dos projetos precisa de valores específicos do ambiente: uma URL base de desenvolvimento, um token de staging, um endpoint de produção. O Karate lida com isso com um único arquivo chamado karate-config.js. Ele é executado uma vez antes dos seus testes e retorna um objeto de configuração que todo cenário pode ler.
function fn() {
var env = karate.env || 'dev';
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
if (env === 'qa') {
config.baseUrl = 'https://qa.example.com';
}
return config;
}
karate.env vem de uma propriedade do sistema que você passa em tempo de execução. Mude de ambiente sem tocar em um único arquivo de feature. Em um cenário, você escreveria Dado url baseUrl em vez de codificar o endereço.
Um Exemplo de Cenário
Vamos escrever algo com um corpo de requisição. Este cenário cria um usuário, verifica o status e valida a forma da resposta.
Funcionalidade: Criar usuário
Background:
* url baseUrl
Cenário: Criar um novo usuário retorna 201
Dado caminho 'users'
E requisição { name: 'Ada', job: 'engineer' }
Quando método post
Então status 201
E match response.name == 'Ada'
E match response.id == '#string'
Algumas coisas a notar. O bloco Background: é executado antes de cada cenário no arquivo, então você define a URL base uma vez. O * é uma etapa curinga; o Karate trata * da mesma forma que Dado, Quando ou Então, o que permite escrever etapas de configuração sem se preocupar com a gramática. A palavra-chave request aceita um payload JSON diretamente. Sem serializador, sem POJO. E #string é um matcher difuso que afirma que o campo id existe e é uma string, sem fixá-lo a um valor específico.
Asserções e Comparação de JSON
As asserções são onde o Karate se destaca. A palavra-chave principal é match. Ela compara um valor real com um valor esperado e falha o teste em caso de qualquer incompatibilidade.
Comparação exata verifica a igualdade:
E match response == { id: '#number', name: 'Ada', job: 'engineer' }
Os tokens #number, #string, #boolean e #uuid são matchers difusos. Eles afirmam o tipo e a presença sem exigir um valor literal, o que mantém os testes estáveis quando o servidor retorna IDs gerados ou timestamps.
Quando você se importa apenas com um subconjunto de campos, use contains:
E match response contains { name: 'Ada' }
Isso passa contanto que name seja igual a Ada, mesmo que a resposta tenha dez outros campos. O Karate também suporta !contains, contains only, contains any e contains deep para um controle mais preciso sobre a comparação parcial.
Você também pode validar arrays. match response == '#[10]' afirma um array de comprimento 10. Você pode aplicar um esquema a cada elemento com each:
E match each response == { id: '#number', name: '#string' }
Esta única linha verifica que cada objeto no array tem um id numérico e um name string. Esse tipo de validação de forma levaria um loop e várias asserções em um framework de teste de propósito geral. Se você quiser uma visão mais ampla sobre a validação de respostas, nosso guia prático de asserções de API aborda os padrões em várias ferramentas.
Testes Orientados a Dados e CI
Suítes de testes reais executam a mesma lógica contra muitas entradas. O Karate lida com isso usando Scenario Outline e uma tabela Examples. Os placeholders entre colchetes angulares são preenchidos a partir de cada linha.
Cenário com Estrutura: Criar usuários a partir de uma tabela
Dado url baseUrl
E caminho 'users'
E requisição { name: '<name>', job: '<job>' }
Quando método post
Então status 201
E match response.name == '<name>'
Exemplos:
| name | job |
| Ada | engenheira |
| Grace | cientista |
| Alan | analista |
Isso executa o cenário três vezes, uma para cada linha. Você também pode ler linhas de um arquivo externo em vez de uma tabela inline, o que mantém grandes conjuntos de dados fora dos seus arquivos de feature:
Exemplos:
| read('classpath:test-data/users.json') |
O Karate lê arquivos JSON e CSV dessa forma, para que seus dados de teste possam residir onde sua equipe preferir gerenciá-los.
Para integração contínua, você tem dois caminhos. Em um projeto Maven ou Gradle, o Karate é executado via JUnit 5. Você adiciona a dependência karate-junit5 e aponta um executor para seus arquivos de feature, de modo que mvn test os executa como qualquer outro teste de unidade. Isso significa que sua etapa de CI existente não precisa de nenhuma ferramenta especial.
O segundo caminho é o jar standalone, que não precisa de ferramenta de build. Baixe o karate.jar dos releases do projeto e execute os arquivos de feature diretamente. Note que o jar requer uma versão recente do Java, então verifique as notas de lançamento para o requisito mínimo.
java -jar karate.jar src/test/java/features
Você pode filtrar por tag, executar em paralelo e escolher um diretório de saída:
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Passe um ambiente com uma propriedade de sistema, que é propagada para karate.env dentro de karate-config.js:
java -jar karate.jar -Dkarate.env=qa src/test/java/features
O Karate gera um relatório HTML no diretório de saída após cada execução, facilitando a inspeção de falhas em um artefato de pipeline. Para uma visão mais ampla de CI, veja como automatizar testes de API em CI/CD.
Pontos Fortes e Compensações
O Karate tem pontos fortes claros. Os testes são legíveis quase como inglês simples, o que diminui a barreira para pessoas que não são fluentes em Java. A comparação de JSON integrada, incluindo matchers difusos e each, remove muito do código repetitivo das asserções. Tudo vive em arquivos de texto sob o Git, então os testes podem ser revisados e comparados (diff) como código-fonte. E ele cobre mais do que HTTP, então uma equipe pode adicionar mocks ou testes de performance mais tarde sem mudar de ferramenta.
As compensações também são reais. O Karate roda na JVM, então você precisa ter Java instalado e um certo nível de conforto com o ecossistema da JVM para qualquer coisa além do básico. A DSL é algo próprio para aprender; a sintaxe é fácil de ler, mas escrever matchers corretos e padrões de reutilização exige prática. Lógica reutilizável, helpers personalizados e configurações complexas muitas vezes o levam de volta a funções JavaScript ou interoperabilidade Java. E como os testes são código, não-desenvolvedores na equipe geralmente não conseguem criá-los ou editá-los sem ajuda.
Nada disso é uma crítica. É o perfil de um framework que prioriza o código. A questão é se esse perfil corresponde à forma como sua equipe deseja trabalhar.
Karate vs uma Abordagem Sem Código (Apidog)
O Karate é baseado em código e nativo do Git. Você escreve arquivos de feature, os commita e os executa a partir de uma ferramenta de build ou do jar. Isso se adequa a engenheiros que desejam testes em controle de versão ao lado do aplicativo e que se sentem confortáveis com a JVM.
O Apidog adota um caminho visual e sem código para o mesmo objetivo. Você constrói cenários de teste em uma UI, encadeia requisições e adiciona asserções clicando em vez de escrever DSL. Como todo o ciclo de vida da API (design, depuração, mocking, documentação) vive em um só lugar, os testes podem reutilizar os endpoints e esquemas que você já definiu. Isso diminui a barreira para engenheiros de QA e pessoas de produto que não querem gerenciar um projeto Java.
As suítes visuais não ficam presas na UI. O Apidog as executa em modo headless em CI através do Apidog CLI, de modo que uma suíte sem código ainda se encaixa em um pipeline automatizado. Você o instala com Node:
npm install -g apidog-cli
Em seguida, acione um cenário ou suíte salvo por ID, apontando para um ambiente e escolhendo os formatos de relatório:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
A flag -t direciona um cenário, pasta ou suíte; -e seleciona o ambiente; -r escolhe um ou mais reportadores (cli, html, json, junit). Para execuções orientadas a dados, -d (ou --iteration-data) recebe um caminho de arquivo de dados ou um ID de dados de teste. O CLI é headless e executa em qualquer etapa de CI que possa rodar Node. Ele executa seus cenários Apidog salvos; não é um remetente de requisições interativo ou um gerador de carga. Veja um guia completo em Apidog CLI para CI/CD, e uma comparação lado a lado com outro executor em Apidog CLI vs Newman.
Ambas as abordagens produzem testes de API automatizados que são executados em modo headless em CI. A diferença está no estilo de autoria: o Karate quer que você escreva DSL no Git; o Apidog quer que você clique em uma UI que também exporta para o pipeline.
Como Escolher
Escolha o Karate quando sua equipe for predominantemente desenvolvedora, confortável com a JVM e desejar testes versionados como código ao lado do aplicativo. Os arquivos de feature em texto simples e a comparação de JSON integrada compensam quando os engenheiros são responsáveis pela suíte de testes de ponta a ponta.
Escolha uma ferramenta sem código como o Apidog quando os autores incluírem pessoas de QA e produto, quando você quiser que os testes estejam ligados a um workflow existente de design e documentação, ou quando preferir não manter um build Java para executar verificações de API. Você ainda obtém cobertura de CI através do CLI.
Algumas equipes usam os dois: Karate para suítes de regressão profundas e de propriedade do código, e uma ferramenta visual para cobertura ampla e rápida que não-desenvolvedores podem estender. Se você ainda está ponderando as opções, nossa visão geral de como escolher um framework de teste de automação de API apresenta os critérios de decisão.
Perguntas Frequentes
Preciso saber Java para usar o Karate? Não, não para escrever testes de API básicos. Os arquivos de feature usam a DSL do Gherkin, e o Karate já vem com as etapas HTTP e de asserção integradas. Você precisará ter Java instalado para executar os testes, e algum conhecimento de Java ou JavaScript ajuda quando você precisar de helpers personalizados ou reutilização complexa.
Qual a diferença entre Karate e Cucumber? Ambos usam a sintaxe Dado/Quando/Então do Gherkin. Com o Cucumber, você escreve o código de definição das etapas para apoiar cada passo. O Karate fornece as etapas de teste de API para você, então não há código de cola para manter em testes HTTP padrão.
O Karate pode rodar sem Maven ou Gradle? Sim. Baixe o karate.jar standalone dos releases do projeto e execute os arquivos de feature com java -jar karate.jar <caminho>. Ele suporta tags, threads paralelas e um diretório de saída personalizado sem a necessidade de nenhuma ferramenta de build.
O que significam as sintaxes #string ou #[10]? São os matchers difusos do Karate. #string afirma que um campo é uma string de qualquer valor, #number um número, e #[10] afirma um array JSON de comprimento 10. Eles permitem validar a forma da resposta sem codificar valores gerados.
Testes de API sem código ainda podem ser executados em CI? Sim. Uma ferramenta visual como o Apidog exporta cenários salvos para o Apidog CLI, que é headless e roda em qualquer etapa de CI com Node. Assim, você cria testes em uma UI e ainda obtém execuções automatizadas em pipeline.