Comment utiliser les scripts de pré-requête et de post-réponse dans Apidog

Certaines requêtes API doivent être préparées avant leur envoi, tandis que d'autres nécessitent des vérifications dès la réception de la réponse. Par exemple : calculer une signature HMAC pour une API de paiement, extraire un jeton après une connexion, ou vérifier qu'une commande renvoie bien un statut 200 et le bon identifiant. Sans scripts, ces étapes deviennent manuelles, répétitives et fragiles dès que la requête est partagée.

Essayez Apidog dès aujourd’hui

Dans Apidog, vous pouvez associer des scripts JavaScript à chaque requête :

• les pré-processeurs s'exécutent avant l'envoi ;
• les post-processeurs s'exécutent après réception de la réponse.

Le moteur est compatible avec l'API pm connue de Postman. Vous pouvez donc réutiliser la plupart des patterns pm.environment, pm.response, pm.test() et pm.expect(). Consultez la documentation des scripts Apidog pour la référence complète.

Pré-processeurs et post-processeurs : quand utiliser chacun ?

Apidog sépare l'exécution des scripts en deux moments.

Pré-processeurs

Les pré-processeurs s'exécutent avant l'envoi de la requête. Utilisez-les pour préparer les données nécessaires à l'appel :

• générer un horodatage ;
• calculer une signature HMAC ;
• produire un ID de commande ;
• transformer une variable en en-tête HTTP ;
• définir des variables utilisées par la requête.

À cette étape, aucune réponse n'existe encore. N'utilisez donc pas pm.response dans un pré-processeur.

Post-processeurs

Les post-processeurs s'exécutent après réception de la réponse. Utilisez-les pour :

• vérifier le statut HTTP ;
• valider la structure du JSON ;
• extraire un jeton d'authentification ;
• enregistrer un ID de ressource ;
• conserver un curseur de pagination.

pm.response est disponible uniquement ici, avec notamment :

pm.response.code
pm.response.status
pm.response.headers
pm.response.responseTime
pm.response.responseSize
pm.response.text()
pm.response.json()

Les variables constituent le lien entre les deux étapes : un pré-processeur peut définir une valeur, la requête peut l'utiliser, puis un post-processeur peut la lire ou la remplacer.

Si vous venez de Postman, retenez surtout le changement d'interface : Apidog utilise les onglets Pré-processeurs et Post-processeurs, au lieu de « Script de pré-requête » et « Tests ».

Configuration : ajouter un script à une requête

Installez Apidog depuis la page Télécharger Apidog, puis ouvrez la requête à automatiser.

Chaque requête expose les onglets habituels — Params, Headers et Body — ainsi que :

• Pré-processeurs
• Post-processeurs

Dans l'onglet concerné, sélectionnez ajouter un script personnalisé, puis écrivez votre JavaScript avec l'objet pm.

Avant de commencer, gardez en tête l'ordre de priorité des variables :

Variables locales > Variables d'environnement > Variables globales partagées au sein du projet > Variables globales partagées au sein de l'équipe

Une variable locale masque donc une variable d'environnement portant le même nom. Si une valeur est inattendue, vérifiez si une variable plus prioritaire l'écrase.

Pour des paramètres stables au niveau du projet, utilisez les paramètres globaux dans Apidog.

Exemple : signer une requête avec HMAC dans un pré-processeur

Supposons une API de paiement qui attend :

1. un horodatage ;
2. une signature HMAC-SHA256 ;
3. une signature calculée à partir de l'horodatage, du corps de la requête et du secret API.

Ce modèle est courant pour la vérification de webhooks. La documentation de signature de Stripe illustre ce principe.

Dans l'onglet Pré-processeurs, ajoutez le script suivant :

// Pré-processeur : signer la requête avant son envoi
const CryptoJS = require('crypto-js');

// Horodatage Unix en secondes
const timestamp = Math.floor(Date.now() / 1000).toString();

// Secret stocké dans l'environnement
const secret = pm.environment.get('payments_api_secret');

// Chaîne à signer : horodatage + saut de ligne + corps brut
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;

// Signature HMAC-SHA256 encodée en hexadécimal
const signature = CryptoJS
  .HmacSHA256(payload, secret)
  .toString(CryptoJS.enc.Hex);

// Variables consommées par la requête
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);

pm.console.log('Requête signée à ' + timestamp);

Ajoutez ensuite ces en-têtes dans l'onglet Headers :

X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}

À chaque envoi, Apidog applique cette séquence :

1. exécution du pré-processeur ;
2. calcul de l'horodatage et de la signature ;
3. stockage dans l'environnement ;
4. résolution de {{x_timestamp}} et {{x_signature}} dans les en-têtes ;
5. envoi de la requête.

crypto-js est inclus dans Apidog. Importez le module complet :

const CryptoJS = require('crypto-js');

N'utilisez pas un chemin de sous-module tel que :

// Non pris en charge
require('crypto-js/sha256');

Les modifications de variables concernent les valeurs actuelles, pas les valeurs initiales définies dans l'éditeur d'environnement. C'est adapté aux signatures, qui doivent être recalculées à chaque requête.

Pour comparer avec les conventions Postman, consultez ce guide sur les scripts de pré-requête Postman.

Exemple : extraire un jeton dans un post-processeur

Imaginons qu'une requête de connexion retourne la réponse suivante :

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": 4812, "email": "[e-mail]" },
  "expires_in": 3600
}

Dans l'onglet Post-processeurs, ajoutez ce script :

// Post-processeur : vérifier la réponse puis extraire le jeton
pm.test('Le statut est 200', function () {
  pm.response.to.have.status(200);
});

const jsonData = pm.response.json();

pm.test('La réponse contient un jeton', function () {
  pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});

pm.test('L’identifiant utilisateur est présent', function () {
  pm.expect(jsonData.user.id).to.be.a('number');
});

// Stocker le jeton pour les requêtes suivantes
pm.environment.set('auth_token', jsonData.token);

pm.console.log('Jeton enregistré pour ' + jsonData.user.email);

Ce script fait deux choses :

1. il valide la réponse avec pm.test() et pm.expect() ;
2. il stocke le jeton dans auth_token.

Les requêtes authentifiées suivantes peuvent alors utiliser :

Authorization: Bearer {{auth_token}}

Vous évitez ainsi de copier-coller le jeton après chaque connexion.

Pour aller plus loin sur les tests, consultez le guide des assertions d'API dans Apidog. Pour générer des données de test, vous pouvez aussi combiner cette approche avec Faker.js dans Apidog.

Limites à connaître dans les post-processeurs

• pm.iterationData est accessible en lecture seule.
• pm.cookies représente les cookies renvoyés par le serveur, pas ceux envoyés dans la requête.

Réutiliser la logique avec les scripts publics

Copier le même script HMAC dans dix requêtes pose un problème de maintenance : si l'algorithme change, vous devez modifier dix emplacements.

Utilisez plutôt les scripts publics.

1. Ouvrez Paramètres > Scripts publics.
2. Créez le script partagé.
3. Attachez-le aux Pré-processeurs ou aux Post-processeurs des requêtes concernées.

L'ordre d'exécution est important :

• les scripts publics s'exécutent avant les scripts personnalisés ;
• plusieurs scripts publics s'exécutent de haut en bas.

Si un script personnalisé doit appeler une fonction définie dans un script public, cette fonction doit être globale.

Dans le script public :

// La fonction est globale car elle n'utilise ni var, ni let, ni const
sign = function (payload, secret) {
  const CryptoJS = require('crypto-js');

  return CryptoJS
    .HmacSHA256(payload, secret)
    .toString(CryptoJS.enc.Hex);
};

Dans le script personnalisé placé après :

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));

Si vous utilisez const sign = ... ou placez les scripts dans le mauvais ordre, la fonction ne sera pas disponible et le script renverra une erreur de fonction indéfinie.

Bibliothèques disponibles et paquets externes

Apidog fournit plusieurs bibliothèques utilisables directement avec require() :

• crypto-js (v3.1.9-1) pour le hachage et HMAC ;
• jsrsasign (v10.3.0) pour JWT et RSA — nécessite Apidog 1.4.5 ou version ultérieure ;
• chai (v4.2.0) pour les assertions ;
• lodash, moment, uuid, xml2js, cheerio, postman-collection, atob, btoa, csv-parse/lib/sync, tv4, ajv ;
• les modules Node path, assert, buffer, util, url, querystring, stream et events.

Pour un paquet non inclus, utilisez $$.liveRequire() :

$$.liveRequire('nanoid', (nanoid) => {
  const id = nanoid.nanoid();

  pm.environment.set('request_id', id);
});

Cette méthode télécharge le paquet à l'exécution et nécessite une connexion Internet. Les bibliothèques intégrées n'en nécessitent pas.

Déboguer vos scripts

Ajoutez des logs pour inspecter les données calculées ou extraites :

pm.console.log('Signature : ' + signature);
console.log('Jeton : ' + jsonData.token);

pm.console.log() et console.log() affichent tous deux les sorties dans la console Apidog.

Gardez également ces limites en tête :

• pm.sendRequest() utilise un modèle à rappel, pas await ;
• pm.nextRequest() de Postman n'est pas pris en charge.

Pour orchestrer un flux avec des conditions ou des branches, utilisez plutôt les scénarios de test Apidog, qui permettent d'enchaîner visuellement les requêtes avec des étapes Condition et If-Else.

Exécuter les scripts en CI avec Apidog CLI

Les pré-processeurs et post-processeurs ne s'exécutent pas uniquement depuis l'interface graphique. Ils sont aussi exécutés lorsqu'un scénario de test est lancé via l'interface de ligne de commande Apidog.

Installez la CLI, authentifiez-vous, puis lancez un scénario :

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

Paramètres principaux :

• -t : ID du scénario de test ;
• -e : ID de l'environnement ;
• -r : rapporteur, par exemple cli, html ou junit.

Vous pouvez combiner plusieurs rapporteurs en les séparant par des virgules.

Générez votre jeton d'accès dans les paramètres de compte Apidog, puis exposez-le dans votre CI sous la variable APIDOG_ACCESS_TOKEN.

Évitez les scripts dépendant d'un fichier local ou d'un paquet présent uniquement sur votre machine. Pour un comportement identique dans l'application et en CI, utilisez les bibliothèques intégrées ou $$.liveRequire().

FAQ

Les scripts Apidog sont-ils compatibles avec Postman ?

Oui, dans la plupart des cas. Apidog prend en charge la même API pm, notamment :

pm.environment.set()
pm.response.json()
pm.test()
pm.expect()

Les différences principales concernent les noms d'onglets et les appels non pris en charge, comme pm.nextRequest().

Pourquoi pm.response est-il undefined dans mon pré-processeur ?

Parce que la requête n'a pas encore été envoyée. Un pré-processeur s'exécute avant la réponse, donc pm.response n'est disponible que dans un post-processeur.

Pour lire les données de la requête avant son envoi, utilisez pm.request, les variables ou une bibliothèque. Voir aussi : récupérer les paramètres de requête dans les scripts pré et post-requête.

Comment partager un script entre plusieurs requêtes ?

Créez un script dans Paramètres > Scripts publics, puis attachez-le aux requêtes nécessaires. Les scripts publics s'exécutent avant les scripts personnalisés.

Pour appeler une fonction du script public dans un script personnalisé, déclarez-la sans var, let ni const.

Puis-je importer un paquet npm non inclus ?

Oui :

$$.liveRequire('package-name', (pkg) => {
  // Utiliser pkg ici
});

Cette méthode nécessite Internet. Pour les bibliothèques incluses, utilisez simplement require().

Où voir les logs de script ?

Utilisez :

pm.console.log('Message');
console.log('Message');

Puis ouvrez la console Apidog après l'exécution de la requête.

Conclusion

Les pré-processeurs et post-processeurs transforment une requête statique en un test API autonome :

• préparez et signez la requête avant l'envoi ;
• validez la réponse après réception ;
• extrayez les jetons et IDs automatiquement ;
• centralisez la logique commune dans des scripts publics ;
• exécutez les scénarios en CI avec Apidog CLI.

Ouvrez Apidog, choisissez une requête et ajoutez un premier script personnalisé pour automatiser votre flux API.