Quando o assunto é frameworks para NodeJS, não é novidade que o AdonisJS é uma opção bem completa – especialmente para aplicações monolíticas. Afinal, ele oferece de forma nativa várias ferramentas que facilitam o processo de desenvolvimento, além de possuir uma documentação clara, objetiva e intuitiva.

Em abril de 2022, houve uma release que deixou esse framework ainda mais incrível – principalmente se você curte desenvolver ‘à la’ TDD (Desenvolvimento Orientado a Testes):

Agora o AdonisJS possui suporte para testes automatizados!

Antes desta release, o AdonisJS já suportava integração com testes automatizados, mas o desenvolvedor precisava realizar instalações e configurações à parte. Havia até um artigo na seção Cookbooks da documentação explicando quais dependências instalar e como configurar tudo para executar os testes.

Mas agora isso é passado, porque desde abril de 2022, toda aplicação inicializada traz arquivos com configurações padrão para testes, e a documentação possui uma seção dedicada aos testes automatizados.

Conforme consta na descrição da release mostrada na imagem acima, o framework utilizado para executar os testes é o Japa. Então, vamos falar um pouco sobre ele destacando algumas features e explicar como o AdonisJS o utiliza.

AdonisJS + Japa

O Japa é um framework para testes que se descreve como sendo API-first e Node-only. Ou seja, ele é focado em testes para desenvolvimento de API`s no ambiente backend NodeJS. Esse framework tem a vantagem de ser extensível – o desenvolvedor pode instalar alguns plugins de acordo com as necessidades do projeto e até mesmo estender classes pré-existentes para atender às necessidades do projeto.

O Japa pode ser utilizado em qualquer projeto com NodeJS. Para isso, basta seguir as orientações de instalação e configuração da documentação (que também é de qualidade). Porém, ao criar um projeto AdonisJS, o desenvolvedor observará os seguintes arquivos-padrão:

tests/bootstrap.ts

Este arquivo armazenado dentro do diretório tests contém uma série de configurações que irão reger o processo de escrita e execução dos testes. Por exemplo, aqui cada desenvolvedor deve escolher quais plugins (suportados pelo Japa) serão utilizados durante os testes.

assert()

O Japa proporciona a liberdade de escolher plugins para escrever os testes utilizando a sintaxe de acordo com a preferência do desenvolvedor. Para aqueles que preferem usar a sintaxe do Chai (Assert), o Adonis adiciona o plugin assert() por padrão ao array plugins. Entretanto, se alguém optar pela sintaxe Jest, basta trocar o plugin por expect().

runFailedTests()

Outro plugin que vem definido por padrão é o runFailedTests(). Qual a sua função? Imagine que você escreveu 10 testes até o momento e os executou pela primeira vez.

Nessa primeira execução, dois testes falharam. Então, você faz alguns ajustes no código de produção e executa os testes pela segunda vez. Se runFailedTests() estiver no array de plugins, o Japa irá executar apenas os dois testes que falharam anteriormente. Caso desejar sempre executar todos os testes, basta remover o plugin do array.

apiClient()

Para testar os endpoints de uma API, o Japa oferece o plugin apiClient() – uma API completa, com inúmeras funções para simular requisições HTTP. É possível simular rotas protegidas por autenticação, rotas que esperam receber dados de um formulário, upload de arquivos, dados em JSON e muito mais. Vale a pena se familiarizar com esse plugin!

specReporter()

Também dentro do arquivo bootstrap.ts, mas desta vez dentro do array reporters, há um plugin do Japa chamado specReporter() registrado por padrão. Ele é responsável por apresentar, no terminal, informações detalhadas sobre o progresso e os resultados dos testes.

Esse plugin deve ser mantido! Se ele for retirado, não haverá nenhum erro de execução. Porém, também existirá nenhuma informação relacionada aos testes será exibida no terminal – a não ser uma mensagem padrão proveniente do Logger do AdonisJS.

runnerHooks

Logo abaixo das configurações de reporters, existe um objeto chamado runnerHooks, que possui duas propriedades: a primeira é um array – setup, e a segunda também é um array – teardown.

Toda função adicionada ao array setup será executada antes de todos os testes iniciarem. Aqui pode ser interessante registrar a execução de migrations e seeders para o banco de dados ou a inicialização de um servidor HTTP, por exemplo. Já as funções contidas no array teardown serão chamadas somente após todos os testes executarem.

Aqui, podem ser registradas funções que limpam alterações sofridas pelo banco de dados durante os testes, por exemplo.

configureSuite

Por último, existe uma função chamada configureSuite – o local onde a documentação sugere o registro hooks para conjuntos (suites) específicos de testes. No exemplo abaixo, o servidor HTTP é iniciado apenas antes de o conjunto de testes funcionais ser executado.

test.ts

Algo interessante de se notar é que todos os elementos (arrays, objetos e função) de configurações definidos no arquivo bootstrap.ts são exportados. Isso porque todos eles são importados pelo arquivo test.ts, que está no diretório raiz do projeto.

Este arquivo carrega todas as configurações necessárias para iniciar a aplicação AdonisJS e executar os testes por meio do Japa, aplicando tudo o que definido no arquivo bootstrap.ts.

A própria documentação declara que raramente é necessário alterar esse arquivo. Dessa forma, tudo está pronto! Basta executar o comando $ node ace test para os testes iniciarem e o seguinte resultado aparecerá no terminal:

.adonisrc.json

Este arquivo é responsável por diversas configurações do AdonisJS, mas será dado destaque apenas à parte que rege os testes automatizados. Nessa parte do arquivo é possível separar os testes da aplicação em grupos chamados suites, o que é útil para deixar o projeto bem organizado. Dentro do array suites, o desenvolvedor pode inserir objetos com as propriedades:

• name (identificação do conjunto de testes);
• files (array com paths relativos para executar arquivos específicos);
• e o timeout (tempo máximo permitido para executar os testes).

É claro que começar a escrever os testes a partir de uma aplicação recém criada é relativamente fácil. Mas o que dizer sobre os projetos AdonisJS iniciados antes do release em abril de 2022? E se adicionar testes automatizados a um desses projetos mais antigos, nos quais não havia arquivos para configuração de testes por padrão?

Adicionando testes a projetos antigos

Como mencionado no início do artigo, o AdonisJS possui uma documentação bem abrangente. Por isso, não é de se surpreender que um passo a passo para integrar testes automatizados a projetos anteriores ao release de abril de 2022 esteja disponível neste link.

Esse breve tutorial oficial orienta o desenvolvedor a seguir os seguintes passos:

1. Atualizar dependências do projeto que sejam relacionadas ao AdonisJS:

Todo pacote registrado no arquivo package.json que contenha @adonisjs em seu nome (ex:@adonisjs/lucid) precisa ser atualizado. Atualizar todas as dependências de um projeto de uma só vez pode ser perigoso, gerando problemas no funcionamento da aplicação.

Por isso, pode ser interessante usar o gerenciador de pacotes Yarn, que oferece a solução de atualizar dependências de forma interativa por meio do comando $ yarn upgradeinteractive --latest. Assim, é possível atualizar apenas o necessário, sempre tomando cuidado com pacotes que contenham breaking changes, marcadas em vermelho:

2. Executar o comando node ace generate:manifest:

Este comando atualizará o arquivo ace-manifest.json, adicionando os comandos mais recentes da CLI utilizada pelo AdonisJS ao projeto.

3. Executar o comando node ace configure tests:

Neste passo, todos os arquivos de configuração necessários para executar os testes serão criados (os mesmos mencionados anteriormente), além de um teste-modelo pronto para ser executado.

4. Mudar nomenclatura do ambiente de teste testing para test:

Por último, é necessário mudar o nome dado pelo AdonisJS ao ambiente de testes. Geralmente, apenas no arquivo env.ts é necessário aplicar essa mudança ao enum da propriedade NODE_ENV.

Porém, alguns projetos possuem o arquivo config/shield.ts, no qual o ambiente de testes também está nomeado como testing, exigindo a mudança para test.

Com isso, tudo está pronto para começar a escrever os testes e executá-los!

Conclusão

De fato, AdonisJS e Japa formam uma dupla poderosa que pode turbinar o processo de desenvolvimento orientado a testes automatizados. Ambos possuem documentações completas e assertivas.

O Japa proporciona liberdade para escolher a sintaxe dos testes e disponibiliza plugins poderosos, enquanto o AdonisJS carrega diversas funcionalidades nativas para validação, autenticação, ORM e muitas outras.

Conheça um pouco mais do universo de desenvolvimento com o AdonisJS com essa série de vídeos do Luber Manoel Fernandes Neto. E para aprender muito mais sobre tecnologia, fique ligado no blog da Luby!

Autor: João Victor Pereira Rodrigues.

Veja também:

Poised Testing – Tudo sobre o assunto.

Testes automatizados com React.

Desenvolvimento de Software.