Karatê DSL: Automatizar Testes de APIs

Recentemente tive a oportunidade de utilizar o Karatê DSL para automatizar os testes de API. Neste post, vou contar como foi a minha experiência utilizando esta DSL desenvolvida em Java e com a missão de simplificar o desenvolvimento de testes automatizados de APIs.

O que é o Karatê DSL

O Karate DSL é uma ferramenta desenvolvida em Java que permite o desenvolvimento e execução de testes de APIs utilizando uma sintaxe semelhante a do Gherkin. Ela foi disponibilizada recentemente (a pouco mais de dois anos) e vem crescendo em popularidade desde então:

Basicamente, esta ferramenta pode ser utilizada de duas formas

• Como biblioteca em um projeto Java (Maven ou Gradle)
• Como arquivo executável (standalone), fazendo download direto no site

Sintaxe baseada no Gherkin

Dado que esta ferramenta utiliza uma sintaxe semelhante ao Gherkin, os testes são implementados em um arquivo de com uma extensão “.feature”.

Logo, podemos utilizar as seguintes palavras chaves:

• Feature
• Background
• Scenario
• Scenario Outline / Examples
• Given / When / Then / And
• * — (sim, um asterisco, que serve como coringa)

Importante: Karatê não é BDD!

Apesar de ser baseado no Gherkin, os steps/cenários descritos com esta ferramenta seguem uma abordagem mais imperativa, ou seja, descrevem como as requisições são feitas, e não o que elas fazem. Em outras palavras, a linguagem utilizada nas features acaba sendo muito mais técnica do que de negócio.

Principais comandos da ferramenta

Para o desenvolvimento dos testes, a ferramenta dispõe de alguns comandos pré-definidos, descritos no formato de steps. Os principais comandos utilizados são:

• url ‘parametro’
• path ‘parametro’
• request ‘payload’
• method ‘método http’
• status ‘status http’
• param ‘nome query param’ = ‘valor do query param’
• header ‘nome header’ = ‘valor do header’
• response
• match ‘expressao’
• set payload.valor
• remove payload.valor
• def ‘nome da variavel’ = ‘valor da variavel’
• print ‘conteudo’
• read
• call read

Obs.: cada tópico possui link direto para a sua seção na documentação.

Execução no modo standalone

Uma vez criadas features com os cenários de testes, podemos executá-las com a ajuda do karate.jar. O comando base para execução dos testes é:

> java -jar karate.jar diretorioComAsFeatures

Nesse formato de execução, podemos combinar outros comandos para:

• filtrar os testes desejados por tags: -t ou — tags
• executar os testes em paralelo: -T ou — threads
• dentre outros (confira o — help ou aqui)

Ao final da execução dos testes, será gerado um relatório com o resultado da execução no diretório target/cucumber-html-reports. Por padrão, o nome do arquivo é overview-features.html e deve ser aberto no navegador.

Sugestão de estrutura de projeto:

├── data

│ ├── payload1.json

│ └── payload2.json

├── features

│ ├── MinhaFuncionalidade.feature

│ ├── NossaFuncionalidade.feature

│ ├── VossaFuncionalidade.feature

│ └── BossaFuncionalidade.feature

├── karate.jar

└── utils

├── funcionalidadeUtil.feature

└── funcaoJavascriptUtil.json

Explicação da estrutura:

No diretório data ficam os arquivos com exemplos de payloads, contratos, e quaisquer outros arquivos com dados que serão utilizados durante o teste.

No diretório features ficam os arquivos de features, com a implementação dos cenários de testes. Caso necessário, podem ser criados sub-diretórios a partir deste para facilitar a organização.

No diretório utils ficam os arquivos com funções utilizadas em mais de um cenário de teste, como: features para autenticação, funções para gerar números aleatórios, função para capturar data atual, etc.

Por fim, o arquivo executável karate.jar é o responsável por executar os testes criados e gerar o relatório com o resultado da execução dos testes.

Importante: Apesar de ser um executável, não é necessário abrir este arquivo. Podemos executar os testes diretamente via linha de comando.

Existe ainda o diretório target com os artefatos gerados pelo teste como: relatórios, logs, etc.. Este é gerado automaticamente após a execução do teste.

Criando o primeiro teste

Vamos a um passo a passo, para criar e executar o primeiro teste. Por ser um mais simples, utilizaremos o modo standalone:

1.  Faça download da última versão do karate.jar, disponível na página de releases da ferramenta: https://github.com/intuit/karate/releases
2. Crie uma nova pasta/diretório, e copie o executável para esta pasta. Sugestão: renomeie o executável para karate.jar;
3. Dentro de sua nova pasta, crie duas subpastas: features e data;
4. Acesse a pasta features, crie um novo arquivo, e salve com a extensão .feature;
5. Adicione o trecho abaixo no novo arquivo de feature e salve;
6. Via linha de comando, acesse sua pasta principal (a que possui o executável e as pastas feature e data) e execute o seguinte comando: java -jar karate.jar features/
7. Após executar a feature via linha de comando, verifique se foi criada uma nova pasta chamada target/
8. Acesse o relatório gerado em target/cucumber-html-reports, abrindo o arquivo overview-features.html no navegador.

Pronto! Agora é só implementar mais cenários de testes 🙂

Arquitetura

A arquitetura da ferramenta utiliza Maven e é desenvolvida em Java. Possui classes (diversas) auxiliares para lidar com JSON, XML, Protocolo HTTP, leitura de arquivos, parametrização, execução paralela, dentre outras funcionalidades. 

Assim como projetos que utilizam Cucumber, possui uma camada que expõe suas funções através de steps. As semelhanças com Cucumber param por aqui, uma vez que as versões mais recentes possuem engine própria para interpretar/executar as features.

Na imagem abaixo, temos uma ilustração simplificada da arquitetura:

Outros recursos interessantes

Além das funcionalidades e suporte padrão que, em geral, grande parte das ferramentas para testes de APIs possuem, o Karate DSL possui alguns recursos que podem auxiliar no desenvolvimento de novos testes, como:

• Execução de testes em paralelo
• Re-uso de features, payloads e arquivos
• Suporte para GraphQL
• Interoperabilidade com código Java e Javascript (puro)
• Cobertura de código
• Plugin para o VSCode

Curva de aprendizado da ferramenta

Assim como qualquer tecnologia ou ferramenta nova, é importante considerar alguns pontos antes de adotá-la em algum projeto. Um destes é sobre a curva de aprendizado da ferramenta. No caso do Karate DSL, a melhor definição resposta é que depende.

Se você têm conhecimentos de: Maven, Cucumber, Java e sabe um pouco sobre executar testes via linha de comando, o start na escrita dos testes é extremamente simples, seguindo apenas alguns comandos básicos.

Após isso, é necessário investir um tempo médio no entendimento da ferramenta, seus comandos e suas sintaxes. Grande parte dos recursos possuem alternativas simples para a escrita dos primeiros testes. Para validações um pouco mais complexas, é necessário um pouco mais de leitura e busca por exemplos na documentação e por vezes isso não é tão trivial.

Por fim, em alguns cenários é necessário utilizar recursos avançados e complexos da ferramenta, como interoperabilidade em Java & Javascript ou requisições com paginação. Nestes casos, inevitavelmente é necessário conhecer as linguagens de programação, como integrar as funções e classes no projeto, além de entender como reaproveitar estes recursos no script de testes. Considero esta etapa do aprendizado a mais trabalhosa.

Conclusão

O Karate DSL é uma ferramenta relativamente recente e surpreende pela facilidade de criação dos primeiros testes. Pode, e tem sido, uma excelente ferramenta para testes em alguns projetos e, além disso, é um bom caminho de entrada para quem deseja conhecer uma ferramenta a mais para automatizar testes de APIs. Em alguns momentos, a complexidade exigida para algumas tarefas frustra, visto que ela não é uma linguagem de programação e que a expectativa quanto a simplicidade na criação dos testes é bem alta.

---

Projetos de exemplo:

• Projeto no Gitlab
• Projeto no Github