Testes Manuais para uma API REST

Em qualquer ação de automatizar uma funcionalidade é imprescindível que tenhamos executado a ação/funcionalidade ao menos uma vez de forma manual, a fim de entender o que deve ser automatizado e garantir que aquele fluxo não possua bug.

Para um API REST existem diversas formas que podem ser aplicadas o teste manual, sendo duas:

via cURL
via Postman

Via cURL

É uma ferramenta via linha de comando para transferir dados entre URLs, suportando diversos protocolos. Ele pode ser utilizado para testes manuais em uma API REST para ações rápidas em uma API, sem grandes necessidades de verificações.

Um exemplo é a rapidez e facilidade que temos para listar dados de um endpoint. Poderíamos executar o seguinte comando para saber se um CPF possui uma restrição financeira:

curl -v http://localhost:8089/api/v1/restricoes/12345678901

Ele é nativo em sistemas baseados em Unix (Linux e Mac). No Windows requer instalação. Você pode saber mais em https://curl.haxx.se

Via Postman (recomendado)

Há diversas ferramentas via interface gráfica para executar testes manuais para uma API REST. Uma das mais utilizadas no mercado é o Postman.

Com ele, além de ter uma facilidade de uso por uma interface gráfica, podemos salvar as requisições, agrupá-las, criar parâmetros, etc…

Neste treinamento utilizaremos esta ferramenta para os testes manuais.

O que é Postman

Há diversas ferramentas via interface gráfica para executar testes manuais para uma API REST. Uma das mais utilizadas no mercado é o Postman.
Com ele, além de ter uma facilidade de uso por uma interface gráfica, podemos salvar as requisições, agrupá-las, criar parâmetros, etc…

O Postman é uma ferramenta para realizar requisições HTTP. Comumente ele é utilizado para efetuar requisições em um endpoint de API REST. Estas requisições são compostas por um método HTTP e uma URL.
Com ele podemos efetuar estas requisições através de uma interface gráfica ao invés de usar ferramentas de linha de comando, de forma intuitiva e de rápido aprendizado.

Composição da interface gráfica

1 - Método HTTP

Aqui você seleciona o método HTTP, onde os mais comuns são GET, POST, PUT e DELETE.

2 - URL

Aqui você insere a URL completa (URI e contexto) para a chamada da API.

3 - Parâmetros, Headers e Body

Você pode, quando necessário:

Inserir parâmetros na requisição (aba Params)
Inserir headers específicos (aba Headers)
Inserir dados na requisição (aba Body)

4 - ResponseBody

Uma vez enviado a requisição clicando no botão Send ao lado da URL, um retorno é gerado. Ele é chamado de Response Body e é composto pelos dados da body e status code.

5 - Histórico

Todas os envios de requisições ficam listados como histórico na aba History.

Efetuando uma requisição tipo GET

A requisição GET sempre será composta por:

Método HTTP GET
URL
Resposta
* Body
* Status

A Body, em quase 100% dos casos, retornará recursos (dados) que chamamos de Response Body.
Sempre há uma diferenciação simples e prática nas requisições GET:

Quando não há parâmetros no path serão retornados todos os dados do recurso
Quando há parâmetro somente é retornado o recurso cujo parâmetro esteja presente (Ex: ID, CPF, etc…)

Exemplo de GET no retorno de recursos

Para visualizar os dados retornados pelo uso do método GET efetuamos os seguintes passos:

Preenchemos o método HTTP como GET
Inserimos a URL completa da API para este método HTTP e enviamos a requisição
Visualizamos o retorno (Response Body)
Visualizamos o Status

Exemplo utilizando GET para retornar todos os recursos existentes

Note que o Response Body inicia com colchetes [ ]. Isso significa que temos como retorno um array de objetos (neste caso uma lista de simulações), onde cada objeto (simulação) está composto por chaves { } e separados por vírgula.

Outro ponto importante que você sempre deve verificar é se o Status corresponde ao status contido na documentação da API.

Exemplo de GET com path

Um GET com path geralmente possui um identificador para trazer um único recurso. A documentação mostra qual deve ser o identificador. No caso do exemplo abaixo o identificador é o CPF. O retorno da requisição, quando existir um recurso com o CPF informado, retornará somente aquele recurso.

Para visualizar o dado retornado pelo uso do método GET com path efetuamos os seguintes passos:

Preenchemos o método HTTP como GET
Inserimos a URL completa da API para este método HTTP com o identificador e enviamos a requisição
Visualizamos o retorno (Repsonse Body)
Visualizamos o Status

Exemplo utilizando GET pata retornar um recurso através de um parâmetro de path

Note que o Response Body inicia com chaves { }, onde é um objeto (simulação). Ele retorna o recurso para o identificador (cpf), se existente.

Exercício

Consultar CPF com restrição

Efetuar uma requisição para verificar um CPF que possui restrição no sistema utilizando o método GET.

Pré-condições

Iniciar aplicação, caso ela não esteja executando
Utilizar um dos CPFs que possui restrição. Ver Regras de Negócio da Aplicação no Capítulo 3.

Passos

Criar uma nova requisição contendo:
- Método GET
- URL: http://localhost:8088/api/v1/restricoes/{cpf}
  * Substitua o {cpf} por um CPF que possui restrição
Efetuar o envio da requisição

Resultados Esperados

O Body deve conter o seguinte resultado:

1  {
2     "mensagem": "O CPF {cpf} possui restrição"
3  }

O Status deve ser 200 OK

Efetuando uma requisição tipo POST

A requisição POST sempre será composta por:

Método HTTP POST
URL
Dados (Body)
Resposta
- Body
- Status

Esta requisição cria um novo recurso, por isso a obrigatoriedade de enviar os dados (Body) na requisição.

Exemplo de POST na criação de recursos

Para criar um novo recurso usando o método POST efetuamos os seguintes passos:

Preenchemos o método HTTP como POST
Inserimos a URL completa da API para este método HTTP
Na aba Body clicamos no item raw
Selecionamos o tipo de conteúdo (Content-Type) como JSON (application/json)
Inserimos os dados da Body de acordo com a documentação da API e enviamos a requisição
Visualizamos o retorno (Response Body)
Visualizamos o Status

Exemplo utilizando POST para criar um recurso

Exercício

Criar uma simulação com sucesso

Efetuar uma requisição para inserir uma simulação no sistema utilizando o método POST.

Pré-condições

Iniciar aplicação, caso ela não esteja executando

Passos

Criar uma nova requisição contendo:

Método POST
URL: http://localhost:8088/api/v1/simulacoes

Clique na aba Body e:
- Selecione o item raw
- Trocar o item Text por JSON (application/json)
- No campo de texto Body insira:

1     {
2        "nome": "Ciclano",
3        "cpf": "12345678910",
4        "email": "email@gmail.com",
5        "valor": 35000,
6        "parcelas": 5,
7        "seguro": true
8    }

Efetuar o envio da requisição

Resultados Esperados

O Body deve estar vazio
O Headers deve conter o atributo Location com a URL para a consulta da requisição criada
- http://localhost:8088/api/v1/simulacoes/12345678910
O Status deve ser 201 Created

Exercício

Validação dos fluxos de exceção

Efetuar uma requisição para tentar inserir uma simulação no sistema, mas que possua problemas na submissão.
O intuito deste teste é validar se as regras de negócio estão sendo aplicadas.

Pré-condições

Iniciar aplicação, caso ela não esteja executando
Visualizar as Regras de Negócio da Aplicação no Capítulo 3.

Passos

Criar uma nova requisição contendo:

Método POST
URL: http://localhost:8088/api/v1/simulacoes

Clique na aba Body e:
- Selecione o item raw
- Trocar o item Text por JSON (application/json)
- No campo de texto Body insira:

1     {
2        "cpf": "12345678910",
3        "email": "meu-email",
4        "valor": 55000,
5        "parcelas": 1,
6        "seguro": true
7     }

Efetuar o envio da requisição

Resultados Esperados

O Body deve deve conter o seguinte resultado:

1  {
2     "erros": {
3         "nome": "Nome não pode ser vazio",
4         "parcelas": "Parcelas deve ser igual ou maior que 2",
5         "valor": "Valor deve ser menor ou igual a R$ 40.000",
6         "email": "E-mail deve ser um e-mail válido"
7     }
8  }

O Status deve ser 400 Bad Request

Efetuando uma requisição tipo PUT

A requisição PUT sempre será composta por:

Método HTTP PUT
URL com identificador
Dados (Body)
Resposta
- Body
- Status

Esta requisição atualiza um recurso existente, por isso da obrigatoriedade de enviar os dados (Body) e um identificador na requisição.

Exemplo de PUT na alteração de recursos

Para alterar um recurso usando o método PUT efetuamos os seguintes passos:

Preenchemos o método HTTP como PUT
Inserimos a URL completa da API para este método HTTP com o identificador
Na aba Body clicamos no item raw
Selecionamos o tipo de conteúdo (Content-Type) como JSON (application/json)
Inserimos os dados da Body de acordo com a documentação da API e dos dados que queremos alterar e enviamos a requisição
Visualizamos o retorno (Response Body)
Visualizamos o Status

Exemplo utilizando PUT para alterar um recurso

Exercício

Alterar uma simulação existente

Efetuar uma requisição para alterar um dos atributos de uma simulação existente utilizando o método PUT.

Pré-condições

Iniciar aplicação, caso ela não esteja executando
Possuir, ao menos, uma simulação cadastrada

Passos

Criar uma nova requisição contendo:
- Método PUT
- URL: http://localhost:8088/api/v1/simulacoes/66414919004
- Clique na aba Body e:
  - Selecione o item raw
  - Trocar o item Text por JSON (application/json)
  - No campo de texto Body insira:
```
1     {
2        "email": "novo-email@gmail.com"
3     }
```
Efetuar o envio da requisição

Resultados Esperados

O Body deve retornar:

1  {
2    "id": 11,
3    "nome": "Fulano",
4    "cpf": "66414919004",
5    "email": "novo-email@gmail.com",
6    "valor": 11000,
7    "parcelas": 3,
8    "seguro": true
9  }

O Status deve ser 200 OK

Efetuando uma requisição tipo DELETE

A requisição DELETE sempre será composta por:

Método HTTP DELETE
URL com identificador
Resposta
- Body vazia
- Status

Esta requisição remove um recurso existente, por isso da obrigatoriedade de inserir um identificador na requisição.

Exemplo de DELETE na remoção de recursos

Para remover um recurso usando o método DELETE efetuamos os seguintes passos:

Preenchemos o método HTTP como DELETE
Inserimos a URL completa da API para este método HTTP com o identificador e enviamos a requisição
Visualizamos o retorno (Response Body) vazio
Visualizamos o Status

Exemplo utilizando DELETE para remover um recurso

Exercício

Tentar remover uma simulação não existente

Efetuar uma requisição para tentar remover uma simulação que não existe.

Pré-condições

Iniciar aplicação, caso ela não esteja executando

Passos

Criar uma nova requisição contendo:
- Método DELETE
- URL: http://localhost:8088/api/v1/simulacoes/{cpf}
  * Substitua o {cpf} por um CPF não existente no cadastro
Efetue o envio da requisição

Resultados Esperados

O Body deve retornar:

1  {
2     "mensagem": "CPF {cpf} não encontrado"
3  }

O Status deve ser 404 Not Found

Exercícios adicionais

Por favor, consulte o capítulo Exercícios adicionais para exercitar outros fluxos de exceção. Você pode fazer isso antes de avançar para o próximo capítulo ou no momento que você quiser.

Documentação de uma API REST

Up next

Testes Automatizados para uma API REST