Pré-requisições com JavaScript: preparação de dados e headers dinâmicos

O que são pré-requisições no Postman e por que usar

No Postman, uma pré-requisição (Pre-request Script) é um trecho de JavaScript executado automaticamente antes do envio de uma request. Ela serve para preparar o estado do teste: gerar ou transformar dados, montar headers dinamicamente, calcular assinaturas, criar timestamps, definir variáveis e até encadear dependências leves entre chamadas. Na prática, você usa pré-requisições quando a request precisa de informações que não são estáticas, como um identificador único, um token calculado, um header de idempotência, um nonce, um valor criptográfico, ou quando precisa ajustar o payload com base no ambiente ou em dados já existentes.

É importante separar mentalmente duas coisas: o script de pré-requisição prepara a request; já os scripts de testes (aba Tests) validam a resposta. Quando você coloca lógica de “preparação” no lugar certo, suas coleções ficam mais previsíveis, fáceis de depurar e reutilizáveis em diferentes ambientes.

Onde o script roda e o que ele pode alterar

Você pode escrever pré-requisições em dois níveis: no nível da request (aba Pre-request Script da própria request) e no nível da Collection (aba Pre-request Script da collection). O Postman executa os scripts na ordem do mais amplo para o mais específico: primeiro o da Collection, depois o da request. Isso permite definir padrões globais (por exemplo, headers comuns) e sobrescrever ou complementar em requests específicas.

O script pode alterar variáveis, montar strings, gerar objetos e, principalmente, influenciar o que será enviado: parâmetros de query, headers e body. A forma mais comum de “alterar a request” é definir variáveis e referenciá-las no request (por exemplo, em headers como {{auth_header}} ou no body como {{user_email}}). Outra forma é usar APIs do Postman para manipular diretamente a request em tempo de execução, como adicionar headers via pm.request.headers.add.

Ferramentas essenciais do JavaScript no Postman

Objeto pm e utilitários

O Postman expõe o objeto pm, que dá acesso a informações da request, variáveis e utilitários. Em pré-requisições, os recursos mais usados são: pm.variables (variáveis disponíveis no contexto), pm.environment (variáveis do ambiente), pm.collectionVariables (variáveis da collection), pm.globals (globais) e pm.request (a request em si). Para gerar valores, você também pode usar pm.sendRequest (para chamadas auxiliares) e bibliotecas embutidas como CryptoJS (hash/criptografia) e moment (em alguns workspaces/versões; quando não disponível, use Date nativo).

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Variáveis: leitura e escrita no script

Mesmo sem repetir conceitos de escopo, na prática você precisa saber como ler e escrever. Para ler, use pm.variables.get('nome') (pega o valor mais “próximo” disponível). Para escrever, escolha um alvo explícito, como pm.environment.set ou pm.collectionVariables.set. Uma boa prática é: dados temporários e específicos do fluxo de testes ficam em variáveis da collection; dados específicos do ambiente (host, credenciais de teste, chaves) ficam no ambiente.

// Lendo e escrevendo variáveis (exemplos práticos) const baseUrl = pm.environment.get('base_url'); const runId = pm.collectionVariables.get('run_id'); if (!runId) {   pm.collectionVariables.set('run_id', pm.variables.replaceIn('{{$guid}}')); } pm.collectionVariables.set('base_url_in_use', baseUrl);

Preparação de dados: gerando valores dinâmicos para payloads

Gerando identificadores únicos e dados “sempre novos”

Em testes de API, colisões de dados são uma fonte comum de falhas: e-mails repetidos, nomes de usuário já existentes, chaves naturais duplicadas. Pré-requisições ajudam a gerar dados únicos a cada execução. O Postman oferece variáveis dinâmicas como {{$guid}}, {{$timestamp}} e {{$randomInt}}, que podem ser usadas diretamente no body, mas também podem ser capturadas e armazenadas em variáveis para reutilização em múltiplas requests do mesmo fluxo.

// Gerar e-mail único e armazenar para usar em várias requests const guid = pm.variables.replaceIn('{{$guid}}'); const email = `qa_${guid}@example.test`; pm.collectionVariables.set('user_email', email); pm.collectionVariables.set('user_external_id', guid);

Depois, no body JSON da request, você referencia: {{user_email}} e {{user_external_id}}. Isso garante consistência: o mesmo usuário criado em uma request pode ser consultado/atualizado em seguida usando os mesmos valores.

Montando payloads complexos com base em variáveis

Às vezes o body precisa de estrutura condicional: incluir um campo apenas em certos ambientes, alternar um tipo de pagamento, ou variar um array de itens. Você pode montar um objeto JavaScript no script e depois serializar para JSON em uma variável, usando-a como body “raw”.

Passo a passo prático:

• Defina o body da request como raw e selecione JSON.
• No body, coloque apenas {{request_body}}.
• No Pre-request Script, monte o objeto e faça JSON.stringify.

// Passo a passo: montar body dinâmico const env = pm.environment.get('env_name') || 'local'; const guid = pm.variables.replaceIn('{{$guid}}'); const baseEmail = `buyer_${guid}@example.test`; const payload = {   customer: {     email: baseEmail,     externalId: guid   },   items: [     { sku: 'SKU-001', qty: 1 },     { sku: 'SKU-002', qty: 2 }   ],   metadata: {     env,     createdAt: new Date().toISOString()   } }; // Exemplo de lógica condicional: em staging, incluir flag extra if (env === 'staging') {   payload.metadata.stagingFlag = true; } pm.collectionVariables.set('request_body', JSON.stringify(payload));

Esse padrão é útil quando você quer manter a request “limpa” e concentrar a lógica de composição no script. Também facilita a depuração: você pode dar console.log(payload) e inspecionar no Postman Console.

Normalização e transformação de dados antes do envio

Pré-requisições também servem para padronizar formatos: remover espaços, forçar caixa baixa, truncar strings, converter números, e garantir que datas estejam em ISO 8601. Isso reduz falsos negativos em testes, especialmente quando dados vêm de variáveis preenchidas por outras etapas do fluxo.

// Normalização simples de campos antes de enviar const rawName = pm.collectionVariables.get('raw_name') || '  Maria  Silva '; const normalizedName = rawName.trim().replace(/
/g, ' '); pm.collectionVariables.set('customer_name', normalizedName); const rawPhone = pm.collectionVariables.get('raw_phone') || '(11) 99999-0000'; const digitsOnly = rawPhone.replace(/\D/g, ''); pm.collectionVariables.set('customer_phone', digitsOnly);

Headers dinâmicos: quando e como criar

Por que headers dinâmicos são comuns em QA

Muitas APIs exigem headers que mudam a cada chamada: X-Request-Id para rastreabilidade, Idempotency-Key para evitar duplicidade em POST, X-Timestamp para validação temporal, ou headers de assinatura como X-Signature. Mesmo quando a autenticação já está resolvida, esses headers adicionais podem ser obrigatórios para o gateway, WAF, ou camada de auditoria.

Adicionando e atualizando headers via script

Você pode definir headers diretamente na aba Headers usando variáveis, mas em cenários dinâmicos é prático garantir no script que eles existam e estejam atualizados. Um padrão é: gerar valores, salvar em variáveis e então inserir/atualizar o header na própria request.

// Gerar headers de rastreio e idempotência const requestId = pm.variables.replaceIn('{{$guid}}'); const idemKey = pm.variables.replaceIn('{{$guid}}'); const nowIso = new Date().toISOString(); pm.collectionVariables.set('x_request_id', requestId); pm.collectionVariables.set('idempotency_key', idemKey); pm.collectionVariables.set('x_timestamp', nowIso); // Aplicar diretamente na request (evita depender de configuração manual) pm.request.headers.upsert({ key: 'X-Request-Id', value: requestId }); pm.request.headers.upsert({ key: 'Idempotency-Key', value: idemKey }); pm.request.headers.upsert({ key: 'X-Timestamp', value: nowIso });

O método upsert é útil porque cria o header se não existir e atualiza se já existir. Isso reduz inconsistências quando você duplica requests ou reorganiza coleções.

Header Authorization montado dinamicamente

Mesmo sem entrar novamente em tipos de autenticação, é comum precisar montar o valor do header Authorization a partir de peças: prefixo, token, ou até múltiplos tokens. Um exemplo prático é padronizar o header em toda a collection: se existir uma variável access_token, o script garante que o header seja preenchido corretamente.

// Montar Authorization de forma padronizada const token = pm.variables.get('access_token'); if (token) {   pm.request.headers.upsert({     key: 'Authorization',     value: `Bearer ${token}`   }); }

Esse padrão evita requests falhando por esquecimento de configurar o header em uma nova chamada adicionada à collection.

Assinaturas e hashes em headers: HMAC e integridade

Algumas APIs exigem que você assine a request com um segredo compartilhado. O Postman permite calcular hashes e HMAC via CryptoJS. O ponto central é: a assinatura normalmente depende de elementos como método HTTP, path, query, body e timestamp. Em pré-requisições, você monta a “string to sign”, calcula o HMAC e injeta em um header, por exemplo X-Signature.

Passo a passo prático (exemplo genérico):

• Defina no ambiente um segredo, por exemplo api_secret.
• No Pre-request Script, capture método, path e body.
• Monte a string de assinatura.
• Calcule HMAC e envie em um header.

// Exemplo genérico de HMAC (ajuste conforme a especificação da sua API) const secret = pm.environment.get('api_secret'); const method = pm.request.method; // GET, POST... const url = pm.request.url.toString(); const timestamp = Math.floor(Date.now() / 1000).toString(); // Body raw (se existir) let body = ''; if (pm.request.body && pm.request.body.mode === 'raw') {   body = pm.request.body.raw || ''; } // String to sign (exemplo): METHOD\nURL\nTIMESTAMP\nBODY const stringToSign = [method, url, timestamp, body].join('\n'); const signature = CryptoJS.HmacSHA256(stringToSign, secret).toString(CryptoJS.enc.Hex); pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp }); pm.request.headers.upsert({ key: 'X-Signature', value: signature });

Ao depurar, registre no console a string de assinatura e compare com o que a API espera. Pequenas diferenças (quebra de linha, espaços, URL com ou sem query, ordenação de parâmetros) são as causas mais comuns de assinatura inválida.

Pré-requisições com pm.sendRequest: buscar dados antes de chamar a API principal

Em alguns fluxos, você precisa consultar um endpoint auxiliar para obter um valor que alimenta a request principal: por exemplo, buscar um identificador de catálogo, uma configuração de tenant, ou um token de curta duração específico para uma operação. Em vez de criar manualmente uma request anterior, você pode fazer essa chamada dentro da pré-requisição usando pm.sendRequest. Isso é útil quando a dependência é pequena e você quer manter o Runner com menos passos.

Passo a passo prático:

• Na request principal, use uma variável no lugar do valor dependente (por exemplo, {{catalog_id}}).
• No Pre-request Script, faça pm.sendRequest para o endpoint auxiliar.
• Extraia o valor da resposta e salve em variável.
• Somente depois, deixe a request principal seguir com o valor preenchido.

// Buscar um dado auxiliar antes de enviar a request principal const baseUrl = pm.environment.get('base_url'); const tenant = pm.environment.get('tenant'); const url = `${baseUrl}/catalogs/default?tenant=${encodeURIComponent(tenant)}`; pm.sendRequest({   url,   method: 'GET',   header: { 'Accept': 'application/json' } }, function (err, res) {   if (err) {     console.log('Erro ao buscar catálogo:', err);     return;   }   const json = res.json();   pm.collectionVariables.set('catalog_id', json.id);   // Opcional: garantir header dependente do catálogo   pm.request.headers.upsert({ key: 'X-Catalog-Id', value: json.id }); });

Um cuidado: pm.sendRequest é assíncrono. Em geral, o Postman aguarda a conclusão do script, mas você deve evitar cadeias complexas de múltiplas chamadas assíncronas na pré-requisição, porque isso aumenta a chance de flutuação e dificulta a depuração. Se a preparação ficar grande, prefira separar em requests explícitas no Runner.

Controle de aleatoriedade e reprodutibilidade

Dados aleatórios ajudam a evitar colisões, mas podem atrapalhar quando você precisa reproduzir um bug. Uma estratégia é criar um “seed” por execução e derivar valores a partir dele. Você pode gerar um run_seed uma vez e reutilizar em todas as requests, garantindo que a execução seja consistente dentro do mesmo run.

// Seed por execução para reprodutibilidade dentro do run let seed = pm.collectionVariables.get('run_seed'); if (!seed) {   seed = pm.variables.replaceIn('{{$timestamp}}');   pm.collectionVariables.set('run_seed', seed); } // Derivar valores determinísticos simples const email = `user_${seed}_${pm.variables.replaceIn('{{$randomInt}}')}@example.test`; pm.collectionVariables.set('seeded_email', email);

Se você precisar reproduzir exatamente, basta fixar manualmente o run_seed antes de rodar novamente.

Boas práticas de organização: scripts reutilizáveis e legibilidade

Centralizar padrões no nível da Collection

Quando várias requests precisam dos mesmos headers dinâmicos (por exemplo, X-Request-Id e X-Timestamp), coloque essa lógica no Pre-request Script da Collection. Assim, qualquer request nova já herda o comportamento. Para casos específicos, complemente no script da request.

Nomear variáveis com intenção e evitar “mágica”

Prefira nomes que indiquem finalidade: idempotency_key, x_request_id, request_body, catalog_id. Evite nomes genéricos como temp ou value1. Quando um header é derivado de uma variável, mantenha o mesmo nome para facilitar rastreio.

Log controlado e depuração

Use o Postman Console para depurar pré-requisições. Um padrão útil é logar apenas quando uma flag estiver ativa, evitando poluir a execução normal.

// Log condicional para depuração const debug = pm.environment.get('debug') === 'true'; if (debug) {   console.log('Request URL:', pm.request.url.toString());   console.log('Headers:', pm.request.headers.toObject()); }

Checklist prático para implementar pré-requisições com dados e headers dinâmicos

• Defina quais campos precisam ser dinâmicos (IDs, e-mails, timestamps, idempotência, assinatura).
• Escolha onde a lógica deve ficar: Collection (padrão) ou request (exceção).
• Gere valores e salve em variáveis com nomes claros.
• Use pm.request.headers.upsert para garantir headers sempre atualizados.
• Se precisar de assinatura, valide a “string to sign” com logs e compare com a especificação.
• Se usar pm.sendRequest, mantenha simples e evite múltiplas dependências assíncronas.
• Ative logs apenas com uma flag de debug para facilitar manutenção.