Indo além com POSTMAN

Fala galera, beleza? Espero que sim!

Por motivos de…

…resolvi escrever esse artigo! Já ouviram falar que a preguiça é a mãe da criatividade? Porque uma pessoa preguiçosa vai sempre arrumar uma forma de fazer uma mesma coisa de maneira mais prática e consequentemente mais rápida. Faz sentido pra você? Hehe

Brincadeiras a parte e sem mais delongas…

Hoje eu vim falar e ensinar uns tricks de produtividade com o POSTMAN. Então, pra quem ainda não conhece e nem sabe o que é o Postman, ele  é uma aplicação super prática e simples para testar serviços REST/RESTful enviando e tratando o retorno de requisições HTTP. Caso queira saber mais obre ele, pode clicar no nome em caixa alta destacado aí acima ou se já sabe como mexer nessa ferramenta, pode fazer o download clicando AQUI.

Pois bem, depois dessa breve introdução, vamos ao que interessa. O foco aqui não é explicar o que é o Postman, mas sim alguns usos que vão além de simplesmente fazer as requisições e que podem trazer muito ganho de tempo e produtividade no dia-a-dia de um desenvolvedor.

O Problema

Ao desenvolver uma API REST, você muito provavelmente já usou ou vai usar o Postman para testar seus endpoints e depois de um tempo pode acabar se perdendo com tantas abas abertas. E se a sua aplicação a ser testada é muito grande, o cenário só piora, vira uma verdadeira salada de URLs e variáveis, tudo misturado e você já nem sabe mais o que testar. Acaba que por muitas vezes você tem que apagar todas as abas e começar tudo de novo do zero, escrevendo cada endereço de forma novamente organizada. Porém com o passar do tempo, o seu painel de requisições vai encher de novo e se não tomar uma atitude, isso vira um ciclo sem fim. E aí você me pergunta: “Certo, Dhellano. E qual a primeira atitude a tomar?” E eu te apresento as COLLECTIONS.

Collections

Como o próprio nome diz, esse recurso são coleções, no caso, coleções de requisições as quais você pode salvar e dar nome a toda e qualquer chamada que é feita via Postman. E quer saber como você pode criar uma coleção? Segue o passo-a-passo:

A primeira coisa (depois de abrir o Postman, claro hehe), é clicar no botão New Collection. Ele fica próximo ao canto superior esquerdo. É um botão em formato de pasta com um símbolo de adição. Está destacado na imagem abaixo, no quadrado azul.

Feito isso, irá aparecer a tela de criação da coleção, onde você simplesmente irá dar um nome a sua coleção e clicar em criar (como mostrado na imagem a seguir).

Agora que temos uma coleção criada, ela não nos serve se não tivermos nossas requests guardadas nela. Então vamos lá, guardar uma URL na nossa coleção.

Salvar uma requesta na nossa coleção é muito fácil, você só tem que ir até o botão Save, quase lá no canto superior direito da tela. Bem ao lado do botão de envio das requisições. O botão foi destacado no quadrado amarelo na imagem acima e ao clicar no mesmo, uma caixa de diálogo é aberta. A caixa de diálogo que se abre é a SAVE REQUEST, nela você vai dar um nome a sua requisição, alguma descrição (opcional) e na parte de baixo selecionar em qual coleção você quer guardá-la. Pronto! Agora é só clicar em salvar. Atente-se ao nome que dei a minha requisição no exemplo acima, GET XYZ. E agora olhe a seguinte imagem:

A requisição foi salva na nossa coleção e sempre que você quiser utilizá-la, basta clicar em cima da mesma e ela já será aberta com todos os dados necessários, pronta para envio. Caso você tenha várias requests salvas e queira abrir mais de uma ao mesmo tempo, clique com o botão direito na chamada desejada e depois Open in New Tab.

Esse é um dos primeiros e mais simples recursos que o Postman oferece e por mais simples que seja, já economiza bastante tempo, hein? Evita reescrita de endpoints, traz celeridade aos testes, deixa tudo mais organizado e consequentemente mais prático de ser executado.

Mas agora vamos melhorar mais as coisas, certo?

Environments

Além das collections, o nosso amigo Postman traz outro recurso muito bacana chamado de ENVIRONMENTS ou simplesmente Ambientes. Imagine que você está atuando em um sistema na empresa em que você trabalha, também está desenvolvendo um sistema para um cliente por meio de freelancer e um amigo te pediu ajuda pra testar a aplicação que ele está desenvolvendo. Ou seja, 3 sistemas para testar e você começa a lotar o Postman não só com vários endereços das requisições, até porque com as coleções isso já não é mais problema. Mas o que pode acontecer agora são várias variáveis, parâmetros que são passados nas muitas requisições e que você pode acabar se confundindo com nomes iguais ou muito parecidos. E essa sopa de letrinhas pode acabar tornando todo o ambiente de difícil gerenciamento… então lá vai seu ganho e praticidade com coleções por água abaixo. Mas é aí que entram as environments (ambientes).

Environment é um ambiente “isolado” dentro do Postman. É como se fosse uma caixa onde você cria suas variáveis, seus parâmetros, seus endereços e eles só existem ali dentro, sem que nada externo interfira. Então o ideal para a situação dada de exemplo no parágrafo anterior, seria criar um ambiente para cada aplicação que você fosse testar: um para o sistema do trabalho, outro para o freelancer e mais um para testar o sistema do seu amigo. Assim, nada se misturaria e você conseguiria alternar a execução dos trabalho facilmente, apenas trocando de ambiente.

“Tá, Dhellano. Mas como eu crio um ambiente?”

Fácil demais! Saca só…

Para criar uma environment, basta clicar ali no botão com a engrenagem, já bem lá em cima no canto superior direito (destacado com quadrado amarelo na imagem acima). Ao clicar no botão, irá abrir a caixa de diálogo MANAGE ENVIRONMENT, então você vai clicar em Add e ao clicar em adicionar, será solicitado o nome da sua environment e já será possível criar suas variáveis. Então agora, você pode por exemplo criar uma variável chamada “teste” e dar um valor inicial a ela. E até pode dar um valor corrente se for o caso, depende da sua necessidade.

Prosseguindo, clique em Add e depois feche a caixa de diálogo. Feito isso, vá novamente até o canto superior direito novamente e no combo de seleção No Environment, selecione o ambiente que você acabou de criar. Agora com o ambiente selecionado, clique no botão ao lado (o que tem um olho desenho) e verá as informações que pertencem ao seu environment e somente a ele, com os seus respectivos valores. O sua visualização deve ser similar a essa (note a nossa variável criada e com o valor definido):

“Aaaah, muito massa! Mas como uso minha variável?”

As variáveis podem ser referenciadas com duas chaves, dessa forma:

{{teste}}

e isso pode ser feito em qualquer parte da ferramenta, como no campo da URL, cabeçalhos de requisição, corpo da mesma etc.

Agora, melhorando ainda mais as coisas… vamos a um exemplo prático de uso das variáveis e de quebra, conhecer outro excelente recurso do Postman. E já digo logo, deixei o melhor pro final. Esse é o recurso que me economizou mais tempo em todo período que já trabalho com REST API’s. Vamos lá, conhecer os pre-request scripts!

Pre-Request Scripts

Um dos casos mais conhecidos de testes no Postman é quando se está trabalhando com uma API que requer autenticação. Geralmente, você fica com uma aba aberta pra requisitar o seu serviço de autenticação que te devolve um token, e então você copia esse token e coloca no cabeçalho das requisições que precisam do mesmo para funcionar. Certo?

O que acontece muitas vezes no cenário descrito é que você copia o token errado e tem que copiar novamente, ou o token expira e você é obrigado a solicitar um novo, você desvia um pouco a atenção para focar em outra coisa e pá! O token que está ali já não está funcionando novamente… é a triste realidade do desenvolvedor que não explora o Postman! hehe. Mas só até hoje, porque agora vou explicar o que são os pre-request scripts e como eles resolvem esse problema e te dão muito mais produtividade durante o dia de desenvolvimento e testes. Assim você foca no que realmente importa. Bora!

Os pre-request-scripts são literalmente scripts que são executados antes de qualquer request dentro de uma collection e isso abre um leque com várias possibilidades de automatização.

Vamos agora ao exemplo prático que resolve o problema das requisições autenticadas e você não vai mais ter que pegar um token novo a cada teste de endpoint que for fazer.

Imaginem só vocês que eu tenho um authentication server que me fornece (baseado nas minhas credenciais) um token que deve ser enviado no cabeçalho das requisições da minha API, certo? Junto disso, podem acontecer todos os problemas que citei a algumas linhas atrás… cópia errada do token, expiração do mesmo, entre outras coisas.

“Então o que fazer?”

Começando com os pre-request scripts e automatizando o set de variáveis.

Na colletion que você deseja automatizar, e no caso desse exemplo, é a que possui os endpoints protegidos, clique nos 3 pontinhos (destacados no quadrado azul acima) referente as opções da coleção. Em seguida, clique em edit.

Ao clicar em edit, será aberta a caixa de diálogo EDIT COLLECTION, onde dentre as abas existentes, você deve selecionar a aba Pre-request Scripts.

Feito isso, logo abaixo no local destinado ao código, o script para a situação apresentada especificamente nesse exemplo é esse:

pm.sendRequest({
    url: 'localhost:8080/api/auth/signin',
    method: 'POST',
    header: {
        'content-type': 'application/json'
    },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            username: pm.environment.get("username"),
            password: pm.environment.get("password")
        })
    }
}, function (err, res) {
    pm.environment.set("access_token", "Bearer " + res.json().accessToken);
});

Explicando o código

• A primeira linha possui um objeto pm, esse objeto é interno ao Postman e fica responsável por todas as funcionalidades referentes a requests e responses, por isso a partir dele fazemos um sendRequest.
• Como já deu pra notar, o sendRequest é uma chamada HTTP e nas linhas a seguir a chamada é configurada com o tipo de conteúdo no cabeçalho (content-type: application/json) e o body, que no exemplo é também um JSON contendo apenas 2 campos: username e password.
• A linha onde são passados os campos do body tem a seguinte expressão: pm.environment.get. Essa instrução serve para recuperar o valor de variáveis criadas no environment. Lembra da nossa variável “teste”? Caso quisesse recuperar o valor dela no script, seria com essa instrução, passando o nome da variável no parâmetro. Aqui no cenário apresentado, tenho as duas variáveis do código criadas (username e password) com seus respectivos valores.
• E por fim, ao final da chamada é executada a instrução pm.globals.set, que serve para definir uma variável global (uma variável global é uma variável compartilhada por todos os environments). E o que de fato está sendo feito nessa última linha é a criação de uma variável global chamada “access_token” e ao mesmo tempo está sendo setado na mesma o valor “Bearer ” + o valor do campo accessToken que está presente no JSON de resposta da requisição (volte 3 imagens atrás e veja o token que essa requisição retorna).

Código salvo e explicado, veja como era feita a requisição antes…

E veja como é feita agora:

Produzindo resultado com sucesso:

Utilizando-se do recurso de chaves para referenciar uma variável, no lugar destinado ao token preenchemos agora com {{access_token}}. Sendo assim, sempre que qualquer request for feita, o nosso script será executado e irá setar o token dentro da nossa váriavel. Com isso, você não precisa mais se preocupar em pegar um novo token sempre que copiar errado ou acontecer do atual expirar.

Indo novamente ao canto superior direito da tela (no botão com o olho para ter acesso aos detalhes do environment), vamos ver o que o Postman faz quando a nosso rotina executa.

A imagem acima destaca as variáveis de momento do environment. Destacadas (escondidas) em vermelho estão as variáveis locais (que só são válidas dentro do ambiente que está sendo utilizado no momento, fazendo valer a vantagem do isolamento de ambientes que falamos mais no início do artigo) e em azul a variável access_token de escopo global, ou seja, válida para todos os environments que forem criados na ferramenta.

Algo que ficou auto-explicado no exemplo foi a vantagem e quando usar variáveis locais ou globais. Se você tem um cenário com várias API’s que se autenticam por meio de um token do mesmo serviço de autenticação, as variáveis particulares de cada serviço e que só fazem sentido para os seus respectivos negócios podem/devem ser locais. Já o token, que todas as API’s vão utilizar para autenticar os serviços, pode/deve ser global, assim todos compartilham o recurso.

Resumo

O Postman é uma ferramenta muito popular e apesar disso sempre foi (e ainda é) muito utilizada para executar apenas o trivial, requisições GET, POST, PUT, DELETE…

Mas agora que você sabe um pouco mais do poder que ela tem, que tal tentar montar o seu ambiente com as collections, environments e pre-request scripts necessários para melhorar o seu dia-a-dia no trabalho, em casa, nos estudos!?! Explore e use ao máximo os recursos que a ferramenta tem a oferecer, a perder você não tem nada. A ganhar? Eu sinceramente ainda não descobri o limite.

Curtiu o artigo? Compartilha nas redes e com os amigos!

Caso queira tirar alguma dúvida, trocar uma ideia sobre tecnologia e desenvolvimento ou propor uma correção/melhoria no conteúdo, aqui tem os meus contatos: http://dhecastro.com.br.

Manda uma mensagem! Vai ser um prazer responder.

Bônus

Pensou que tinha acabado, né? Acabou não! Falta o ponto e vírgula do código… hehe.

Já não bastava toda essa automação e versatilidade do Postman e tudo isso ainda é portátil! Isso mesmo, portátil!

Download e Import de environments

As environments configuradas podem ser facilmente baixadas, dessa forma:

Clicando no botão com ícone de engrenagem no canto superior direito (destacado em amarelo), a caixa de diálogo Manage Environments é aberta. E então basta clicar no botão com a seta para baixo (destacado em azul) no environment que se deseja realizar o download. Assim, será salvo no seu computador um arquivo no formato JSON com o nome do seu ambiente, e com todas as configurações que você fez.

Não muito diferente do fluxo de download é o de importação.

Para importar um environment presente na sua máquina, basta clicar no botão de engrenagem e logo depois na opção Import. Uma caixa de diálogo com os diretórios do seu computador abrirá. Assim, localize o arquivo JSON proveniente do download de alguma environment que você quer restaurar e clique em abrir. Pronto! A environment será novamente criada no Postman com todas as variáveis que ela já possuía, pronta para uso.