Algumas requisições precisam de trabalho antes de sair da sua máquina, e outras precisam de trabalho no momento em que uma resposta chega. Uma API de pagamento deseja uma assinatura HMAC computada a partir de um timestamp e seu segredo. Um endpoint de login retorna um token que toda chamada posterior precisa. Um fluxo de checkout precisa afirmar que a resposta realmente retornou um 200 e o ID de pedido correto. Você pode fazer tudo isso manualmente, mas isso se torna tedioso rapidamente e quebra no segundo em que você compartilha a requisição com um colega de equipe.
Scripts resolvem isso. No Apidog, você anexa pequenos trechos de JavaScript a uma requisição que são executados automaticamente: um conjunto antes da requisição ser enviada, outro depois que a resposta retorna. Se você já escreveu scripts no Postman antes, a memória muscular se mantém, porque o motor do Apidog é compatível com a mesma API de objeto pm. Este guia aborda ambas as etapas com um exemplo realista: assinar uma requisição em um script pré-requisição e, em seguida, extrair um token em um script pós-resposta. O comportamento está totalmente documentado na documentação de scripts do Apidog, mas os nomes das abas e alguns comportamentos diferem do Postman, e essas diferenças importam.
O que os scripts pré e pós-requisição realmente fazem
O Apidog executa scripts em duas etapas, e os nomeia de forma clara.
Os Pré-Processadores são executados antes da requisição ser enviada ao servidor. É aqui que você prepara as coisas: gera um timestamp, calcula uma assinatura, define um ID de pedido aleatório ou lê uma variável e a formata em um cabeçalho. A resposta ainda não existe neste ponto, então qualquer coisa que inspecione uma resposta está fora dos limites aqui.
Os Pós-Processadores são executados depois que a resposta é recebida. É aqui que você verifica o que retornou com asserções, e onde você extrai valores do corpo para reutilizar mais tarde. Extraia um token de autenticação, pegue um ID de recurso recém-criado, verifique o código de status, salve um cursor para paginação.
Duas regras decorrem dessa divisão. Primeiro, pm.response (com seu code, status, headers, responseTime, responseSize, text() e json()) só funciona em Pós-Processadores. Não há resposta para ler antes de enviar, então chamá-lo em um Pré-Processador não o ajudará. Segundo, as variáveis são como as duas etapas se comunicam. Um Pré-Processador define um valor, a requisição o usa, e um Pós-Processador pode lê-lo ou sobrescrevê-lo.
Se você está vindo do Postman, observe a mudança de rótulo logo de cara. As abas do Apidog são Pré-Processadores e Pós-Processadores, não "Pre-request Script" e "Tests". O comportamento é bastante semelhante, mas os nomes na tela são diferentes.
Configuração: abra uma requisição e encontre as abas
Baixe o Apidog para acompanhar. É gratuito e funciona em macOS, Windows e Linux, então pegue-o na página de Download do Apidog se você ainda não o tem.
Abra a requisição da API que você deseja roteirizar dentro do Apidog. Cada endpoint tem uma aba de Pré-Processadores e uma aba de Pós-Processadores ao lado das abas usuais de Params, Headers e Body. Para adicionar lógica a qualquer uma das etapas, abra a aba e selecione adicionar um Script Personalizado. Isso abre um editor de código onde você escreve JavaScript puro contra o objeto pm.
Antes de escrever qualquer coisa, é útil saber onde os valores residem. O Apidog resolve variáveis nesta ordem de prioridade:
Variáveis Locais > Variáveis de Ambiente > Variáveis Globais Compartilhadas dentro do Projeto > Variáveis Globais Compartilhadas dentro da Equipe.
Assim, uma variável local prevalece sobre uma variável de ambiente com o mesmo nome, e assim por diante. Mantenha isso em mente quando um valor não for o que você espera: algo mais alto na ordem provavelmente está ofuscando-o. Se você deseja valores que persistam em muitas requisições, os parâmetros globais no Apidog ficam mais abaixo na ordem de prioridade e são um bom lugar para configurações estáveis e de todo o projeto.
Exemplo de Pré-Processador: assinar uma requisição com HMAC
Digamos que você chame um endpoint de pagamentos que autentica cada requisição com uma assinatura HMAC-SHA256. Este é o mesmo padrão que muitos provedores usam para verificação de webhook, e a documentação de assinatura do Stripe descreve-o bem: o servidor espera um timestamp e uma assinatura calculada sobre esse timestamp mais o corpo da requisição, chaveada com seu segredo de API. Você precisa construir ambos frescos a cada envio.
O Apidog vem com crypto-js como uma biblioteca embutida, então você não precisa instalar nada. Abra a aba de Pré-Processadores, selecione adicionar um Script Personalizado, e escreva isto:
// Pre Processor: sign the request before it is sent
const CryptoJS = require('crypto-js');
// current unix timestamp in seconds
const timestamp = Math.floor(Date.now() / 1000).toString();
// read the secret from an environment variable
const secret = pm.environment.get('payments_api_secret');
// build the string to sign: timestamp + newline + raw body
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;
// compute the HMAC-SHA256 signature, hex encoded
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
// stash both values as environment variables for the request to use
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);
pm.console.log('Signed request at ' + timestamp);
Esse script calcula a assinatura e salva tanto o timestamp quanto a assinatura em variáveis de ambiente. Agora, conecte-os à requisição. Na aba Headers, referencie os valores armazenados com a sintaxe {{variableName}}:
X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Ao enviar, o Apidog executa o Pré-Processador primeiro, define as duas variáveis e, em seguida, as substitui nos cabeçalhos. O servidor recebe uma assinatura válida no momento do envio, sempre, sem nenhuma etapa manual. Observe que a chamada require('crypto-js') importa o módulo inteiro. Você importa a biblioteca completa, não um submódulo, então require('crypto-js') funciona e require('crypto-js/sha256') não.
Uma coisa a observar: as operações de variáveis afetam apenas os valores atuais, não os valores iniciais que você pode ter digitado no editor de ambiente. É isso que você deseja aqui, já que a assinatura é efêmera. Se você precisar de padrões de assinatura explicados também para o lado do Postman, o guia sobre scripts pré-requisição do Postman aborda a mesma ideia com os rótulos do Postman, e ele se adapta perfeitamente aos Pré-Processadores do Apidog.
Exemplo de Pós-Processador: extrair um token e asserção
Agora, a outra etapa. Imagine uma requisição de login que retorna um token que você precisa para cada chamada autenticada posteriormente:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": 4812, "email": "dana@example.com" },
"expires_in": 3600
}
Abra a aba de Pós-Processadores, selecione adicionar um Script Personalizado, e extraia o token do corpo, salvando-o para requisições posteriores:
// Post Processor: verify the response, then extract the token
pm.test('Status is 200', function () {
pm.response.to.have.status(200);
});
const jsonData = pm.response.json();
pm.test('Response returns a token', function () {
pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});
pm.test('User id is present', function () {
pm.expect(jsonData.user.id).to.be.a('number');
});
// store the token so other requests can send it
pm.environment.set('auth_token', jsonData.token);
pm.console.log('Saved token for user ' + jsonData.user.email);
Duas coisas acontecem aqui. Os blocos pm.test() afirmam que a resposta está formatada da maneira que você espera, usando matchers pm.expect() no estilo Chai que o Apidog suporta nativamente. E pm.environment.set('auth_token', jsonData.token) salva o token no ambiente. Qualquer requisição posterior pode agora enviar Authorization: Bearer {{auth_token}} sem que você precise copiar nada manualmente.
A parte de asserção merece atenção por si só. Boas verificações pós-resposta são o que transformam um clique manual e uma inspeção visual em um teste real, e nosso guia sobre asserções de API no Apidog aprofunda nos matchers e padrões que valem a pena conhecer. Se você também quiser alimentar dados falsos realistas nesses fluxos, Faker.js no Apidog combina bem com a configuração de variáveis mostrada acima.
Alguns comportamentos a serem observados nos Pós-Processadores. pm.iterationData (seus dados de teste) é somente leitura, então você pode ler um valor orientado a dados, mas não pode escrever nele a partir de um script. E pm.cookies retorna o cookie da resposta, aquele que o servidor enviou de volta, não o cookie que foi enviado com sua requisição.
Reutilizar lógica com Scripts Públicos
Depois de escrever esse bloco de assinatura HMAC, você provavelmente o desejará em mais de uma requisição. Copiá-lo e colá-lo em dez endpoints significa dez lugares para corrigir quando o algoritmo mudar. A resposta do Apidog são os Scripts Públicos: trechos reutilizáveis que você escreve uma vez e anexa onde for necessário.
Crie um em Configurações > Scripts Públicos e, em seguida, adicione-o à aba de Pré-Processadores ou Pós-Processadores de uma requisição. Dentro de uma lista de processadores, um Script Público e um Script Personalizado ficam lado a lado, e a ordem importa: os scripts públicos são executados antes dos scripts personalizados na mesma lista, e se você tiver vários scripts públicos, eles são executados de cima para baixo na ordem listada.
Há um detalhe que costuma confundir as pessoas. Se você quiser que um Script Personalizado chame uma função definida em um Script Público, essa função precisa ser global. Uma declaração de function normal ou uma função vinculada a const é local ao seu próprio script e invisível para o próximo. Declare-a atribuindo sem var, let ou const:
// In the Public Script: make sign() global by omitting the keyword
sign = function (payload, secret) {
const CryptoJS = require('crypto-js');
return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
// In the Custom Script below it: call the global function by name
const timestamp = Math.floor(Date.now() / 1000).toString();
const secret = pm.environment.get('payments_api_secret');
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', sign(timestamp, secret));
Adicione o Script Público primeiro, coloque o Script Personalizado abaixo dele, e a chamada será resolvida. Erre a ordem ou adicione um const e você receberá um erro de função indefinida.
Bibliotecas, pacotes externos e depuração
A importação de crypto-js acima é uma de um conjunto de bibliotecas que o Apidog inclui sem necessidade de configuração. Você pode usar require() para qualquer uma delas diretamente:
crypto-js(v3.1.9-1) para hashing e HMACjsrsasign(v10.3.0) para trabalho com JWT e RSA, que requer Apidog 1.4.5 ou posteriorchai(v4.2.0) para os matchers de asserçãolodash,moment,uuid,xml2js,cheerio,postman-collection,atob,btoa,csv-parse/lib/sync,tv4,ajv- Módulos nativos do Node como
path,assert,buffer,util,url,querystring,streameevents
Se você precisar de algo que não esteja nessa lista, importe-o em tempo de execução com $$.liveRequire(), que busca o pacote na hora:
$$.liveRequire('nanoid', (nanoid) => {
const id = nanoid.nanoid();
pm.environment.set('request_id', id);
});
Esse caminho requer uma conexão com a internet, já que o Apidog baixa o pacote quando o script é executado. As bibliotecas empacotadas não.
Quando um script se comporta mal, use logs para depurar. Tanto pm.console.log() quanto o simples console.log() imprimem no console do Apidog, para que você possa despejar uma assinatura computada ou um campo extraído e ver exatamente o que o script produziu antes da requisição ser enviada ou depois de retornar.
Mais dois limites que valem a pena mencionar para não o surpreenderem. pm.sendRequest(), para disparar uma chamada HTTP extra dentro de um script, usa um padrão de callback em vez de Promises, então escreva-o com um callback, não com await. E o pm.nextRequest() do Postman para encadear requisições não é suportado aqui. Quando você precisa de orquestração de fluxo de trabalho real, com ramificações e etapas condicionais, o Apidog usa Cenários de Teste, onde você sequencia requisições visualmente com etapas de Condição e If-Else. Se você escreve muitos scripts, o Gerador de Scripts Apidog integrado também pode rascunhar um a partir de uma descrição em linguagem natural para lhe dar um ponto de partida.
Automatize o fluxo de trabalho com a CLI do Apidog
Scripts não são executados apenas quando você clica em Enviar. Quando você empacota suas requisições e asserções em um Cenário de Teste salvo, a CLI do Apidog executa todo esse cenário sem interface, incluindo Pré-Processadores e Pós-Processadores, o que torna sua lógica de assinatura e extração de token parte da CI em vez de uma etapa manual.
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli
A flag -t é o ID do cenário de teste, -e é o ID do ambiente, e -r seleciona o relatório (cli, html, ou junit, separados por vírgula para vários). Gere o token de acesso nas configurações da sua conta Apidog, exporte-o como APIDOG_ACCESS_TOKEN, e o mesmo cenário que rodou no seu desktop agora roda na CI, incluindo Pré-Processadores e Pós-Processadores.
Uma ressalva honesta: um script que depende de algo presente apenas na sua máquina, um arquivo local ou um pacote que você carregou uma vez, pode funcionar no aplicativo de desktop e falhar na CLI, porque o executor não tem essa dependência. Mantenha os scripts restritos às bibliotecas empacotadas ou $$.liveRequire() para que funcionem da mesma forma em todos os lugares.
FAQ
Os scripts do Apidog são compatíveis com meus scripts Postman existentes?
Em grande parte, sim. O motor do Apidog usa a mesma API de objeto pm, então pm.environment.set(), pm.response.json(), pm.test() e pm.expect() se comportam da maneira que você já conhece. As duas diferenças a serem lembradas são os nomes das abas, Pré-Processadores e Pós-Processadores em vez de Pre-request Script e Tests, e algumas chamadas não suportadas como pm.nextRequest(). A maioria dos scripts pode ser copiada e executada.
Por que pm.response retorna indefinido no meu script pré-requisição?
Porque ainda não há resposta. Os Pré-Processadores são executados antes da requisição ser enviada, então nada retornou para ser inspecionado. Qualquer código que lê pm.response (seu status, corpo, cabeçalhos) pertence a um Pós-Processador. Se você precisa de um valor na etapa prévia, recupere-o de pm.request, de uma variável ou de uma biblioteca.
Como faço para compartilhar um script entre várias requisições?
Use os Scripts Públicos em Configurações > Scripts Públicos. Escreva a lógica uma vez, anexe-a à aba de Pré-Processadores ou Pós-Processadores de cada requisição, e lembre-se que os scripts públicos são executados antes dos scripts personalizados na mesma lista. Para chamar uma função de Script Público a partir de um Script Personalizado, declare-a globalmente atribuindo sem var, let ou const.
Posso importar um pacote npm que o Apidog não inclui?
Sim, com $$.liveRequire('package-name', (pkg) => { ... }), que baixa o pacote em tempo de execução e precisa de uma conexão com a internet. Para qualquer item da lista integrada, como crypto-js, moment ou uuid, use um require() simples sem necessidade de rede. Note que você só pode importar um módulo completo, não um caminho de submódulo.
Onde vejo o que meu script imprimiu?
Use pm.console.log() ou console.log() e leia a saída no console do Apidog depois de enviar a requisição. É a maneira mais rápida de confirmar se uma assinatura foi computada ou um token foi extraído antes de confiar nele em um cenário.
Conclusão
Pré-Processadores e Pós-Processadores transformam uma requisição estática em uma que se prepara e verifica seu próprio trabalho. Assine antes de enviar, extraia e faça asserções depois de receber, e eleve a lógica compartilhada para Scripts Públicos para que você a escreva apenas uma vez. A API pm e as bibliotecas incluídas significam que a maior parte do que você conhece do Postman se transfere diretamente. Abra o Apidog, escolha qualquer requisição e adicione seu primeiro Script Personalizado para ver ambas as etapas serem executadas em um único envio. É gratuito para começar, sem necessidade de cartão de crédito.