DEV Community

Cover image for Variável Postman Não Persiste no Runner: Causa e Solução
Lucas
Lucas

Posted on • Originally published at apidog.com

Variável Postman Não Persiste no Runner: Causa e Solução

#api #testing #tooling #tutorial

Em resumo

Variáveis definidas em scripts do Postman podem “sumir” quando você troca a execução manual pelo Collection Runner. Na prática, quase sempre é um problema de escopo: pm.environment.set escreve no ambiente ativo, variáveis de coleção têm outro ciclo de vida, e o runner pode descartar alterações ao final da execução.

Experimente o Apidog hoje

Neste guia, você vai ver como diagnosticar o problema, escolher o escopo correto e corrigir os casos mais comuns. Também verá como o Apidog lida com variáveis de forma mais explícita na interface.

Introdução

Você testa uma API manualmente no Postman:

  1. Executa a requisição de login.
  2. Um script salva o token.
  3. As próximas requisições usam {{token}}.
  4. Tudo funciona.

Depois você clica em Run Collection. O login retorna sucesso, mas a próxima requisição falha com 401 Unauthorized. O token não foi encontrado.

Esse comportamento é comum porque o modo manual e o Collection Runner não lidam com o estado das variáveis exatamente da mesma forma.

A correção começa entendendo a hierarquia de escopos do Postman.

Hierarquia de escopo de variáveis do Postman

O Postman resolve variáveis seguindo uma ordem de prioridade. Da maior para a menor:

  1. Variáveis locais: existem apenas durante a execução do script atual.
  2. Variáveis de dados: vêm de arquivos CSV ou JSON usados em execuções orientadas por dados.
  3. Variáveis de coleção: pertencem à coleção e podem ser usadas por requisições dentro dela.
  4. Variáveis de ambiente: pertencem ao ambiente selecionado.
  5. Variáveis globais: ficam disponíveis para qualquer coleção e ambiente.

Quando você usa:

{{token}}
Enter fullscreen mode Exit fullscreen mode

o Postman procura token nessa ordem e usa o primeiro valor encontrado.

Isso significa que o problema nem sempre é “a variável não existe”. Às vezes ela existe, mas em outro escopo, ou um escopo de maior prioridade está sobrescrevendo o valor esperado.

Por que as variáveis desaparecem no Collection Runner

1. Valor inicial vs. valor atual

Cada variável no Postman pode ter dois valores:

  • Valor inicial: sincronizado e compartilhado com a equipe.
  • Valor atual: local à sua máquina.

Quando você executa este código:

pm.environment.set('token', pm.response.json().access_token);
Enter fullscreen mode Exit fullscreen mode

o Postman atualiza o valor atual do ambiente ativo.

No modo manual, isso costuma funcionar porque você continua usando a mesma sessão e o mesmo ambiente selecionado.

No Collection Runner, a execução começa a partir do estado do ambiente no início da execução. As variáveis atualizadas durante a execução podem funcionar para as próximas requisições daquela mesma execução, mas podem não ser preservadas depois que o runner termina.

2. pm.environment.set exige um ambiente ativo

Este código escreve no ambiente selecionado:

pm.environment.set('token', pm.response.json().access_token);
Enter fullscreen mode Exit fullscreen mode

Se nenhum ambiente estiver selecionado, não há onde salvar esse valor. O resultado prático é que sua próxima requisição pode não encontrar {{token}}.

Antes de executar uma coleção, verifique se o ambiente correto está selecionado no runner.

3. O runner pode redefinir variáveis após a execução

No Collection Runner, existe a opção Keep variable values / Manter valores de variáveis.

Se ela estiver desmarcada, alterações feitas por scripts durante a execução podem ser descartadas ao final. Isso causa a impressão de que pm.environment.set “não funcionou”, mesmo que ele tenha funcionado durante a execução.

Correções práticas

Correção 1: marque “Manter valores de variáveis” no runner

Use esta correção quando você quer que os valores definidos durante a execução sejam preservados depois que o runner terminar.

Passos:

  1. Abra o Collection Runner.
  2. Selecione sua coleção.
  3. Selecione o ambiente correto.
  4. Marque Manter valores de variáveis.
  5. Execute a coleção.

Use quando você precisa persistir valores como:

  • token de autenticação;
  • refresh token;
  • IDs criados durante a execução;
  • valores usados por execuções posteriores.

Evite quando você roda múltiplas iterações e não quer que o estado da iteração anterior afete a próxima.

Correção 2: use variáveis de coleção para estado interno da coleção

Se o token é gerado e consumido dentro da mesma coleção, prefira pm.collectionVariables.

No script pós-resposta da requisição de login:

const response = pm.response.json();

pm.collectionVariables.set('token', response.access_token);
Enter fullscreen mode Exit fullscreen mode

Nas requisições seguintes, use diretamente:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Ou leia no script de pré-requisição:

const token = pm.collectionVariables.get('token');

console.log('collection token:', token);
Enter fullscreen mode Exit fullscreen mode

Variáveis de coleção são úteis quando:

  • o valor só importa dentro daquela coleção;
  • você não quer depender de um ambiente selecionado;
  • você quer reduzir conflitos com outras coleções;
  • você está executando a coleção no runner.

Correção 3: selecione um ambiente antes de usar pm.environment.set

Se você precisa usar variáveis de ambiente, confirme o ambiente antes de rodar.

Checklist:

  1. Abra o Collection Runner.
  2. Localize o menu de ambiente.
  3. Selecione o ambiente correto.
  4. Execute a coleção.

Depois, no script, você pode validar se a variável foi gravada:

const token = pm.response.json().access_token;

pm.environment.set('token', token);

console.log('saved environment token:', pm.environment.get('token'));
Enter fullscreen mode Exit fullscreen mode

Se pm.environment.get('token') retornar undefined, revise se o ambiente está ativo e se o nome da variável está correto.

Correção 4: defina valores iniciais para variáveis obrigatórias

Variáveis como baseUrl, clientId ou scope geralmente precisam existir antes da primeira requisição.

Nesse caso, não dependa apenas do valor atual.

No editor de ambiente:

  1. Crie a variável.
  2. Defina o valor inicial.
  3. Defina também o valor atual, se necessário.
  4. Salve o ambiente.

Exemplo:

baseUrl = https://api.exemplo.com
Enter fullscreen mode Exit fullscreen mode

Se apenas o valor atual estiver definido, outro membro da equipe, uma execução em CI ou o Newman podem iniciar sem esse valor.

Correção 5: adicione logs para identificar o escopo usado

Use console.log para saber exatamente onde o valor está sendo lido.

No script de pré-requisição:

console.log('local token:', pm.variables.get('token'));
console.log('collection token:', pm.collectionVariables.get('token'));
console.log('environment token:', pm.environment.get('token'));
console.log('global token:', pm.globals.get('token'));
Enter fullscreen mode Exit fullscreen mode

No script pós-resposta do login:

const body = pm.response.json();

console.log('login response:', body);

pm.collectionVariables.set('token', body.access_token);

console.log('saved collection token:', pm.collectionVariables.get('token'));
Enter fullscreen mode Exit fullscreen mode

Abra o console em:

View > Show Postman Console
Enter fullscreen mode Exit fullscreen mode

ou:

Exibir > Mostrar Console do Postman
Enter fullscreen mode Exit fullscreen mode

Os logs ajudam a responder três perguntas:

  1. O script foi executado?
  2. O valor foi extraído corretamente da resposta?
  3. A variável foi salva no escopo esperado?

Correção 6: evite nomes duplicados entre escopos

Se você tem token em variáveis de ambiente e também em variáveis de coleção, o Postman pode resolver um valor diferente do que você espera.

Exemplo problemático:

environment.token = token-antigo
collection.token = token-novo
Enter fullscreen mode Exit fullscreen mode

Ao usar:

{{token}}
Enter fullscreen mode Exit fullscreen mode

o Postman aplica a prioridade de escopo. Para evitar ambiguidade:

  • use nomes mais específicos;
  • remova variáveis antigas;
  • registre os escopos no console;
  • padronize onde tokens temporários devem ser salvos.

Exemplo de nomes mais claros:

authToken
collectionAuthToken
environmentAuthToken
Enter fullscreen mode Exit fullscreen mode

Exemplo completo: login salva token para a coleção

Requisição de login

Script pós-resposta:

pm.test('login retornou 200', function () {
  pm.response.to.have.status(200);
});

const json = pm.response.json();

pm.test('resposta contém access_token', function () {
  pm.expect(json.access_token).to.exist;
});

pm.collectionVariables.set('token', json.access_token);

console.log('token salvo na coleção:', pm.collectionVariables.get('token'));
Enter fullscreen mode Exit fullscreen mode

Requisição protegida

Header:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Script de pré-requisição:

const token = pm.collectionVariables.get('token');

if (!token) {
  throw new Error('Token não encontrado em variáveis de coleção');
}

console.log('usando token:', token);
Enter fullscreen mode Exit fullscreen mode

Esse padrão evita depender de ambiente para um valor que só precisa existir durante a execução da coleção.

Quando usar cada escopo

Escopo Use para Evite quando
Local Valores temporários dentro de um único script Você precisa compartilhar entre requisições
Dados Iterações com CSV/JSON O valor precisa ser alterado por scripts
Coleção Tokens e IDs usados dentro da mesma coleção O valor precisa ser compartilhado entre várias coleções
Ambiente baseUrl, credenciais e configs por ambiente O valor é temporário e específico de uma execução
Global Valores realmente compartilhados entre tudo Há risco de colisão de nomes

Como o Apidog gerencia o escopo de variáveis

O Apidog usa uma hierarquia de escopo compatível com o modelo do Postman: global, ambiente, coleção e local.

A diferença principal está na experiência de configuração. No editor de variáveis do Apidog, valores iniciais e atuais são exibidos de forma mais explícita, reduzindo a chance de configurar apenas o valor atual sem perceber.

O Apidog também suporta scripts compatíveis com Postman, incluindo:

pm.environment.set('token', value);
pm.environment.get('token');

pm.collectionVariables.set('token', value);
pm.collectionVariables.get('token');
Enter fullscreen mode Exit fullscreen mode

Quando um script atualiza uma variável, a interface mostra a alteração, facilitando a depuração do estado durante a execução.

O runner do Apidog preserva o estado das variáveis entre requisições de uma execução, a menos que você configure outro comportamento. Isso tende a se aproximar do que muitos desenvolvedores esperam ao migrar de testes manuais para execuções automatizadas.

Resumo dos erros comuns

Erro Sintoma Correção
Nenhum ambiente selecionado pm.environment.set não salva onde você espera Selecione um ambiente ou use variáveis de coleção
Apenas valor atual definido Variável ausente na CI ou na máquina de outro membro da equipe Defina o valor inicial no editor de ambiente
“Manter valores de variáveis” desmarcado Variáveis redefinidas após o fim do runner Marque “Manter valores de variáveis” na configuração do runner
Variáveis de ambiente usadas para estado temporário da coleção Funciona manualmente, mas falha no runner Use pm.collectionVariables.set
Mesmo nome em vários escopos O valor usado não é o esperado Registre os escopos no console e remova duplicidades

FAQ

Por que pm.environment.set funciona no modo manual, mas não no runner?

No modo manual, você costuma trabalhar com uma sessão persistente e um ambiente já selecionado. No runner, o ambiente é carregado no início da execução e pode ser redefinido no final.

As variáveis definidas durante a execução ainda podem funcionar para requisições seguintes na mesma execução, mas não necessariamente serão preservadas depois que o runner terminar.

Qual é a diferença entre pm.environment.set e pm.collectionVariables.set?

pm.environment.set grava no ambiente ativo:

pm.environment.set('token', token);
Enter fullscreen mode Exit fullscreen mode

Use para valores ligados a um ambiente, como:

dev
staging
production
Enter fullscreen mode Exit fullscreen mode

pm.collectionVariables.set grava na coleção:

pm.collectionVariables.set('token', token);
Enter fullscreen mode Exit fullscreen mode

Use para valores que só importam dentro daquela coleção ou execução.

Este problema também ocorre no Newman?

Sim. O Newman usa o mesmo modelo de escopo.

Por padrão, ele inicia com os valores do ambiente exportado e não persiste alterações após a execução, a menos que você exporte o estado final.

Exemplo:

newman run collection.json \
  -e environment.json \
  --export-environment environment.updated.json
Enter fullscreen mode Exit fullscreen mode

Depois, você pode usar environment.updated.json na próxima execução.

O que faz a flag --export-environment no Newman?

Ela salva o estado final do ambiente em um arquivo JSON, incluindo variáveis atualizadas por scripts durante a execução.

Isso é útil em pipelines onde uma etapa gera um token e outra etapa precisa reutilizá-lo.

O Apidog suporta pm.collectionVariables.set?

Sim. O Apidog suporta APIs de script compatíveis com Postman, incluindo:

pm.collectionVariables.set('token', value);
pm.collectionVariables.get('token');
pm.environment.set('token', value);
pm.environment.get('token');
Enter fullscreen mode Exit fullscreen mode

Coleções migradas do Postman podem usar a mesma sintaxe de script.

Como passar variáveis de uma coleção para outra no Postman?

Use variáveis globais:

pm.globals.set('token', value);
Enter fullscreen mode Exit fullscreen mode

E leia com:

const token = pm.globals.get('token');
Enter fullscreen mode Exit fullscreen mode

Use com cuidado. Variáveis globais não têm escopo por coleção e podem causar colisões de nomes, especialmente em equipes.

Conclusão

Quando uma coleção passa manualmente, mas falha no Collection Runner, revise o escopo das variáveis antes de investigar a API.

Na maioria dos casos, a correção é uma destas:

  1. selecionar o ambiente correto;
  2. marcar Manter valores de variáveis;
  3. trocar pm.environment.set por pm.collectionVariables.set;
  4. definir valores iniciais para variáveis obrigatórias;
  5. usar logs para confirmar qual escopo está sendo lido.

Com esses ajustes, suas execuções ficam mais previsíveis e seus testes de API deixam de depender de estado implícito da sessão manual.

Top comments (0)