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

Em resumo

Variáveis definidas durante a execução manual de requisições frequentemente desaparecem quando você executa a mesma coleção no Collection Runner do Postman. A causa raiz é uma incompatibilidade de escopo de variável: pm.environment.set se comporta de forma diferente no runner do que no modo manual, e as variáveis de coleção funcionam de forma diferente das variáveis de ambiente. Este guia explica exatamente por que isso acontece e como corrigir, e então mostra como o Apidog gerencia o escopo de variáveis de uma maneira mais difícil de ser acidentalmente mal configurada.

Introdução

Você tem testado uma API manualmente no Postman. Você executa uma requisição de login, o script de pré-requisição define um token de autenticação, e as requisições subsequentes o capturam sem problemas. Tudo funciona.

Então você clica em "Executar Coleção" (Run Collection). O runner inicia, a requisição de login é bem-sucedida, mas a próxima requisição falha com um 401. O token não está lá.

Este cenário aparece repetidamente no Stack Overflow e nos fóruns da comunidade Postman. As respostas geralmente apontam para o escopo de variável, mas raramente explicam o panorama completo de por que o comportamento difere entre o teste manual e o runner.

Entender isso requer compreender a hierarquia de escopo de variáveis do Postman. Uma vez que você a veja claramente, a correção é direta.

Hierarquia de escopo de variáveis do Postman

Postman possui cinco escopos de variáveis, listados da maior para a menor prioridade:

1. Variáveis Locais – disponíveis apenas dentro da execução do script atual, não acessíveis entre requisições
2. Variáveis de Dados – carregadas de um arquivo CSV ou JSON para execuções orientadas por dados
3. Variáveis de Coleção – com escopo na coleção, persistem entre requisições nessa coleção
4. Variáveis de Ambiente – com escopo no ambiente selecionado, persistem entre coleções
5. Variáveis Globais – disponíveis em qualquer coleção em qualquer ambiente

Quando o Postman resolve uma referência de variável como {{token}}, ele percorre esta lista e usa a primeira correspondência que encontra.

O problema é que "persistir" significa coisas diferentes dependendo de como você está executando a coleção.

Por que as variáveis desaparecem no Collection Runner

A distinção entre valor atual e valor inicial

Toda variável do Postman possui dois campos: "valor inicial" e "valor atual".

• Valor inicial é sincronizado com a nuvem do Postman e compartilhado com colegas de equipe.
• Valor atual é local à sua máquina e nunca é sincronizado.

Quando você define uma variável programaticamente em um script usando pm.environment.set('token', valor), o Postman atualiza o valor atual no seu ambiente ativo.

No modo de teste manual, isso funciona como esperado porque seus valores atuais locais persistem entre execuções de requisições individuais dentro da mesma sessão.

No Collection Runner, o comportamento muda. O runner inicia cada execução a partir do estado atual do ambiente no início da execução. Scripts que atualizam variáveis durante a execução funcionam corretamente dentro dessa execução. Mas se o runner estiver configurado para limpar variáveis entre execuções, ou se o valor inicial estiver vazio e o runner usar um snapshot de ambiente "fresco", você pode acabar em um estado onde seu script é executado, mas a variável não parece persistir.

A questão da variável de ambiente vs. variável de coleção

Aqui está a armadilha mais comum. Você está definindo uma variável em um script pós-resposta:

pm.environment.set('token', pm.response.json().access_token);

Isso define uma variável no ambiente ativo. Mas o Collection Runner tem uma opção chamada "Manter valores de variáveis" (Keep variable values). Se esta caixa de seleção estiver desmarcada (o padrão é desmarcada), o runner redefine as variáveis de ambiente para seus valores iniciais após a execução. Qualquer valor definido durante a execução é descartado.

Se você estiver executando a coleção sem um ambiente selecionado, pm.environment.set falha silenciosamente. Não há ambiente para escrever. A variável desaparece.

A incompatibilidade de escopo entre o modo manual e o modo runner

No teste manual, você tipicamente tem um ambiente selecionado e ele persiste por toda a sua sessão do Postman. Quando você executa uma requisição, define uma variável e executa outra requisição, todas elas acontecem no mesmo contexto de ambiente persistente.

O Collection Runner cria um contexto de execução separado. Ele carrega o estado do ambiente no início, executa todas as requisições e então (a menos que você marque "Manter valores de variáveis") retorna o ambiente ao seu estado pré-execução.

Isso significa que as variáveis definidas por uma requisição no runner estão disponíveis para requisições subsequentes na mesma execução, mas elas não persistem no seu painel de ambiente após o término da execução, a menos que você as mantenha explicitamente.

Correções

Correção 1: Marque "Manter valores de variáveis" no runner

No Collection Runner, antes de clicar em "Executar":

1. Procure pela opção "Manter valores de variáveis" no painel de configuração do runner.
2. Marque esta caixa.

Isso informa ao runner para escrever de volta quaisquer alterações de variáveis para o seu ambiente ativo após a conclusão da execução. Variáveis definidas por scripts durante a execução serão visíveis no seu painel de ambiente quando a execução terminar.

Quando usar isso: Quando você deseja que o runner atualize o estado compartilhado, como atualizar um token de autenticação que outras ferramentas ou execuções subsequentes usarão.

Quando não usar isso: Quando você estiver executando múltiplas iterações e as variáveis definidas na iteração 1 poluíssem a iteração 2. Nesse caso, use arquivos de dados ou redefina as variáveis explicitamente no início de cada iteração.

Correção 2: Use variáveis de coleção em vez de variáveis de ambiente para o estado intra-execução

// No script pós-resposta da sua requisição de login:
pm.collectionVariables.set('token', pm.response.json().access_token);

// No script de pré-requisição de requisições subsequentes:
const token = pm.collectionVariables.get('token');

As variáveis de coleção estão sempre disponíveis no runner, independentemente de um ambiente estar selecionado. Elas persistem pela duração da execução da coleção. São o escopo certo para valores que são definidos e consumidos dentro de uma única coleção.

Correção 3: Garanta que um ambiente esteja selecionado antes de executar

pm.environment.set falha silenciosamente quando nenhum ambiente está ativo. Antes de executar a coleção:

1. Abra o Collection Runner.
2. Verifique se um ambiente está selecionado no menu suspenso "Ambiente".
3. Se você não precisar de variáveis de nível de ambiente, use variáveis de coleção (Correção 2).

Correção 4: Use valores iniciais para variáveis que sempre devem existir

Se uma variável como baseUrl precisar estar disponível desde a primeira requisição em uma execução, defina-a como o valor inicial em seu ambiente, não apenas o valor atual.

No editor de ambiente:

• Defina o campo "Valor inicial", não apenas o campo "Valor atual".
• O valor inicial é o que o runner usa como estado inicial.

Se apenas o valor atual for definido e o runner não tiver acesso aos seus valores atuais locais (por exemplo, um colega de equipe executando a coleção, ou uma execução Newman/Apidog CLI), a variável começa vazia.

Correção 5: Depure com registro no console

Adicione console.log aos seus scripts de pré-requisição e pós-resposta para ver exatamente o que está acontecendo:

// Script de pré-requisição
console.log('token before request:', pm.collectionVariables.get('token'));
console.log('environment token:', pm.environment.get('token'));

Abra o Console do Postman (Exibir > Mostrar Console do Postman) antes de executar a coleção. Os logs mostrarão exatamente de qual escopo cada variável está sendo lida e qual valor ela contém em cada etapa.

Como o Apidog gerencia o escopo de variáveis

O Apidog usa a mesma hierarquia de escopo: global, ambiente, coleção e local. A principal diferença está na interface do usuário.

No editor de variáveis do Apidog, os valores iniciais e atuais são exibidos com rótulos e cores explícitas. A interface torna mais difícil definir acidentalmente apenas o valor atual. Quando um script define uma variável usando pm.environment.set (que o Apidog suporta para compatibilidade com o Postman), o painel de ambiente atualiza visualmente em tempo real para que você possa ver a mudança acontecer.

O test runner do Apidog também não redefine os valores das variáveis entre as etapas, a menos que você o configure explicitamente para isso. O comportamento padrão é preservar o estado das variáveis entre as requisições em uma execução, o que corresponde ao que a maioria dos desenvolvedores espera do teste manual.

Para cenários de equipe, o modelo local-first do Apidog significa que as variáveis de ambiente são armazenadas em disco. Não há sincronização na nuvem que sobrescreva seus valores atuais entre execuções.

Resumo dos erros comuns

FAQ

Por que pm.environment.set funciona no modo manual, mas não no runner?No modo manual, você tem uma sessão de ambiente persistente. No runner, o ambiente é carregado no início da execução e, por padrão, redefinido no final. Scripts que definem variáveis durante a execução ainda funcionam para requisições subsequentes nessa execução, mas as alterações não persistem no seu ambiente a menos que "Manter valores de variáveis" esteja marcado.

Qual a diferença entre pm.environment.set e pm.collectionVariables.set?pm.environment.set escreve para o ambiente ativo, que é compartilhado entre todas as coleções que usam esse ambiente. pm.collectionVariables.set escreve para um escopo ligado à coleção específica. Para valores que só importam dentro de uma execução de coleção, variáveis de coleção são mais apropriadas e não exigem que um ambiente seja selecionado.

Este problema ocorre no Newman?Sim. O Newman tem o mesmo modelo de escopo. Por padrão, o Newman inicia cada execução com os valores iniciais do ambiente exportado e não persiste as alterações após a execução, a menos que você use a flag --export-environment para escrever o estado final do ambiente em um arquivo.

O que é a flag --export-environment no Newman?Ela informa ao Newman para escrever o estado final do ambiente, incluindo quaisquer valores definidos por scripts durante a execução, em um arquivo JSON após a conclusão da execução. Você pode então passar esse arquivo como o ambiente para a próxima execução. Isso é útil para pipelines onde uma execução gera tokens usados pela próxima.

O Apidog suporta pm.collectionVariables.set?Sim. O Apidog suporta a API de script completa do Postman, incluindo pm.collectionVariables.set, pm.collectionVariables.get, pm.environment.set e pm.environment.get. Coleções migradas do Postman usam a mesma sintaxe de script.

Como eu passo variáveis de uma coleção para outra no Postman?Use variáveis globais: pm.globals.set('token', valor). Variáveis globais persistem entre coleções e ambientes durante a vida útil da sessão do Postman. Tenha cuidado com esta abordagem em configurações de equipe, pois as variáveis globais não têm escopo e podem criar colisões de nomes.

Problemas de escopo de variáveis no Postman são uma das fontes mais confiáveis de falsos negativos em suítes de teste de API. Um teste que passa manualmente, mas falha no runner, não é um teste em que você pode confiar. Compreender o modelo de escopo, usar o setter correto para o contexto certo e marcar "Manter valores de variáveis" quando apropriado são os três passos que resolvem a maioria desses problemas.