Conheci o Postman em 2015, eu acho, e desde então nunca mais larguei ele. É uma excelente ferramenta para ajudar nos testes de APIs/backends, sendo muito mais poderosa do que a maioria dos usuários imagina. Pensando nisso, no tutorial de hoje resolvi abordar tanto o básico de Postman, necessário para quem está começando, quanto dicas mais avançadas, que podem surpreender até mesmo quem já trabalha com ele há bastante tempo.
Importante que você tenha conhecimentos básicos do protocolo HTTP para conseguir acompanhar esse tutorial.
Vamos falar de:
- Requests HTTP/S
- Requests WS/S
- Requests Autenticadas
- Workspaces e Collections
- Variables
- Testes Automatizados
#1 – Requests HTTP/S
O primeiro passo é você instalar o Postman Desktop na sua máquina, algo que você deve fazer no site oficial, gratuitamente. Assim que realizar o download e a instalação apenas avançando até o final, você será convidado a criar uma conta ou então se autenticar usando Google e outros provedores de autenticação. Esse processo é importante para o uso de recursos mais avançandos como workspaces e collections, que veremos mais tarde.
Outra coisa que vamos precisar para nossos testes é de uma API/Backend. Se você já possui uma, beleza, mas se não possui, pode usar essa aqui. Ela é uma API Node.js, então você vai precisar ter ele instalado na sua máquina para que funcione, basta baixar e instalar do site oficial. Siga as instruções do README e deixe ele rodando na sua máquina antes de avançar, apenas sugiro colocar um valor bem alto de JWT_EXPIRES no seu .env para não te atrapalhar nos testes com autenticação mais tarde.
Se preferir, o resto desta seção é coberto pelo vídeo abaixo.
A coisa mais importante no Postman vem agora: criação de requests HTTP. Tem mais de um lugar na ferramenta que você pode fazer isso, mas uma bem fácil é clicando no botão “New” no canto superior esquerdo, o que vai te trazer as opções de requests possíveis de serem feitas via Postman, sendo que a que vamos usar aqui é a primeira e mais comum: HTTP.
Quando criamos uma nova requisição HTTP precisamos definir o verbo (GET, POST, etc), a URL e opcionalmente os Headers e Body, a depender dos requisitos da sua requisição. Por exemplo, na API que você clonou e subiu na sua máquina a partir do meu repositório, tem uma rota GET na raiz para ver se a API está funcional, que não exige parâmetro algum, essa aqui:
|
1 2 3 4 5 |
app.get("/", (req, res, next) => { res.json({ message: "Tudo ok por aqui!" }); }) |
Sua requisição ficaria assim, já com a response após clicar no botão azul de enviar a requisição:
Agora, nessa mesma API, temos outra rota para simular um login, que é um POST, essa aqui:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
app.post("/login", (req, res, next) => { if (req.body.user === "luiz" && req.body.password === "123") { const userId = 1; const token = jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: parseInt(process.env.JWT_EXPIRES) }); return res.json({ token: token }); } res.status(401).json({ message: "Invalid credentials!" }); }) |
Requisições POST, PUT e PATCH é comum exigirem que você passe parâmetros no corpo da requisição, o que você pode fazer na aba Body de um request no Postman e, se ele for JSON (como é o caso neste exemplo), selecionando a opção “raw”. Segue abaixo exemplo já com a response.
Veja que em ambos os casos, a response contém um corpo e um status code. Códigos iniciados em 2XX são sempre sucesso, enquanto que outros status geralmente indicam problemas, da sua requisição (4xx) ou do servidor (5xx).
Um último ponto a respeito de requests com dados no body é que dependendo do tipo de dado que você for enviar pode ser necessário adicionar Headers específicos, na respectiva aba. Como usei JSON, um formato muito popular, o próprio Postman entendeu isso e adicionou o header correto pra mim, mas querendo ou precisando fazer manualmente, você faria assim.
Outros Headers quaisquer que você possa precisar devem ser adicionados por essa aba também, como os headers de autenticação que veremos mais tarde. E isso encerra o básico de requisições HTTP.
#2 – Requests WS/S
Outra utilidade do Postman é para testes de servidores de WebSockets. Vamos precisar para nossos testes é de um servidor WS, então se você já possui um, beleza, mas se não possui, pode usar esse aqui. Ela é um exemplo de server WS com Node.js, então você vai precisar ter ele instalado na sua máquina para que funcione, basta baixar e instalar do site oficial. Este meu projeto é de um servidor que exige autenticação, então para podermos testar sem se preocupar com ela, vá no app-ws.js e comente a linha que chama a função de verificação, ficando como abaixo (linha 47 do arquivo ou 4 no trecho abaixo).
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
module.exports = (server) => { const wss = new WebSocket.Server({ server, //verifyClient }); wss.on('connection', onConnection); wss.broadcast = broadcast; console.log(`App Web Socket Server is running!`); return wss; } |
Depois siga as instruções do README e deixe ele rodando na sua máquina antes de avançar.
Se preferir, o restante desta seção é coberto no vídeo abaixo.
Agora crie uma nova request no Postman do mesmo que antes, no botão “New” no canto superior esquerdo, mas na tela de seleção do tipo de request, escolha “WebSocket”.
A forma de criar uma request via WebSocket é mais simples, pois temos apenas a URL para nos conectarmos, apenas lembrando que o protocolo a ser usado aqui é ws para servidores sem certificado SSL e wss para servidores com certificado. Também é importante atentar a todos os detalhes da URL a ser testada, pois às vezes um único detalhe como uma barra a mais ou a menos no final faz toda a diferença quando o assunto é websocket server.
Abaixo exemplo de conexão no ws server do meu repositório, após clicar no botão de “Connect” e já recebendo as respostas do meu servidor que apenas ficam me enviando timestamps a cada x tempo.
Uma vez devidamente conectado, como a comunicação via WS é bi-lateral, você também pode enviar mensagens para o servidor usando o campo “message” e depois o botão azul “Send” como abaixo, onde você pode ver também a resposta do servidor que informa que recebeu a mensagem e “ecoa” ela pra gente.
O protocolo WS é bem “cru”, então geralmente as mensagens e request e de response são strings mesmo ou ao menos JSON serializado como string, como pôde ver acima, com quaisquer parâmetros necessários sendo passados por querystring junto à URL da conexão.
Com isso encerramos o básico de testes de requisições WS via Postman.
#3 – Requests Autenticadas
Uma vez que aprendemos a fazer requests simples em URLs públicas, o próximo passo é aprender a fazer o mesmo mas agora em URLs que exijam autenticação. Existem inúmeros tipos diferentes de autenticações possíveis em web APIs e o intuito desse tutorial não é discutir ou apresentar todos eles, então tomarei como exemplo o JWT, que é a autenticação baseada em tokens JSON, muito popular atualmente.
No servidor de exemplo que forneci no passo 1, você pode usar a requisição de login para obter um token válido, a fim de fazer o teste seguinte que será em cima da rota privada de listagem de clientes que você abaixo.
|
1 2 3 4 5 6 |
app.get("/clientes", verifyJWT, (req, res) => { console.log("Retornou todos clientes!"); res.json([{ id: 1, nome: "luiz" }]); }) |
Como em toda autenticação HTTP, usamos o cabeçalho Authorization para informar os parâmetros de autenticação. Você pode tanto fazer isso pela aba Headers ou usar a aba Authorization, destinada exclusivamente para isso. Neste exemplo usarei o Auth Type como Bearer Token e o valor do token recebido no teste de login anterior. Já a request em si vai fazer um GET em /clientes, como abaixo, já com a resposta bem sucedida.
Experimente não informar o token ou mesmo informar um token errado e terá como retorno um erro 401 (Unauthorized) indicando a falta de permissão.
Já em servidores de websockets o token de autorização geralmente é enviado junto à própria URL, em formato de querystring. Se você voltar no projeto de ws server que forneci no passo 2 e descomentar a linha que comentamos para tirar a autenticação, você poderá fazer conexões somente com autenticação via parâmetro token, sendo que o token aqui está fixado para fins didáticos em 123456.
E com isso finalizamos o básico de requests autenticadas tanto via HTTP quanto via WS.
#4 – Workspaces e Collections
Uma vez que você crie requisições, possivelmente você vá querer reaproveitá-las e isso é possível através da funcionalidade de salvamento disponível na ferramenta, que fica no canto superior direito da request. No entanto, conforme a quantidade de requisições salvas for aumentando e requisições para diferentes sistemas e empresas forem sendo criadas, vai ser necessário você implementar algum tipo de organização. Felizmente o Postman já vem com uma estrutura embutida para isso, através de Workspaces e Collections. Eu falo disso e dos demais tópicos no vídeo abaixo.
Workspaces servem como “empresas”, ou seja, você pode ter um workspace para seus projetos pessoais e outro para os projetos do trabalho. Você cria workspaces pelo menu Workspaces > Create Workspace, no canto superior esquerdo da aplicação, como na imagem abaixo.
Dentro de Workspaces você pode ter Collections, que servem como “projetos”, ou seja, cada sistema diferente que você está testando pode ter as suas collections de requests, como no exemplo abaixo, onde Cerberus é o nome é o nome do projeto/collection e dentro dele ainda criei pastas para sub-organizar as requests por endpoint.
Assim, todas as chamadas ao endpoint /users (GET, POST, etc) eu guardo dentro da pasta Users, como abaixo.
Essa organização em workspaces > collections > folders > requests não é meramente organizacional, ela lhe permite usar alguns recursos mais avançados do Postman como as variáveis, que veremos a seguir.
#5 – Variables
Variáveis são um recurso muito poderoso do Postman e que facilitam bastante os nossos testes no dia a dia. Existem dois tipos de variáveis: as User-defined e as System-defined. As variáveis user-defined são criadas clicando no nome da Collection e indo na aba Variables, como abaixo, onde criei duas variáveis da collection Cerberus, uma para o host do backend e outra para o token a ser usado nas requisições.
Eu poderia definir o token na aba Auth, mas por costume gosto de usar a aba variables para isso. Assim, em todas as requests da Collection Cerberus agora eu posso usar as variáveis host e token usando a notação {{nomeVariavel}}, como abaixo, onde usei a variável {{host}} na construção da URL e a variável {{token}} no header Authorization.
As vantagens dessa abordagem são as mesmas da centralização e não-repetição de informações na programação tradicional: se eu precisar mudar o token por exemplo, pois o antigo expirou, eu gero um novo e troco apenas na seção Variables da Collection e automaticamente todas as requests da minha coleção usarão o token atualizado.
O outro tipo de variáveis são as system-defined, ou seja, as padrões que já vem definidas no Postman. Essas são variáveis são muitos úteis por terem comportamentos especiais como geração de valores aleatórios. Veja o exemplo abaixo onde uso as variáveis system-defined {{$randomFullName}} para gerar um nome aleatório e a {{$randomEmail}} para geração de um endereço de e-mail aleatório também em uma request de cadastro de usuário. Apenas certifique-se de respeitar o tipo de dados, na imagem abaixo acabei esquecendo de colocar aspas ao redor da variável.
As variáveis system-defined começam todas com $, então experimente iniciar uma delas e ver o auto-complete do Postman te mostrar todas as possibilidades que você possui à disposição.
#6 – Testes Automatizados
E por fim, mas não menos importante, temos os testes automatizados. Sim, porque uma vez que você crie uma request para seu sistema você pode escrever um script JS para verificar se o teste passou ou não. Isso é feito na aba Scripts da request, sendo que você pode criar scripts de pré-request (para ajudar a preparar a request) ou de pós-response, para analisar o resultado do teste, que é o que faremos aqui.
Para quem já trabalhou com unit tests em Node.js, com frameworks como Jest, vai se sentir em casa porque a sintaxe das asserções é muito parecida uma vez que o Postman usa a biblioteca Chai, mudando apenas o fato que usamos um objeto global chamado pm (de Postman) para acessar request, response, etc como abaixo onde escrevi um teste para ver se o retorno da request foi o status que eu esperava.
|
1 2 3 4 5 |
pm.test("Should be success", () => { pm.response.to.have.status(200) }) |
Ao enviar a requisição como faria normalmente, eu tenho na área da resposta a opção de trocar entre “Body” e “Test Results” que me traz o resultado dos meus scripts de teste. Sim, scripts, no plural, porque eu posso ter vários pm.test em cada request ou até mesmo scripts de testes espalhados em várias requests da minha coleção e mandar rodar todos eles usando a função “Run Collection” citada na mensagem em azul na imagem abaixo, onde poderá configurar a bateria de testes.
Outro exemplo de script de teste é verificar se o corpo da resposta veio JSON.
|
1 2 3 4 5 |
pm.test("Should be JSON", () => { pm.response.to.have.jsonBody() }) |
Outro exemplo é para acessar as informações do corpo da resposta em formato JSON, como abaixo e também usando uma sintaxe diferente e mais parecida como o que temos em outros ambientes JS (expect).
|
1 2 3 4 5 6 |
pm.test("Should has 1 customer", () => { const responseJson = pm.response.json(); pm.expect(responseJson).to.have.lengthOf(1); }) |
Para a documentação completa de escrita de scripts de teste no Postman, consulte a documentação oficial.
Um abraço e até a próxima!
Olá, tudo bem?
O que você achou deste conteúdo? Conte nos comentários.