Como usar o Codeception para criar testes de APIs eficientes

O uso de APIs para uma comunicação padronizada entre aplicações é cada vez mais comum. Ao utilizar APIs testes precisam ser criados para validar seu funcionamento e garantir a comunicação. Neste artigo apresento como usar o Codeception para criação de testes de APIs.

Codeception é um incrível framework opensource que reúne as principais ferramentas de automação de testes no mercado. Seu objetivo é permitir escrever testes unitários, integração e aceitação.

Conceito de API

Antes de começarmos a falar sobre testes automatizados com Codeception vamos falar um pouco sobre o conceito de API.

API significa Application Programming Interface, ou seja, uma Interface de Programação de Aplicações. Bom… isso quer dizer basicamente que a API é uma interface de comunicação entre aplicações. Uma API é construída com o propósito de ser uma espécie de intérprete entre aplicação. Imagine, por exemplo, que você tem duas aplicações da mesma empresa que precisam se integrar, mas foram desenvolvidas em linguagens distintas, uma em JAVA e outra em PHP. Como é que faz? Crie uma API que possibilita troca de dados entre as duas aplicações.

Nós ouvimos falar tanto de API do Google Maps, API do Facebook, API do Twitter. Essas API’s são portas de entrada para conversarmos com essas aplicações sem que você precise conhecer sequer a linguagem em que essas aplicações foram desenvolvidas.

Entretanto para que a comunicação ocorra é necessário que ambas as aplicações, ou simplesmente partes delas, tenham um “idioma” em comum. É como no mundo real, para duas pessoas terem uma conversa elas precisam ter algum idioma comum, que pode ser português ou libras por exemplo. Entre os “idiomas” mais comumente usados entre API’s está o tradicional XML – e ainda muito usado – e o mais recente JSON.

Partindo do princípio de que quem vai consumir a API é outra aplicação, as respostas precisam ser padronizadas. Uma forma de garantir que a API vai responder de acordo com o esperado é criar testes automatizados. Lembrando que precisamos testar não somente o padrão de resposta esperado mas também o status code da resposta.

Porque criar testes de API?

Imagine a situação que a API retorna uma mensagem de erro. Como identificar que aquela simples string não se trata de um sucesso mas sim de uma falha? Por esse motivo é importante além de retornar os devidos status code sobre a situação ocorrida, também garantir o retorno do status através dos testes.

Em resumo o teste de API irá validar tanto o corpo da resposta como o status code. Precisamos então manter os demais testes (como os unitários) funcionais para garantir o cumprimento dos requisitos e das regras de negócio. O teste de API não testa métodos, ele simplesmente faz uma requisição HTTP para uma API e verifica se a resposta está conforme previsto.

O Codeception é um framework completo de testes, que possibilita ao desenvolvedor criar vários tipos de testes automatizados inclusive testes de API. Ou seja, você também pode utilizá-lo para seus testes unitários.

Com o Codeception é possível testar API REST, SOAP ou RPC com retornos em json ou XML. Neste post vou abordar apenas o teste de uma API RESTful.

Codeception

O Codeception testa API desenvolvida com ou sem framework. Veja abaixo alguns passos para implementar testes automatizados na sua API.

O primeiro passo é instalar o composer. Não irei abordar a instalação do composer neste post mas o procedimento é simples e você pode encontrar as instruções no link https://getcomposer.org/download/.

Uma vez instalado o composer você pode instalar o Codeception através dos comandos:

php composer.phar require "codeception/codeception"

php vendor/bin/codecept

php vendor/bin/codecept bootstrap

php vendor/bin/codecept generate:suite api

Após a instalação o próximo passo é alterar o arquivo api.suite.yml dentro do diretorio tests para:

class_name: ApiTester

modules:

   enabled:

    - REST:

     depends: PhpBrowser

     url: http://codeception.local/    // SUA API

Neste ponto todas as instalações necessárias foram feitas e você já pode começar a criar seus testes de API.

php vendor/bin/codecept generate:cest api MyTest

Uma classe de teste será criada em tests/api com o nome MyTestCest com a seguinte estrutura:

class HelloTestCest
{

   public function _before(ApiTester $I)
   {

   }

   public function _after(ApiTester $I)
   {

   }

   // tests
   public function tryToTest(ApiTester $I)
   {

   }

}

Reparem que todos os métodos recebem como parâmetro uma instância da classe ApiTester e nós usaremos seus métodos para elaborar os testes de API. ApiTester tem vários métodos mas vou mencionar aqui alguns:

$I->wantTo // Rápida descrição para o teste a seguir

$I->haveHttpHeader // Seta um novo cabeçalho à próxima requisição

$I->sendPOST | $I->sendGET // Efetua a requisição de acordo com o verbo HTTP

$I->seeResponseCodeIs // Confere se o status code da requisição está conforme o esperado

$I->seeResponseIsJson // Checa se a resposta é um json

$I->seeResponseContains // Verifica se o corpo da resposta contem determinado conteúdo

$I->grabResponse // Retorna o corpo da resposta da requisição

Criação dos testes

Voltando ao MyTestCest gerado, com os métodos acima é possível testar sua API facilmente. Você pode utilizar o próprio método tryToTest gerado, ou então criar seu próprio metodo de teste.

Considere um API de cadastro de usuários que requere os campos email e senha. Vejamos abaixo exemplos de testes que não enviam os dados requeridos.

public function tryCreateUserWithoutEmailTest(ApiTester $I)
{

   $I->wantTo('test create user without email');

   $I->sendPOST('user',['password'=>'123']);

   $I->seeResponseCodeIs(\Codeception\Util\HttpCode::BAD_REQUEST);

   $I->seeResponseIsJson();

   $I->seeResponseEquals('{"message":"Email is required"}');

}

O teste acima:

• Faz uma requisição POST para a API http://codeception.local/user enviando no corpo da requisição o campo password com o valor ‘123’.
• Verifica se o status code de resposta é 400
• Checa se a resposta é um json e se é exatamente igual a {“message”:”Email is required”}

O teste abaixo é semelhante ao anterior, a diferença é que na requisição o email será enviado e a senha vazia.

public function tryCreateUserWithoutPasswordTest(ApiTester $I)

{

   $I->wantTo('test create user without password');

   $I->sendPOST('user',['email'=>'email@test.com', 'password'=>'']);

   $I->seeResponseIsJson();

   $I->seeResponseContains('{"message":"Password is required"}');

   $I->seeResponseCodeIs(\Codeception\Util\HttpCode::BAD_REQUEST);

}

Este teste:

• Faz uma requisição POST para a API http://codeception.local/user enviando no corpo da requisição o campo email com o valor ‘email@test.com’ e o campo password vazio.
• Verifica se o status code de resposta é 400
• Checa se a resposta é um json e se contém {“message”:”Password is required”}

Reparem que os testes anteriores testaram os comportamentos mediante a requisições mal sucedidas, o que é muito importante para indicar a quem consumir essas API’s que algo de errado aconteceu. A seguir um caso que testa o sucesso da requisição:

public function tryCreateUserWithSuccess(ApiTester $I)

{

  $I->wantTo('test create user with success');

  $I->sendPOST('user',['email'=>'email@test.com','password'=>'123']);

  $I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK);

  $I->seeResponseIsJson();

  $I->seeResponseContains('{"message":"User saved successfully"}');

}

Este teste:

• Faz uma requisição POST para a API http://codeception.local/user enviando no corpo da requisição o campo email com o valor ‘email@test.com’ e o campo  password com o valor ‘123’.
• Verifica se o status code de resposta é 200.
• Checa se a resposta é um json e se contém {“message”:”User saved successfully”}

Execução dos testes

Feitos os testes é hora de executá-los e existem algumas formas de fazer isso via linha de comando:

Executa todas as suítes de testes

php codecept run

Executa todos os testes de API

php codecept run api

Executa os testes contidos em uma classe específica de testes

php codecept run tests/api/NewTestCest.php

Executa os testes contidos em uma classe específica de testes exibindo passo a passo

php codecept run tests/api/NewTestCest.php --steps

Executa os testes contidos em uma classe específica de testes exibindo detalhadamente dados enviados e resposta. Ideal para identificar problemas.

php codecept run tests/api/NewTestCest.php --debug

juciellen@cabrera:~/Documentos/projetos/codeception$ php codecept run api

Codeception PHP Testing Framework v2.2.11

Powered by PHPUnit 5.7.19 by Sebastian Bergmann and contributors.



Api Tests (3) ---------------------------------------------------------------------------------------------------------------------------------------------------

✔ UserCest: Test create user without email (0.02s)

✔ UserCest: Test create user without password (0.01s)

✔ UserCest: Test create user with success (0.01s)

-----------------------------------------------------------------------------------------------------------------------------------------------------------------


Time: 95 ms, Memory: 10.00MB


OK (3 tests, 12 assertions)

Basicamente é isso, percebam que não é complicado implementar testes de API na sua aplicação. Vale relembrar que se trata de mais um tipo de cobertura de testes e ele não substitui os demais tipos.