Por que ambientes e variáveis são essenciais em testes de API
Em rotinas de QA com Postman, o mesmo conjunto de requisições costuma rodar em contextos diferentes: desenvolvimento, homologação, produção, ou ainda em múltiplos clientes/tenants. Ambientes e variáveis permitem que você troque esses contextos sem duplicar requisições, reduzindo manutenção e evitando erros como apontar acidentalmente para um host errado. A ideia central é parametrizar partes variáveis (URL base, credenciais, IDs dinâmicos, headers, payloads) e manter a Collection o mais estável possível.
Além disso, variáveis viabilizam encadear chamadas: você cria um recurso em uma requisição, captura o identificador retornado e usa esse valor nas próximas requisições. Isso transforma uma Collection em um fluxo automatizável e reprodutível, com menos intervenção manual.
O que são variáveis no Postman e como elas aparecem nas requisições
Uma variável no Postman é um par chave-valor que pode ser referenciado em praticamente qualquer parte da requisição usando a sintaxe {{nomeDaVariavel}}. Você pode usar variáveis em URL, query params, headers, body (JSON, form-data), scripts de pré-requisição e scripts de testes. Exemplo simples de URL parametrizada: {{baseUrl}}/v1/users/{{userId}}. Ao executar, o Postman resolve cada {{...}} para um valor conforme o escopo e a precedência.
Variáveis podem ser estáticas (definidas manualmente) ou dinâmicas (definidas/atualizadas por scripts). Também existem variáveis “geradas” por funções internas e variáveis de dados vindas de execução com datasets. Entender escopos e precedência é o que evita surpresas quando um valor “não troca” ou “troca errado”.
Scopes (escopos) de variáveis e o que cada um resolve
O Postman oferece diferentes escopos para variáveis. Cada escopo tem um “alcance” e um ciclo de vida. Os principais, do ponto de vista prático, são: Global, Environment, Collection e Local. Além deles, há variáveis de Data (quando você roda com um arquivo CSV/JSON) e variáveis dinâmicas internas (como {{$guid}}).
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
Global
Variáveis globais ficam disponíveis em qualquer lugar do workspace. São úteis para valores realmente universais, mas devem ser usadas com cautela porque aumentam o risco de colisão de nomes e de “vazar” configurações entre projetos. Em geral, prefira escopos mais específicos (Collection/Environment) para manter isolamento.
Environment
Variáveis de ambiente representam um contexto de execução (por exemplo, dev, hml, prod). É o escopo mais comum para valores que mudam conforme o servidor: baseUrl, credenciais de teste, chaves de API específicas, IDs de tenant, etc. Ao trocar o ambiente no seletor do Postman, os valores mudam sem alterar a Collection.
Collection
Variáveis de Collection ficam “presas” à Collection e são ótimas para padronizar nomes e defaults que não dependem do ambiente. Por exemplo, apiVersion (se for igual em todos os ambientes), caminhos comuns, ou flags de comportamento de testes. Também são úteis para evitar globais quando você quer que a variável exista apenas naquele conjunto de requisições.
Local
Variáveis locais existem apenas durante a execução de uma requisição (ou durante um script) e não são persistidas. Elas são ideais para valores temporários, como um timestamp calculado para aquele request, ou um valor intermediário usado para montar um payload. Você cria com pm.variables.set e lê com pm.variables.get.
Data (Runner/Newman)
Quando você executa uma Collection com um arquivo de dados (CSV/JSON), cada linha/objeto vira um conjunto de variáveis de “data”. Isso é essencial para testes orientados a dados: você roda o mesmo fluxo para múltiplos usuários, múltiplos pedidos, múltiplas combinações de parâmetros. Essas variáveis são acessadas diretamente por {{nomeColuna}} ou via pm.iterationData.get('nomeColuna').
Dynamic variables internas
O Postman oferece variáveis dinâmicas prontas, como {{$guid}}, {{$timestamp}}, {{$randomInt}}, {{$randomEmail}}. Elas ajudam a gerar dados únicos sem escrever lógica. Exemplo: { "email": "user_{{$timestamp}}@exemplo.com" }.
Precedência: qual valor o Postman usa quando há conflito
Se você definir a mesma variável em mais de um escopo, o Postman precisa decidir qual usar. A regra prática é: o escopo mais específico vence. Em termos comuns de execução, a ordem de prioridade costuma ser: Local (pm.variables) > Data (iteration data) > Environment > Collection > Global. Isso significa que, se baseUrl existir no Environment e também na Collection, o valor do Environment será usado. Se você definir um baseUrl local no pré-script, ele sobrescreve temporariamente os demais durante aquela execução.
Estratégia recomendada: evite reutilizar o mesmo nome em escopos diferentes sem necessidade. Quando fizer sentido ter “defaults” na Collection e sobrescrever no Environment, documente isso e mantenha um padrão consistente.
Current value vs Initial value: como isso afeta colaboração e segurança
Em variáveis de Environment (e também em Globals), o Postman costuma exibir dois campos: Initial Value e Current Value. O Initial Value é o que tende a ser compartilhado/sincronizado quando você exporta ou compartilha o ambiente (dependendo do modo de trabalho). O Current Value é o valor usado localmente na sua execução e pode ser diferente do inicial.
Uso prático: você pode manter no Initial Value um placeholder seguro (por exemplo, __INSIRA_TOKEN__) e no Current Value o token real na sua máquina. Isso reduz o risco de expor segredos ao versionar/exportar. Mesmo assim, trate tokens e chaves como segredos: prefira não colocá-los em texto claro em materiais compartilhados e use variáveis com nomes explícitos como authToken e apiKey para facilitar auditoria.
Estratégias de parametrização: padrões que reduzem manutenção
1) Parametrizar URL base e versão de API
Um padrão simples e eficaz é separar host e versão. Exemplo: {{baseUrl}}/{{apiVersion}}/users. Você pode manter apiVersion como variável de Collection e baseUrl como variável de Environment. Assim, trocar de ambiente não mexe na versão, e trocar de versão não exige editar cada request.
2) Parametrizar headers comuns
Se várias requisições usam os mesmos headers (por exemplo, Authorization, X-Tenant-Id, Accept-Language), use variáveis e, quando possível, defina esses headers no nível da Collection para reduzir repetição. Exemplo de header: Authorization: Bearer {{authToken}}. Para tenant: X-Tenant-Id: {{tenantId}}.
3) Parametrizar payloads com placeholders
Em bodies JSON, use variáveis para campos que mudam: { "name": "{{userName}}", "email": "{{userEmail}}" }. Para dados únicos, combine com variáveis dinâmicas: { "email": "qa_{{$guid}}@exemplo.com" }. Isso evita colisões em ambientes compartilhados e reduz flakiness.
4) Capturar IDs e tokens em runtime
Quando uma requisição cria um recurso, capture o ID retornado e salve em variável para as próximas etapas. Isso elimina a necessidade de “colar” IDs manualmente. O mesmo vale para tokens de autenticação obtidos por uma chamada específica: salve em authToken no Environment (ou Collection, dependendo do caso) e reutilize.
5) Separar variáveis “de configuração” e “de estado”
Uma prática que melhora muito a previsibilidade é separar variáveis em dois grupos: (a) configuração, que você define antes de rodar (ex.: baseUrl, tenantId), e (b) estado, que o fluxo gera (ex.: userId, orderId, authToken). Para variáveis de estado, prefira Environment ou Collection conforme o escopo do fluxo, e limpe-as quando necessário para evitar reaproveitar valores antigos.
Passo a passo: criando ambientes e usando variáveis na prática
Passo 1: criar ambientes (dev e hml) e definir baseUrl
No Postman, crie dois ambientes: dev e hml. Em cada um, adicione a variável baseUrl com o valor correspondente, por exemplo https://api.dev.suaempresa.com e https://api.hml.suaempresa.com. Se houver um identificador de tenant por ambiente, adicione tenantId também.
Selecione o ambiente ativo no canto superior direito e confirme que o valor de {{baseUrl}} muda ao alternar entre dev e hml.
Passo 2: criar variáveis de Collection para padrões estáveis
Abra as configurações da Collection e crie variáveis como apiVersion com valor v1 e defaultTimeoutMs com um valor padrão (se você usar isso em scripts). A ideia é guardar aqui o que é comum a todos os ambientes e específico daquela Collection.
Passo 3: aplicar variáveis em uma requisição
Edite uma requisição para usar a URL parametrizada: {{baseUrl}}/{{apiVersion}}/users. Em headers, use X-Tenant-Id: {{tenantId}} se aplicável. No body, use placeholders para campos variáveis. Esse padrão permite que a mesma requisição rode em qualquer ambiente sem edição manual.
Passo 4: capturar um ID retornado e reutilizar
Suponha que uma requisição de criação retorne um JSON com id. No script de testes dessa requisição, extraia e salve o valor em uma variável de Environment chamada userId. Exemplo:
const json = pm.response.json();pm.environment.set('userId', json.id);pm.test('Salvou userId no ambiente', function () { pm.expect(pm.environment.get('userId')).to.exist;});Agora, em outra requisição (por exemplo, buscar detalhes), use {{userId}} na URL: {{baseUrl}}/{{apiVersion}}/users/{{userId}}. Isso cria um encadeamento automático: criar > capturar ID > consultar.
Passo 5: usar variáveis locais para valores temporários
Em um pré-script, você pode montar um valor apenas para aquela execução, sem persistir no ambiente. Exemplo: gerar um e-mail único e guardar como variável local tempEmail:
const email = `qa_${Date.now()}@exemplo.com`;pm.variables.set('tempEmail', email);No body da requisição, use {{tempEmail}}. Como é local, não “polui” o ambiente e reduz o risco de usar acidentalmente um valor antigo em outra execução.
Passo 6: limpar variáveis de estado para evitar falsos positivos
Se o fluxo depende de variáveis como userId e orderId, pode ser útil limpá-las no início de uma execução (por exemplo, no pré-script de uma requisição inicial) para garantir que o teste falhe caso não consiga gerar novos valores. Exemplo:
pm.environment.unset('userId');pm.environment.unset('orderId');Isso evita que uma execução parcial reutilize IDs antigos e passe “por acidente”.
Parametrização avançada: dados por iteração (Data-driven)
Para rodar o mesmo conjunto de requisições com múltiplos dados, use o Runner (ou Newman) com um arquivo CSV/JSON. Exemplo de CSV com colunas userEmail e userName. No body, você referencia {{userEmail}} e {{userName}}. A cada iteração, o Postman injeta os valores da linha atual.
Quando precisar acessar esses dados em scripts, use pm.iterationData.get('userEmail'). Exemplo de validação simples:
pm.test('Email da iteração foi enviado', function () { const sent = pm.iterationData.get('userEmail'); pm.expect(sent).to.be.a('string');});Estratégia recomendada: use variáveis de Data para entradas (inputs) e variáveis de Environment/Collection para saídas (outputs) geradas pelo fluxo, como IDs criados.
Boas práticas de nomenclatura e organização de variáveis
Padrões de nomes consistentes
Adote nomes descritivos e estáveis: baseUrl, apiVersion, authToken, tenantId, userId, orderId. Evite nomes genéricos como id ou token, que podem colidir e gerar confusão em fluxos maiores.
Prefixos para diferenciar natureza
Quando o projeto cresce, prefixos ajudam: cfg_baseUrl para configuração, st_userId para estado, tmp_email para temporários. Isso facilita identificar o que pode ser compartilhado e o que é gerado em runtime.
Evitar segredos em variáveis compartilhadas
Para chaves e tokens, prefira manter placeholders no Initial Value e valores reais no Current Value. Se você precisa exportar ambientes, revise o arquivo exportado antes de compartilhar. Outra abordagem é usar variáveis locais para tokens de curta duração quando fizer sentido, ou scripts que renovem o token e o mantenham apenas no contexto de execução.
Erros comuns e como diagnosticar rapidamente
Variável não resolve e aparece como {{nome}}
Isso geralmente indica que a variável não existe no escopo ativo ou foi escrita com nome diferente (maiúsculas/minúsculas contam). Verifique: (1) se o ambiente correto está selecionado, (2) se a variável existe naquele ambiente/collection, (3) se não há espaços no nome, (4) se você não está usando um escopo diferente do esperado.
Valor “errado” porque existe em dois escopos
Se você definiu baseUrl na Collection e no Environment, o Environment vence. Se você esperava o valor da Collection, remova a duplicidade ou renomeie. Para depurar, use o console do Postman e imprima o valor resolvido: console.log('baseUrl=', pm.variables.get('baseUrl'));.
Variável de estado antiga causando teste instável
Se um fluxo falha no meio e você roda de novo, pode acabar usando um userId antigo. Limpe variáveis no início do fluxo com unset ou use variáveis locais quando o valor não precisa persistir entre requisições.
Dados de iteração não aparecem
Variáveis de Data só existem quando você roda via Runner/Newman com um arquivo de dados. Se você executar manualmente uma requisição, {{userEmail}} pode ficar vazio. Para tornar o request executável manualmente, você pode definir um fallback no Environment ou no script, mas faça isso conscientemente para não mascarar problemas.
Exemplo integrado: parametrizando um fluxo com ambiente, collection e estado
Imagine um fluxo com três etapas: criar usuário, consultar usuário, e atualizar usuário. Você define baseUrl e tenantId no Environment; define apiVersion na Collection; e captura userId como variável de Environment após a criação. No body de criação, você usa {{$guid}} para garantir unicidade do e-mail. Em seguida, as requisições seguintes usam {{userId}} na URL. Se quiser rodar o mesmo fluxo para múltiplos perfis, você injeta userName e outros campos via Data file, mantendo o encadeamento por userId gerado em runtime.
Esse arranjo separa claramente: o que muda por ambiente (host/tenant), o que é padrão do conjunto (versão), o que vem de massa de dados (inputs), e o que é gerado pelo sistema (IDs). O resultado é uma Collection mais reutilizável, previsível e fácil de automatizar.
