Postman Runner : Variable non persistante - Causes et solutions

TL;DR

Les variables définies lors de l'exécution manuelle d'une requête disparaissent souvent lorsque vous exécutez la même collection dans le Collection Runner de Postman. La cause première est une incompatibilité de portée des variables : pm.environment.set se comporte différemment dans le runner qu'en mode manuel, et les variables de collection fonctionnent différemment des variables d'environnement. Ce guide explique précisément pourquoi cela se produit et comment y remédier, puis montre comment Apidog gère la portée des variables d'une manière qui rend la mauvaise configuration accidentelle plus difficile.

Introduction

Vous avez testé une API manuellement dans Postman. Vous exécutez une requête de connexion, le script de pré-requête définit un jeton d'authentification, et les requêtes suivantes le récupèrent sans problème. Tout fonctionne.

Puis vous cliquez sur « Exécuter la collection » (Run Collection). Le runner démarre, la requête de connexion réussit, mais la requête suivante échoue avec une erreur 401. Le jeton n'est pas présent.

Ce scénario apparaît régulièrement sur Stack Overflow et les forums de la communauté Postman. Les réponses indiquent généralement la portée des variables, mais elles expliquent rarement l'image complète des raisons pour lesquelles le comportement diffère entre les tests manuels et le runner.

Comprendre cela nécessite de comprendre la hiérarchie de la portée des variables de Postman. Une fois que c'est clair, la solution est simple.

Hiérarchie de la portée des variables de Postman

Postman dispose de cinq portées de variables, listées de la priorité la plus élevée à la plus basse :

1. Variables locales – disponibles uniquement dans l'exécution du script actuel, non accessibles entre les requêtes
2. Variables de données – chargées à partir d'un fichier CSV ou JSON pour les exécutions pilotées par les données
3. Variables de collection – dont la portée est la collection, persistent entre les requêtes de cette collection
4. Variables d'environnement – dont la portée est l'environnement sélectionné, persistent entre les collections
5. Variables globales – disponibles dans n'importe quelle collection, dans n'importe quel environnement

Lorsque Postman résout une référence de variable comme {{token}}, il parcourt cette liste et utilise la première correspondance qu'il trouve.

Le problème est que « persister » signifie différentes choses selon la manière dont vous exécutez la collection.

Pourquoi les variables disparaissent dans le Collection Runner

La distinction entre valeur actuelle et valeur initiale

Chaque variable Postman a deux champs : « valeur initiale » et « valeur actuelle ».

• La valeur initiale est synchronisée avec le cloud de Postman et partagée avec les membres de l'équipe.
• La valeur actuelle est locale à votre machine et n'est jamais synchronisée.

Lorsque vous définissez une variable par programme dans un script à l'aide de pm.environment.set('token', value), Postman met à jour la valeur actuelle dans votre environnement actif.

En mode de test manuel, cela fonctionne comme prévu car vos valeurs actuelles locales persistent entre les exécutions individuelles de requêtes au sein de la même session.

Dans le Collection Runner, le comportement change. Le runner démarre chaque exécution à partir de l'état actuel de l'environnement au début de l'exécution. Les scripts qui mettent à jour les variables pendant l'exécution fonctionnent correctement au sein de cette exécution. Mais si le runner est configuré pour effacer les variables entre les exécutions, ou si la valeur initiale est vide et que le runner utilise un instantané d'environnement frais, vous pouvez vous retrouver dans un état où votre script s'exécute mais la variable ne semble pas persister.

Le problème des variables d'environnement vs. variables de collection

Voici le piège le plus courant. Vous définissez une variable dans un script post-réponse :

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

Cela définit une variable dans l'environnement actif. Mais le Collection Runner a une option appelée « Conserver les valeurs des variables » (Keep variable values). Si cette case est décochée (elle est décochée par défaut), le runner réinitialise les variables d'environnement à leurs valeurs initiales après l'exécution. Toute valeur définie pendant l'exécution est supprimée.

Si vous exécutez la collection sans environnement sélectionné, pm.environment.set échoue silencieusement. Il n'y a pas d'environnement dans lequel écrire. La variable disparaît.

L'incompatibilité de portée entre le mode manuel et le mode runner

En mode de test manuel, vous avez généralement un environnement sélectionné qui persiste tout au long de votre session Postman. Lorsque vous exécutez une requête, définissez une variable et exécutez une autre requête, tout cela se produit dans le même contexte d'environnement persistant.

Le Collection Runner crée un contexte d'exécution distinct. Il charge l'état de l'environnement au début, exécute toutes les requêtes, puis (à moins que vous ne cochiez « Conserver les valeurs des variables ») restaure l'environnement à son état d'avant l'exécution.

Cela signifie que les variables définies par une requête dans le runner sont disponibles pour les requêtes ultérieures de la même exécution, mais elles ne persistent pas dans votre panneau d'environnement après la fin de l'exécution, à moins que vous ne les conserviez explicitement.

Solutions

Solution 1 : Cochez « Conserver les valeurs des variables » dans le runner

Dans le Collection Runner, avant de cliquer sur Exécuter :

1. Recherchez l'option « Conserver les valeurs des variables » (Keep variable values) dans le panneau de configuration du runner.
2. Cochez cette case.

Cela indique au runner d'écrire les modifications de variables dans votre environnement actif une fois l'exécution terminée. Les variables définies par les scripts pendant l'exécution seront visibles dans votre panneau d'environnement lorsque l'exécution sera terminée.

Quand l'utiliser : Lorsque vous souhaitez que le runner mette à jour un état partagé, comme la mise à jour d'un jeton d'authentification que d'autres outils ou des exécutions ultérieures utiliseront.

Quand ne pas l'utiliser : Lorsque vous exécutez plusieurs itérations et que les variables définies dans l'itération 1 pollueraient l'itération 2. Dans ce cas, utilisez des fichiers de données ou réinitialisez explicitement les variables au début de chaque itération.

Solution 2 : Utilisez des variables de collection au lieu de variables d'environnement pour l'état intra-exécution

Si une variable n'a besoin d'être partagée qu'entre les requêtes au sein de la même exécution de collection, utilisez des variables de collection au lieu de variables d'environnement :

// Dans le script post-réponse de votre requête de connexion :
pm.collectionVariables.set('token', pm.response.json().access_token);

// Dans le script de pré-requête des requêtes suivantes :
const token = pm.collectionVariables.get('token');

Les variables de collection sont toujours disponibles dans le runner, qu'un environnement soit sélectionné ou non. Elles persistent pendant toute la durée de l'exécution de la collection. Elles constituent la portée appropriée pour les valeurs qui sont définies et consommées au sein d'une seule collection.

Solution 3 : Assurez-vous qu'un environnement est sélectionné avant l'exécution

pm.environment.set échoue silencieusement lorsqu'aucun environnement n'est actif. Avant d'exécuter la collection :

1. Ouvrez le Collection Runner.
2. Vérifiez qu'un environnement est sélectionné dans la liste déroulante « Environnement ».
3. Si vous n'avez pas besoin de variables au niveau de l'environnement, utilisez plutôt des variables de collection (Solution 2).

Solution 4 : Utilisez des valeurs initiales pour les variables qui devraient toujours exister

Si une variable comme baseUrl doit être disponible dès la première requête d'une exécution, définissez-la comme valeur initiale dans votre environnement, et pas seulement comme valeur actuelle.

Dans l'éditeur d'environnement :

• Définissez le champ « Valeur initiale », pas seulement le champ « Valeur actuelle ».
• La valeur initiale est ce que le runner utilise comme état de départ.

Si seule la valeur actuelle est définie et que le runner n'a pas accès à vos valeurs actuelles locales (par exemple, un coéquipier exécutant la collection, ou une exécution CLI Newman/Apidog), la variable démarre vide.

Solution 5 : Déboguer avec la journalisation de la console

Ajoutez console.log à vos scripts de pré-requête et post-réponse pour voir exactement ce qui se passe :

// Script de pré-requête
console.log('token before request:', pm.collectionVariables.get('token'));
console.log('environment token:', pm.environment.get('token'));

Ouvrez la console Postman (Affichage > Afficher la console Postman) avant d'exécuter la collection. Les journaux vous montreront exactement de quelle portée chaque variable est lue et quelle valeur elle contient à chaque étape.

Comment Apidog gère la portée des variables

Apidog utilise la même hiérarchie de portée : globale, environnement, collection et locale. La différence clé réside dans l'interface utilisateur.

Dans l'éditeur de variables d'Apidog, les valeurs initiales et actuelles sont affichées avec des étiquettes et des couleurs explicites. L'interface rend plus difficile de ne définir accidentellement que la valeur actuelle. Lorsqu'un script définit une variable à l'aide de pm.environment.set (ce qu'Apidog prend en charge pour la compatibilité Postman), le panneau d'environnement se met à jour visuellement en temps réel afin que vous puissiez voir le changement se produire.

Le runner de tests d'Apidog ne réinitialise pas non plus les valeurs des variables entre les étapes, sauf si vous le configurez explicitement pour le faire. Le comportement par défaut est de préserver l'état des variables entre les requêtes d'une exécution, ce qui correspond à ce que la plupart des développeurs attendent des tests manuels.

Pour les scénarios d'équipe, le modèle local-first d'Apidog signifie que les variables d'environnement sont stockées sur disque. Il n'y a pas de synchronisation cloud qui écrase vos valeurs actuelles entre les exécutions.

Résumé des erreurs courantes

FAQ

Pourquoi pm.environment.set fonctionne-t-il en mode manuel mais pas dans le runner ?En mode manuel, vous avez une session d'environnement persistante. Dans le runner, l'environnement est chargé au début de l'exécution et réinitialisé par défaut à la fin. Les scripts qui définissent des variables pendant l'exécution fonctionnent toujours pour les requêtes ultérieures de cette exécution, mais les modifications ne persistent pas dans votre environnement à moins que l'option « Conserver les valeurs des variables » ne soit cochée.

Quelle est la différence entre pm.environment.set et pm.collectionVariables.set ?pm.environment.set écrit dans l'environnement actif, qui est partagé entre toutes les collections utilisant cet environnement. pm.collectionVariables.set écrit dans une portée liée à la collection spécifique. Pour les valeurs qui n'importent que dans une seule exécution de collection, les variables de collection sont plus appropriées et ne nécessitent pas la sélection d'un environnement.

Ce problème se produit-il dans Newman ?Oui. Newman a le même modèle de portée. Par défaut, Newman démarre chaque exécution avec les valeurs initiales de l'environnement exporté et ne persiste pas les modifications après l'exécution, à moins que vous n'utilisiez l'option --export-environment pour écrire l'état final de l'environnement dans un fichier.

Qu'est-ce que l'option --export-environment dans Newman ?Elle indique à Newman d'écrire l'état final de l'environnement, y compris toutes les valeurs définies par les scripts pendant l'exécution, dans un fichier JSON une fois l'exécution terminée. Vous pouvez ensuite passer ce fichier comme environnement pour la prochaine exécution. Ceci est utile pour les pipelines où une exécution génère des jetons utilisés par la suivante.

Apidog prend-il en charge pm.collectionVariables.set ?Oui. Apidog prend en charge l'API de scripting Postman complète, y compris pm.collectionVariables.set, pm.collectionVariables.get, pm.environment.set et pm.environment.get. Les collections migrées depuis Postman utilisent la même syntaxe de script.

Comment transmettre des variables d'une collection à une autre dans Postman ?Utilisez des variables globales : pm.globals.set('token', value). Les variables globales persistent entre les collections et les environnements pendant toute la durée de la session Postman. Soyez prudent avec cette approche dans les environnements d'équipe car les variables globales ne sont pas délimitées et peuvent créer des conflits de noms.

Les problèmes de portée des variables dans Postman sont l'une des sources les plus fiables de faux négatifs dans les suites de tests d'API. Un test qui réussit manuellement mais échoue dans le runner n'est pas un test auquel vous pouvez faire confiance. Comprendre le modèle de portée, utiliser le bon setter pour le bon contexte et cocher « Conserver les valeurs des variables » le cas échéant sont les trois actions qui résolvent la plupart de ces problèmes.