DEV Community

Cover image for Karate para Testes de API: Guia Prático da DSL
Lucas
Lucas

Posted on • Originally published at apidog.com

Karate para Testes de API: Guia Prático da DSL

Você quer testes de API legíveis, versionados no Git junto com o código e executáveis em qualquer pipeline de CI. O Karate atende bem esse caso: ele usa uma DSL baseada em Gherkin para escrever cenários Dado / Quando / Então, sem exigir glue code em Java para testes HTTP comuns. Neste guia, você verá como estruturar arquivos .feature, configurar ambientes, escrever asserções JSON e rodar tudo em CI.

Experimente o Apidog hoje

O que é o Karate

Karate é um framework open source de automação de testes de API baseado em Java. Você escreve testes em arquivos .feature, usando a sintaxe Gherkin do Behavior-Driven Development, mas sem precisar implementar definições de steps como no Cucumber.

Um teste HTTP básico no Karate já vem com suporte nativo para:

  • montar requisições;
  • enviar métodos HTTP;
  • validar status codes;
  • comparar JSON;
  • usar matchers flexíveis como #string, #number e #[10];
  • executar testes por Maven, Gradle, JUnit 5 ou jar standalone.

Karate API testing

Além de testes de API, o projeto também inclui recursos para mocks, testes de performance com Gatling e automação de UI. Aqui, o foco é o núcleo de testes de API.

Como os testes são arquivos de texto, eles funcionam bem em um workflow baseado em código, nativo do Git. Um pull request mostra exatamente quais cenários, payloads ou asserções foram alterados.

Se você ainda não usa o estilo Dado / Quando / Então, veja também o guia sobre Behavior-Driven Development.

Como funciona: arquivos .feature e karate-config.js

Um teste Karate começa com um arquivo .feature. Cada arquivo possui uma Funcionalidade: e um ou mais Cenário:.

Exemplo mínimo:

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]'
Enter fullscreen mode Exit fullscreen mode

O fluxo é direto:

  1. url define a base da API.
  2. caminho adiciona o recurso.
  3. método get envia a requisição.
  4. status 200 valida o HTTP status.
  5. match response == '#[10]' verifica que a resposta é um array com 10 itens.

O marcador #[10] é próprio do Karate. Ele valida o tamanho do array sem exigir código JavaScript.

Para entender melhor a sintaxe Gherkin aplicada a APIs, consulte o guia Gherkin para BDD e testes de API.

Configurando ambientes com karate-config.js

Em projetos reais, você normalmente precisa alternar entre ambientes como dev, qa, staging e prod. O Karate centraliza isso no arquivo karate-config.js.

Crie um arquivo assim na raiz dos testes:

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;
}
Enter fullscreen mode Exit fullscreen mode

Agora, no arquivo .feature, use a variável baseUrl:

Funcionalidade: API de Usuário

Background:
  * url baseUrl

Cenário: Listar usuários
  Dado caminho 'users'
  Quando método get
  Então status 200
Enter fullscreen mode Exit fullscreen mode

Para trocar o ambiente em tempo de execução:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Assim, você evita hardcode de URLs nos cenários.

Exemplo prático: criando um usuário

Este cenário envia um payload JSON, valida o status code e verifica 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'
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • Background: roda antes de cada cenário do arquivo.
  • * é um step curinga, útil para configuração.
  • requisição recebe JSON diretamente.
  • #string valida que id existe e é uma string, sem fixar um valor específico.

Esse estilo reduz boilerplate: não há DTO, POJO, serializer ou código de setup HTTP.

Asserções e comparação de JSON

A principal palavra-chave para validação no Karate é match.

Comparação exata 

E match response == { id: '#number', name: 'Ada', job: 'engineer' }
Enter fullscreen mode Exit fullscreen mode

Aqui, o objeto precisa ter os campos esperados. Os matchers flexíveis validam tipos:

  • #number: número;
  • #string: string;
  • #boolean: booleano;
  • #uuid: UUID.

Isso é útil para campos gerados dinamicamente, como IDs e timestamps.

Comparação parcial com contains

Quando você só precisa validar parte da resposta:

E match response contains { name: 'Ada' }
Enter fullscreen mode Exit fullscreen mode

O teste passa mesmo que a resposta tenha outros campos.

O Karate também suporta:

E match response !contains { error: true }
E match response contains only { name: 'Ada', job: 'engineer' }
E match response contains any [{ name: 'Ada' }, { name: 'Grace' }]
E match response contains deep { user: { name: 'Ada' } }
Enter fullscreen mode Exit fullscreen mode

Validação de arrays

Para validar o tamanho de um array:

E match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

Para validar cada item do array:

E match each response == { id: '#number', name: '#string' }
Enter fullscreen mode Exit fullscreen mode

Essa linha verifica que todos os objetos retornados possuem id numérico e name string.

Para mais padrões de validação, veja o guia prático de asserções de API.

Testes orientados a dados

Para executar o mesmo cenário com múltiplas entradas, use Cenário com Estrutura e Exemplos.

Funcionalidade: Criar usuários

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   |
Enter fullscreen mode Exit fullscreen mode

O Karate executa o cenário uma vez para cada linha da tabela.

Para manter dados grandes fora do .feature, leia um arquivo externo:

Exemplos:
  | read('classpath:test-data/users.json') |
Enter fullscreen mode Exit fullscreen mode

O Karate suporta JSON e CSV para esse tipo de execução orientada a dados.

Rodando Karate em CI

Você tem duas opções comuns para executar Karate em pipelines.

Opção 1: Maven, Gradle e JUnit 5

Em projetos Java, adicione a dependência karate-junit5 e crie um runner apontando para os arquivos .feature.

A vantagem é que seu pipeline continua simples:

mvn test
Enter fullscreen mode Exit fullscreen mode

ou:

gradle test
Enter fullscreen mode Exit fullscreen mode

Isso encaixa os testes de API no mesmo fluxo dos testes automatizados existentes.

Opção 2: jar standalone

Se você não quer usar Maven ou Gradle, baixe o karate.jar nos releases do projeto e execute os testes diretamente:

java -jar karate.jar src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Para filtrar por tags, executar em paralelo e definir diretório de saída:

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Para passar o ambiente:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Após a execução, o Karate gera um relatório HTML no diretório de saída, útil como artefato de CI.

Para uma visão mais ampla sobre pipelines, veja como automatizar testes de API em CI/CD.

Pontos fortes e compensações

O Karate funciona bem quando você quer:

  • testes versionados no Git;
  • cenários legíveis;
  • validação JSON com pouco boilerplate;
  • execução headless em CI;
  • uma abordagem code-first para testes de API.

As principais compensações:

  • exige Java instalado;
  • a DSL precisa ser aprendida;
  • reutilização avançada pode exigir JavaScript ou interoperabilidade Java;
  • pessoas não desenvolvedoras podem ter dificuldade para criar e manter cenários.

Ou seja: o Karate é forte para times que tratam testes como código e querem manter a suíte próxima da aplicação.

Karate vs uma abordagem sem código com Apidog

O Karate é baseado em código: você escreve arquivos .feature, versiona no Git e executa por build tool ou jar.

O Apidog segue uma abordagem visual e sem código. Você cria cenários na UI, encadeia requisições e adiciona asserções por configuração, sem escrever DSL.

Como o ciclo de vida da API fica no mesmo lugar — design, depuração, mocking, documentação e testes — os testes podem reutilizar endpoints e esquemas já definidos. Isso reduz a barreira para QA, produto e outras pessoas que não querem manter um projeto Java.

Apidog API testing

As suítes visuais também podem rodar em CI com o Apidog CLI.

Instale com Node:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Execute um cenário ou suíte salvo por ID:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Principais flags:

  • -t: cenário, pasta ou suíte;
  • -e: ambiente;
  • -r: reportadores, como cli, html, json e junit;
  • -d ou --iteration-data: arquivo ou ID de dados de teste para execução orientada a dados.

O Apidog CLI é headless e roda em qualquer CI com Node. Ele executa cenários salvos no Apidog; não é um remetente interativo de requisições nem um gerador de carga.

Veja mais em Apidog CLI para CI/CD e na comparação Apidog CLI vs Newman.

A diferença principal é o estilo de autoria:

  • Karate: DSL em arquivos versionados no Git.
  • Apidog: criação visual com execução headless em pipeline.

Como escolher

Escolha Karate se:

  • seu time é majoritariamente desenvolvedor;
  • vocês já usam Java/JVM;
  • testes devem viver no Git junto com o código;
  • a equipe quer controle detalhado por DSL;
  • a suíte será mantida como código.

Escolha uma ferramenta sem código como o Apidog se:

  • QA e produto também precisam criar ou editar testes;
  • você quer conectar testes com design e documentação de API;
  • prefere evitar um projeto Java só para validar APIs;
  • precisa manter execução em CI via CLI.

Algumas equipes usam os dois: Karate para regressões profundas mantidas por engenharia e uma ferramenta visual para cobertura ampla que mais pessoas conseguem estender.

Se você ainda está comparando opções, veja como escolher um framework de teste de automação de API.

Perguntas frequentes

Preciso saber Java para usar o Karate?

Não para escrever testes básicos de API. Os arquivos .feature usam a DSL do Karate com sintaxe Gherkin. Você precisa ter Java instalado para executar os testes, e conhecimento de Java ou JavaScript ajuda em helpers e reutilização avançada.

Qual é a diferença entre Karate e Cucumber?

Ambos usam Dado / Quando / Então. No Cucumber, você normalmente implementa o código das definições de steps. No Karate, os steps HTTP e asserções já vêm prontos para testes de API.

O Karate pode rodar sem Maven ou Gradle?

Sim. Use o karate.jar standalone:

java -jar karate.jar <caminho>
Enter fullscreen mode Exit fullscreen mode

Ele suporta tags, paralelismo e diretório de saída personalizado.

O que significam #string, #number e #[10]?

São matchers flexíveis do Karate. #string valida uma string, #number valida um número e #[10] valida um array com 10 itens.

Testes de API sem código ainda podem rodar em CI?

Sim. Uma ferramenta visual como o Apidog pode executar cenários salvos via Apidog CLI em qualquer pipeline com Node. Assim, você cria os testes na UI e mantém execução automatizada em CI.

Top comments (0)