Testando sua API web com Postman

     Em algum momento todo desenvolvedor web já se deparou com a necessidade de interagir com alguma API (Application Programming Interface), seja para disponibilizar acesso externo à sua própria aplicação ou para se integrar com algum outro sistema. Antigamente era muito comum criar um Web Service usando a tríade HTTP, SOAP e XML, mas atualmente a maior parte destes serviços está sendo construída sob o modelo REST, com a troca de mensagens sendo realizada através de requisições HTTP  e o formato de dados JSON. Este post tem como objetivo apresentar uma maneira fácil e gratuita de testar sua API usando o software POSTMAN. Vamos lá?

     O POSTMAN é uma aplicação que permite realizar requisições HTTP a partir de uma interface simples e intuitiva, facilitando o teste e depuração de serviços REST. Ele está disponível como uma aplicação para o navegador Chrome (melhor baixar já que a versão do Chrome está sendo descontinuada) e possui diversas funcionalidades úteis no desenvolvimento desse tipo de projeto. Aqui veremos como utilizá-lo para testar as chamadas de um serviço ASP.NET Web API, enviando e recebendo dados no formato JSON. A nossa sequencia de passos será:

1. Efetuar um Get sem parâmetros
2. Efetuar um Get com parâmetros
3. Criar um teste HTTP 200
4. Criar um ambiente de testes dentro do Postman
5. Executar uma sequência de testes com uma variável compartilhada

Vou utilizar como base uma API que possuo de controle de Clientes.

1- EFETUAR UM GET SEM PARÂMETROS

Esta é a mais simples, vamos testar se um GET para a lista de clientes, digitamos o endereço (http://localhost:5000/api/Cliente), e clicamos em SEND:

     Neste caso não precisamos setar parâmetros de autenticação, alterar cabeçalhos nem adicionar cookies. Os dados são retornados abaixo e podem ser visualizados em JSON, texto ou XML. Neste caso temos o retorno em JSON por padrão por que o método retorna o content-type como application/json, veja:

Nada de surpreendente até aqui certo? Vamos em frente que as coisas vão ficar mais interessantes.

2- EFETUAR UM GET COM PARÂMETROS

     Agora vamos passar um parâmetro para filtrar nossa consulta e retornar um Cliente específico. Neste caso, a única mudança é que precisamos informar o código do cliente através da URL:

http://localhost:5000/api/Cliente/{codigo_cliente}

Ao clicar em send é feita a requisição e o resultado em JSON apresentado. É retornado apenas o cliente cujo o código é 2.

3- CRIAR UM TESTE COM VERIFICAÇÃO DO CÓDIGO DE RETORNO

     Agora que temos uma visão básica de como a ferramenta funciona que tal criar um teste de requisição básico verificando se a chamada HTTP retornou um status code de OK? Usando o mesmo método da API para retorno de Clientes:

Desta vez iremos utilizar a aba “Tests” conforme indicado pela seta 1. Digite o seguinte código:

tests[“Status code is 200”] = responseCode.code === 200;

     Nesta linha estamos criando um teste com nome de “Status code is 200” e verificando se o código de resposta HTTP é 200. Simples né? Ao executar o envio, clicando em “Send” obtemos o resultado do teste na seção apontada pela seta 2. O teste passou com sucesso!!

     A ideia é ter uma série de testes deste tipo em seus métodos da API para identificar possíveis links quebrados toda vez que os testes do Postman forem executados e antes mesmo de abrir qualquer tela, se retornar 404,403,500 ou qualquer código que não seja 200, você saberá.

4- CRIAR UM AMBIENTE DE TESTES DENTRO DO POSTMAN

1. No canto direito superior da tela do Postman, clique na engrenagem, depois em “Manage Enviroments”
2. Na tela de gerenciamento clique em “Add”
3. Digite um nome para o nosso ambiente e clique em “Add” novamente. Agora no combobox irá aparecer o ambiente que criamos (AmbienteTests). Veja abaixo:

Ambiente criado agora vamos criar dois testes e passar uma variável entre eles.

5- EXECUTAR UMA SEQUÊNCIA DE TESTES COM UMA VARIÁVEL COMPARTILHADA

     Para finalizar vamos criar dois testes e passar uma variável entre eles, este tipo de relação permite testarmos, por exemplo, um CRUD (Create, Read, Update e Delete) onde após efetuar a criação de um objeto no banco (INSERT) usamos o ID para deleta-lo (DELETE). Vamos lá?

     Para o insert vamos executar desta vez um comando de POST passando no body da requisição os dados que desejamos inserir. Veja na imagem abaixo que selecionei a aba “Body” e o formato de entrada “raw” em JSON, esta desta forma porque o input da minha API captura os atributos de entrada desta maneira, mas existem outras formas, como são vários campos, acho mais fácil e rápido de manipular deste jeito. A declaração do método no backend em .Net fica assim:

     Ao clicar no botão “Send” o registro será incluído, como saber a resposta retornou status correto? Da mesma maneira que no passo anterior, criei um teste que retorna status code 201 caso tudo tenha ocorrido conforme esperado. Veja o código do teste:

tests[“Status code is 201”] = responseCode.code === 201;

Partindo da ideia que o banco estava vazio banco de teste certo?), temos agora um registro criado, e o ID do cliente foi retornado na resposta em JSON, veja na imagem abaixo:

A imagem acima mostra outro ponto vital no nosso fluxo de testes, se após o insert iremos executar um delete do registro criado, precisamos de uma forma de passar o ID entre os teste certo? Observe que na aba “Tests” três novas linhas foram adicionadas:

var jsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable(“idCliente”, jsonData.idCliente);
console.log(jsonData.idCliente);

1. A primeira linha captura o JSON de retorno ao executar o POST, colocamos o resultado na variável jsonData.
2. A segunda linha cria uma variável de ambiente dentro do Postman, é aqui que está o “pulo do gato”, através deste ambiente que trocaremos o ID entre as requisições. Basta informar um nome e passar o valor como parâmetro.
3. E por fim, gravo o ID criado na tela de console do Postman apenas para fins didáticos. Para abri o console pressione ALT+CTRL+C.

Agora que temos o cliente e seu respectivo ID vamos ao segundo passo, executar um comando de DELETE. Para excluirmos um registro pelo ID temos duas mudanças importantes:

1. O comando HTTP agora é um DELETE.
2. Precisamos passar o vaor da variável(idCliente) do ambiente(AmbienteTestes) para nossa API. Veja a imagem abaixo.

     Veja que a URL agora tem {{idCliente}}, essa dupla chaves de cada lado é para informar ao Postman que esse valor vem de uma variável do ambiente. Se colocar o mouse em cima da URL será mostrado o valor atual da variável:

Para saber se ocorreu tudo OK coloquei um código de retorno no método da API para trazer 204 e um test no Postman semelhante ao que fizemos lá em cima:

tests[“Status code is 204”] = responseCode.code === 204;

Agora vamos executar os dois testes em sequencia, de uma forma semelhante ao que fazemos com testes unitários em uma aplicação. O Postman facilita isso para nós também, pressione CTRL+SHIFT+R para abrir a tela do Runner:

     Do lado esquerdo temos os testes criados, no meu caso além do INSERT e do DELETE tenho dois GETS, abaixo temos os ambientes, o número de vezes que desejamos executar os testes (Iterations), um delay entre as requisições e configurações de log. Execute o teste no botão azul gigante. O resultado é apresentado:

     Se todos os testes passarem uma tela semelhante a a esta será mostrada, neste caso os seis testes passaram com sucesso. Os resultados podem ser exportados para JSON. Bacana né? Agora você pode preparar sua aplicação para testar toda sua API antes de publicar em produção, inclusive é possível fazer isso via linha de comando e de forma automatizada antes de dar commit no seu código, mas fica para um próximo post.

Até a próxima pessoal.