Como testar APIs usando Postman, e como automatizar testes com Runner e Newman

Um breve overview sobre APIs

Uma API é um conjunto de definições e protocolos usado no desenvolvimento e na integração de software. Com as APIs é possível realizar integrações entre soluções ou serviços sem precisar se preocupar com linguagem, infraestrutura e ferramentas que foram utilizadas em sua implementação. O uso de APIs permite:

  • Facilidade na integração mobile-cloud
  • Grande poder de integração entre aplicações
  • Viabilizar parcerias
  • Customização de serviços
  • Impulsiona a inovação aberta

Devemos pensar na API como um contrato. Ela possui uma documentação que representa um acordo entre as partes interessadas, e, para que tenhamos sucesso nas solicitações, é necessário respeitar esta documentação.

REST

Representational State Transfer ou REST, é um estilo de arquitetura a ser utilizado para se projetar software distribuído, baseadas em comunicação via rede. O REST foi criado por Roy Fielding, um dos principais criadores do protocolo HTTP.

RESTful

Podemos dizer que uma API é RESTful, quando ela utiliza um design que respeita os conceitos de REST.

URI — Uniform Resource Identifier

A URI é o identificador de um recurso, pois tudo o que está disponível na internet precisa de um identificador único. Por exemplo, o identificador de uma página pode ser: https://github.com/murillowelsi .

Abaixo temos uma imagem que ilustra qual deve ser a estrutura básica de uma URI:

Métodos HTTP

Os recursos de uma aplicação podem ser manipulados de diversas maneiras. É possível criá-los, atualizá-los, excluí-los, dentre outras operações.

Quando fazemos uma requisição HTTP para um serviço, devemos informar URI para identificar quais recursos pretendemos manipular, e também informe o tipo de manipulação que queremos fazer no recurso. Para isso, utilizaremos os métodos do protocolo HTTP.

O protocolo HTTP possui diversos métodos, sendo que cada um possui uma função diferente. Os métodos HTTP mais utilizados são:

  • GET: Utilizamos o GET para recuperar os dados de um recurso.
  • POST: O POST é utilizado quando desejamos criar um novo recurso.
  • PUT: É utilizado quando queremos fazer uma alteração em um determinado recurso já existente.
  • PATCH: Utilizado para atualizar parcialmente um determinado recurso.
  • DELETE: Utilizado para excluir um determinado recurso.

Na próxima seção veremos na prática, a utilização dos métodos HTTP em um serviço REST.

HTTP Status-Code

Os códigos de retorno do protocolo (Status-Code) são basicamente um algarismo de três dígitos que é o resultado de uma tentativa de entendimento de uma requisição, isto é, sempre que você interage via HTTP, você obtém um código de retorno. As principais classes de status-code são:

2xx Sucesso

A classe de códigos de status 2xx indica a ação solicitada pelo cliente foi recebida, compreendida, aceita e processada com êxito. Exemplo:

200 OK : A requisição foi concluída com sucesso!

4xx Erro de cliente

A classe 4xx de código de status é destinado para os casos em que o servidor não conseguiu processar a solicitação porque o cliente a fez de forma errada ou que não dependa dele, como por exemplo uma página excluída. Por exemplo:

400 Bad Request: A requisição não pôde ser entendida pelo servidor devido à sintaxe malformada.

5xx Erro do servidor

Indica um erro do servidor ao processar a solicitação. Por exemplo:

500 Internal Server Error: O servidor encontrou uma situação com a qual não sabe lidar.

IMPORTANTE: Consulte os Status-Code e seus significados em: https://httpstatuses.com/

É importante dizer que essas informações te deixam apto a entender o básico do funcionamento de uma API, porém elas podem ser bem mais complexas em um projeto real.

Hands-on — Testando a API do TMDb

Usaremos a API da Movie Database em nossos testes, que é um banco de dados de filmes e TV criado pela comunidade. Para isto, precisaremos criar uma conta, acesse o endereço:

https://www.themoviedb.org/login?language=pt-BR

Após criar a conta, acesse Configurações > API e anote as informações de Chave da API e o Token de Leitura da API, precisaremos delas mais tarde.

Consulte sempre a documentação da API através do endereço:

https://developers.themoviedb.org/3/getting-started/introduction

Postman

O Postman é um API Client que facilita criar, compartilhar, testar e documentar APIs. A ferramenta oferece uma interface de usuário elegante onde é possível criar, salvar as requisições e ler suas respostas, sem a necessidade de escrever um monte de código apenas para testar a funcionalidade de uma API.

Para instalar o Postman consulte a documentação oficial em:

https://learning.getpostman.com/docs/postman/launching-postman/installation-and-updates/

Conhecendo os componentes do Postman

A seguir apresentarei alguns componentes do Postman de uma forma prática.

Workspace

Nosso primeiro passo será criar um Workspace, que é um recurso que ajuda a organizar o trabalho. Podemos separar nossos projetos por clientes, orgizando em espaços de trabalho de acordo com o contexto do projeto que está testando. Também possível compartilhar espaços de trabalho com sua equipe, o que permite a colaboração em tempo real.

Para criar nosso Workspace, selecione Create New, vamos chamá-lo de TMDb API Test.

Collection

Depois de criar nosso Workspace, vamos criar uma collection, que permite o agrupamento de diferentes solicitações, organizando essas solicitações em “pastas”. Para criar uma collection, clique em New Collection:

Dê um nome para a collection:

As collections são muito úteis, pois facilitam a organização e a documentação de suas requisições. Você pode criar conjuntos de testes, anexando scripts de teste a requisições e construir conjuntos de testes de integração.

Environment

Um environment é um conjunto de variáveis ​​que permite alternar o contexto de suas solicitações. As variáveis ​​permitem armazenar e reutilizar valores em suas solicitações e scripts.

Vamos inserir a URL base do TMDb (https://api.themoviedb.org/3 ) , a api_key e o token dentro de variáveis, para que possamos reutilizá-la em todos os requests:

Primeiro Request

Vamos criar agora nosso primeiro request. Será um GET que retorna os filmes mais bem avaliados na plataforma.

Siga os passos abaixo para criar um novo request:

A URI desse request é:

https://api.themoviedb.org/3/movie/top_rated

Como a URL base já está na nossa environment, parassaremos o nome da variável seguindo a notação {{baseUrl}}

{{baseUrl}}/movie/top_rated

Vamos inserir também os headers necessários, e clicar em Send para efetuar o request:

Agora recebemos a resposta da API, com os filmes top-rated e suas informações no formato JSON. Destaquei um filme (ótimo filme, por sinal) para que possamos identificar seu bloco no retorno:

Adicionando mais requests

Para saber quais as possibilidades de requests que podemos fazer nessa API, consulte a documentação em https://developers.themoviedb.org/3 , conforme a imagem abaixo:

Vamos adicionar mais requests em nossa collection.

GET /discover/movie
GET /movie/popular

Podemos utilizar Query Params para realizar filtros e buscar um filme específico. Devemos passar também o parâmetro api_key, como solicitado na documentação (https://developers.themoviedb.org/3/search/search-movies). Vamos fazer um filtro, buscando pelo título Batman:

Query params
GET /search/movie

Sandbox e Test Scripts

Com o Postman é possível escrever scripts de teste para suas solicitações da API usando JavaScript. O Postman Sandbox é um ambiente de execução JavaScript disponível para você ao escrever scripts de pré-request e scripts de teste para solicitações. Vamos adicionar alguns testes básicos em nossos requests:

  • Status-Code: queremos que nossas requisições retornem 200 (Sucesso).
  • Validar se Content-Type e Connection são retornados no Response Header.

Insira o código abaixo na aba Tests:

// Valida status code
pm.test(“Status test”, function () {
 pm.response.to.have.status(200);
});

// Valida se Content-Type é retornado no Response Header
pm.test(“Content-Type header is present”, function () {
 pm.response.to.have.header(“Content-Type”);
});

// Valida se Connection é retornado no Response Header
pm.test(“Connection header is present”, function () {
 pm.response.to.have.header(“Connection”);
});

Na aba Test Results podemos ver os resultados dos testes:

Os testes permitem garantir que sua API esteja funcionando conforme o esperado, estabelecer que as integrações entre os serviços estejam funcionando de maneira confiável e verificar se os novos desenvolvimentos não quebraram nenhuma funcionalidade existente.

Collection Runner

Como vimos anteriormente, as collections são grupos de requisições que podem ser executados. Com o Runner podemos criar suítes de teste de integração usando scripts de teste e automatizar sua execução.

Vamos executar os testes usando o Runner:

Selecione a collection e environment desejadas, e clique em Run:

Os testes serão exibidos em Run Results:

Newman

O Newman é utilizado para executar o Runner do Postman via linha de comando. Ele é construído com a extensibilidade em mente, para que você possa integrá-lo facilmente aos seus servidores de Integração Contínua.

Para instalar o Newman, consulte a documentação em: https://www.npmjs.com/package/newman

Pra finalizar esse post (que já ficou MUITO longo), vamos executar o Runner pela linha de comando usando o Newman:

  • Primeiro exporte sua collection, e salve em um diretório com seus testes:
  • Depois exporte suas environments e salve no mesmo diretório:

Para executar, abra o terminal e navegue até o diretório que salvamos as collections e environments. O comando para executar o newman é:

newman run SUA_COLLECTION --environment SUA_ENVIRONMENT

O Newman exibirá todos os relatórios no próprio terminal.

Assim finalizamos nossos testes com Postman, lembrando que existem diversas possibilidades, e o intuito deste post foi exibir apenas algumas delas.

Obrigado por acompanharem, e PRONTO, CHEGA!!