[Guia] O que significa Postman JSONPath?

Testes eficazes de API dependem da extração e manipulação eficientes de dados de respostas JSON. Postman, uma popular plataforma de desenvolvimento de API, capacita os usuários com JSONPath, uma poderosa linguagem de consulta projetada especificamente para navegar em estruturas JSON.

Este artigo aprofunda-se no mundo do Postman JSONPath, equipando você com as habilidades para desbloquear todo o potencial de suas interações com a API.

O que é JSONPath?

JSON (JavaScript Object Notation) é um formato de dados onipresente para troca de informações entre APIs e aplicativos. Embora sua natureza legível por humanos seja uma vantagem, respostas JSON complexas com objetos e arrays aninhados podem ser difíceis de navegar. É aqui que o JSONPath entra – uma linguagem de consulta concisa projetada especificamente para percorrer e extrair dados de estruturas JSON.

As expressões JSONPath se assemelham a um mapa, guiando você pela hierarquia JSON. Veja como funciona:

Elemento Raiz

Os elementos raiz são representados por $, que significa o documento JSON inteiro.

Nós Filhos

A notação de ponto (.) ou notação entre colchetes ([]) é usada para acessar nós filhos.

• A notação de ponto é preferida para nomes de propriedades simples: $.name seleciona a propriedade "name" do objeto raiz.
• A notação entre colchetes é usada para acessar propriedades com caracteres especiais ou espaços: $['full name'] almeja a propriedade "full name".

Arrays

Colchetes com um índice acessam elementos específicos: $.items[1] seleciona o segundo elemento no array "items". Coringas (*) podem ser usados para direcionar todos os elementos: $.products[*] seleciona todos os elementos no array "products".

Filtros

Filtros permitem restringir resultados com base em condições. Por exemplo, $..[?(@.price > 100)] seleciona todos os objetos dentro da estrutura JSON (denotados por ..) onde o "price" da propriedade é maior que 100.

Como o Postman Funciona com JSONPath?

Scripts de Teste

Expressões JSONPath podem ser incorporadas dentro dos scripts de teste do Postman para extrair dados específicos das respostas e realizar asserções.

• Exemplo: pm.test("Código de status é 200", () => pm.response.json().statusCode === 200);
• Exemplo (com JSONPath): pm.test("ID do Usuário é 123", () => pm.response.jsonPath("$.id") === 123);

Coleções

JSONPath pode ser usado dentro de variáveis de coleção para definir dinamicamente os parâmetros da solicitação com base em respostas anteriores. Isso permite construir casos de teste reutilizáveis e orientados por dados.

• Exemplo: Recuperar um ID de usuário de uma resposta anterior e usá-lo em uma solicitação subsequente: pm.collectionVariables.set("userId", pm.response.jsonPath("$.id"));

Scripts de Pré-solicitação

Expressões JSONPath podem ser usadas dentro de scripts de pré-solicitação para manipular dados antes de enviar uma solicitação.

• Exemplo: Modificar um corpo de solicitação com base em valores específicos de uma variável de ambiente de teste: pm.request.body.set("productId", pm.environment.variables.selectedProduct.id);

Exemplos de Consultas JSONPath

Estes são alguns exemplos de consultas JSONPath que podem ser implementadas na seção de pré-solicitação do Postman.

Exemplo 1 - Lógica Condicional com a função if

Imagine uma resposta com uma propriedade "isActive" para usuários. Você quer extrair seus nomes, mas apenas se eles estiverem ativos.

$.users[*].if(@.isActive, $.name, "Inativo")

Este código usa a função if. Se o objeto de usuário atual tiver uma propriedade "isActive" definida como true, ele extrai seu nome. Caso contrário, retorna a string "Inativo".

Exemplo 2 - Encontrando Valores Mínimos/Máximos

Vamos supor que você tenha um array "orders" com uma propriedade "amount" para cada pedido. Você quer encontrar o pedido com o menor e o maior valor.

$..[?(@.type == "order")].amount.min()  // Valor mínimo
$..[?(@.type == "order")].amount.max()  // Valor máximo

Essas consultas aproveitam as funções min() e max() para identificar os respectivos valores na propriedade "amount" em todos os pedidos.

Exemplo 3 - Achatar Arrays Aninhados

O Postman não suporta nativamente arrays aninhados. Se você tiver uma resposta com categorias de produtos aninhadas, pode querer achatá-las em uma única lista.

$.categories..[*] | flatten

Este código utiliza o operador de pipeline (|) e a função flatten. Ele percorre todos os elementos aninhados dentro da estrutura "categories" e os achata em um array de um único nível.

Exemplo 4 - Trabalhando com Datas e Números

JSONPath pode manipular datas e números. Vamos supor que você tenha um timestamp "createdAt" para usuários. Você quer formatá-lo para um formato de data específico.

pm.response.json().users[*].createdAt.toString(pm.timestampFormat("YYYY-MM-DD"))  // Supondo uma função de formato pré-definida

Este exemplo combina JSONPath com uma função de script do Postman (pm.timestampFormat) para formatar o timestamp "createdAt" no formato desejado (YYYY-MM-DD) dentro de um script de pré-solicitação.

Exemplo 5 - Combinando JSONPath com Variáveis do Postman

Você pode controlar dinamicamente consultas JSONPath usando variáveis do Postman. Suponha que você queira filtrar usuários com base em um ID de usuário armazenado em uma variável.

$.users[?(@.id == pm.variables.get("selectedUserId"))]

Aqui, pm.variables.get("selectedUserId") recupera o valor armazenado na variável "selectedUserId" e o utiliza dentro do filtro JSONPath para a seleção dinâmica de usuários.

Apidog - Configurando Rápido Scripts de Pré-Processamento

Apidog é uma ferramenta abrangente de desenvolvimento de API que pode ser a alternativa perfeita ao Postman para desenvolvedores.

Com ferramentas completas para todo o ciclo de vida da API, os desenvolvedores podem construir, testar, simular e documentar APIs apenas no Apidog!

Definindo Scripts de API Personalizados Usando Apidog

Apidog fornece aos desenvolvedores recursos de geração de código para scripts personalizados. Você pode obter e definir variáveis de ambiente e locais.

Você também pode personalizar a seção do pós-processador da sua API, especificando a Expressão JSONPath e o objeto alvo.

Criando Novas APIs com Apidog

Apidog capacita os usuários com um alto grau de flexibilidade de design no processo de criação da API. Isso possibilita o desenvolvimento de APIs que se alinham precisamente com os requisitos funcionais de seu aplicativo ou as necessidades específicas de seus usuários pretendidos.

Comece pressionando o botão Nova API, conforme mostrado na imagem acima.

Após estabelecer a funcionalidade principal da sua API, agora é essencial definir meticulosamente suas características operacionais. Esta seção descreve as principais considerações envolvidas nesse processo:

• Métodos HTTP: A seleção do método HTTP apropriado (GET, POST, PUT, DELETE) é vital. Esses métodos governam como os usuários interagem e manipulam informações dentro da sua API.
• Endpoint da API: Um endereço da web único (endpoint) deve ser escolhido para servir como ponto de acesso para os usuários localizarem e interagirem com sua API.
• Parâmetros de Entrada: É necessário especificar claramente quaisquer elementos de dados que os usuários possam incorporar ao endereço da API para recuperar respostas específicas.
• Funcionalidade: É necessária uma explicação clara para detalhar as ações e resultados precisos facilitados pela sua API.

Para garantir que você esteja construindo APIs eficazes, considere revisar estes artigos úteis sobre melhores práticas de REST API.

Conclusão

A integração do JSONPath no Postman desbloqueia uma ferramenta poderosa e versátil para navegar e manipular dados dentro de respostas JSON. Ao dominar expressões JSONPath, você pode extrair eficientemente valores específicos, filtrar resultados com base em condições e até mesmo realizar transformações de dados complexas. Isso capacita você a agilizar os fluxos de trabalho de teste de API, obter insights mais profundos das respostas e construir casos de teste robustos que garantam a funcionalidade e confiabilidade de suas APIs.

Além disso, a integração suave do JSONPath com as capacidades de script do Postman abre portas para casos de uso ainda mais avançados. Você pode controlar dinamicamente consultas usando variáveis, aproveitar funções para manipulação sofisticada de dados e combinar JSONPath com scripts de pré-solicitação ou scripts de teste para automatizar tarefas complexas. Ao abraçar o poder do JSONPath no Postman, você eleva seu processo de desenvolvimento de API a um novo nível de eficiência e eficácia.