Certaines requêtes nécessitent un travail avant de quitter votre machine, et d'autres en exigent dès qu'une réponse arrive. Une API de paiement demande une signature HMAC calculée à partir d'un horodatage et de votre secret. Un point d'accès de connexion renvoie un jeton que chaque appel ultérieur nécessite. Un flux de paiement doit vérifier que la réponse a bien renvoyé un 200 et le bon ID de commande. Vous pouvez faire tout cela manuellement, mais cela devient vite fastidieux et cela se casse dès que vous partagez la requête avec un coéquipier.
Les scripts corrigent cela. Dans Apidog, vous attachez de petits morceaux de JavaScript à une requête qui s'exécutent automatiquement : un ensemble avant l'envoi de la requête, un autre après que la réponse est reçue. Si vous avez déjà écrit des scripts Postman, la mémoire musculaire se transfère, car le moteur d'Apidog est compatible avec la même API d'objet pm. Ce guide présente les deux étapes avec un exemple réaliste : signer une requête dans un script de pré-requête, puis extraire un jeton dans un script de post-réponse. Le comportement est entièrement documenté dans la documentation de script Apidog, mais les noms d'onglets et quelques comportements diffèrent de Postman, et ces différences sont importantes.
bouton
Ce que les scripts de pré et post-traitement font réellement
Apidog exécute les scripts en deux étapes, et les nomme clairement.
Les pré-processeurs s'exécutent avant l'envoi de la requête au serveur. C'est là que vous préparez les choses : générer un horodatage, calculer une signature, définir un ID de commande aléatoire, ou lire une variable et la transformer en en-tête. La réponse n'existe pas encore à ce stade, donc tout ce qui inspecte une réponse est interdit ici.
Les post-processeurs s'exécutent après la réception de la réponse. C'est là que vous vérifiez ce qui est revenu avec des assertions, et où vous extrayez des valeurs du corps pour les réutiliser plus tard. Extraire un jeton d'authentification, récupérer un ID de ressource nouvellement créé, vérifier le code d'état, enregistrer un curseur pour la pagination.
Deux règles découlent de cette séparation. Premièrement, pm.response (avec son code, status, headers, responseTime, responseSize, text() et json()) ne fonctionne que dans les post-processeurs. Il n'y a pas de réponse à lire avant d'envoyer, donc l'appeler dans un pré-processeur ne vous aidera pas. Deuxièmement, les variables sont la façon dont les deux étapes communiquent entre elles. Un pré-processeur définit une valeur, la requête l'utilise, et un post-processeur peut la lire ou la modifier.
Si vous venez de Postman, notez d'emblée le changement d'étiquette. Les onglets d'Apidog sont Pré-processeurs et Post-processeurs, et non « Script de pré-requête » et « Tests ». Le comportement est très similaire, mais les noms à l'écran sont différents.
Configuration : ouvrez une requête et trouvez les onglets
Téléchargez Apidog pour suivre. C'est gratuit et ça fonctionne sur macOS, Windows et Linux, alors téléchargez-le depuis la page Télécharger Apidog si vous ne l'avez pas encore.
Ouvrez la requête API que vous souhaitez scripter dans Apidog. Chaque point d'accès dispose d'un onglet Pré-processeurs et d'un onglet Post-processeurs à côté des onglets habituels Params, Headers et Body. Pour ajouter de la logique à l'une ou l'autre étape, ouvrez l'onglet et sélectionnez ajouter un script personnalisé. Cela ouvre un éditeur de code où vous écrivez du JavaScript simple contre l'objet pm.
Avant d'écrire quoi que ce soit, il est utile de savoir où vivent les valeurs. Apidog résout les variables dans cet ordre de priorité :
Variables locales > Variables d'environnement > Variables globales partagées au sein du projet > Variables globales partagées au sein de l'équipe.
Ainsi, une variable locale l'emporte sur une variable d'environnement du même nom, et ainsi de suite dans la liste. Gardez cela à l'esprit lorsqu'une valeur n'est pas celle que vous attendez : quelque chose de plus haut dans l'ordre la masque probablement. Si vous souhaitez des valeurs qui persistent sur plusieurs requêtes, les paramètres globaux dans Apidog sont plus bas dans l'ordre de priorité et constituent un bon emplacement pour des paramètres stables à l'échelle du projet.
Exemple de pré-processeur : signer une requête avec HMAC
Supposons que vous appeliez un point d'accès de paiement qui authentifie chaque requête avec une signature HMAC-SHA256. C'est le même modèle que de nombreux fournisseurs utilisent pour la vérification des webhooks, et la documentation de signature de Stripe le décrit bien : le serveur attend un horodatage et une signature calculée sur cet horodatage plus le corps de la requête, avec votre secret d'API comme clé. Vous devez construire les deux à chaque envoi.
Apidog inclut crypto-js comme bibliothèque intégrée, vous n'avez donc rien à installer. Ouvrez l'onglet Pré-processeurs, sélectionnez ajouter un script personnalisé, et écrivez ceci :
// Pre Processor: sign the request before it is sent
const CryptoJS = require('crypto-js');
// current unix timestamp in seconds
const timestamp = Math.floor(Date.now() / 1000).toString();
// read the secret from an environment variable
const secret = pm.environment.get('payments_api_secret');
// build the string to sign: timestamp + newline + raw body
const body = pm.request.body ? pm.request.body.toString() : '';
const payload = timestamp + '\n' + body;
// compute the HMAC-SHA256 signature, hex encoded
const signature = CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
// stash both values as environment variables for the request to use
pm.environment.set('x_timestamp', timestamp);
pm.environment.set('x_signature', signature);
pm.console.log('Signed request at ' + timestamp);
Ce script calcule la signature et enregistre l'horodatage et la signature dans des variables d'environnement. Connectez-les maintenant à la requête. Dans l'onglet En-têtes, référencez les valeurs stockées avec la syntaxe {{variableName}} :
X-Timestamp: {{x_timestamp}}
X-Signature: {{x_signature}}
Lorsque vous envoyez, Apidog exécute d'abord le pré-processeur, définit les deux variables, puis les substitue dans les en-têtes. Le serveur reçoit une signature valide au moment de l'envoi, à chaque fois, sans aucune étape manuelle. Notez que l'appel require('crypto-js') charge le module entier. Vous importez la bibliothèque entière, pas un sous-module, donc require('crypto-js') fonctionne et require('crypto-js/sha256') non.
Une chose à surveiller : les opérations sur les variables ne touchent que les valeurs actuelles, pas les valeurs initiales que vous auriez pu saisir dans l'éditeur d'environnement. C'est ce que vous voulez ici, car la signature est censée être éphémère. Si vous avez besoin d'explications sur les modèles de signature pour Postman également, le guide sur les scripts de pré-requête Postman couvre la même idée avec les étiquettes de Postman, et cela correspond parfaitement aux pré-processeurs d'Apidog.
Exemple de post-processeur : extraire un jeton et affirmer
Passons maintenant à l'autre étape. Imaginez une requête de connexion qui renvoie un jeton dont vous avez besoin pour chaque appel authentifié par la suite :
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": 4812, "email": "dana@example.com" },
"expires_in": 3600
}
Ouvrez l'onglet Post-processeurs, sélectionnez ajouter un script personnalisé, et extrayez le jeton du corps, en le sauvegardant pour les requêtes ultérieures :
// Post Processor: verify the response, then extract the token
pm.test('Status is 200', function () {
pm.response.to.have.status(200);
});
const jsonData = pm.response.json();
pm.test('Response returns a token', function () {
pm.expect(jsonData.token).to.be.a('string').and.not.empty;
});
pm.test('User id is present', function () {
pm.expect(jsonData.user.id).to.be.a('number');
});
// store the token so other requests can send it
pm.environment.set('auth_token', jsonData.token);
pm.console.log('Saved token for user ' + jsonData.user.email);
Deux choses se passent ici. Les blocs pm.test() affirment que la réponse est formatée comme vous l'attendez, en utilisant les correspondances pm.expect() de style Chai qu'Apidog prend en charge nativement. Et pm.environment.set('auth_token', jsonData.token) enregistre le jeton dans l'environnement. Toute requête ultérieure peut maintenant envoyer Authorization: Bearer {{auth_token}} sans que vous ayez à copier quoi que ce soit manuellement.
La partie d'assertion mérite une attention particulière. De bonnes vérifications après la réponse transforment un simple clic et examen visuel en un véritable test, et notre guide sur les assertions d'API dans Apidog approfondit les correspondances et les modèles à connaître. Si vous souhaitez également alimenter ces flux avec des données fictives réalistes, Faker.js dans Apidog se marie bien avec la définition de variables présentée ci-dessus.
Quelques comportements à bien comprendre dans les post-processeurs. pm.iterationData (vos données de test) est en lecture seule, vous pouvez donc lire une valeur pilotée par les données mais vous ne pouvez pas la réécrire à partir d'un script. Et pm.cookies renvoie le cookie de la réponse, celui que le serveur a renvoyé, et non le cookie qui a été envoyé avec votre requête.
Réutiliser la logique avec les scripts publics
Une fois que vous avez écrit ce bloc de signature HMAC, vous voudrez probablement l'utiliser sur plus d'une requête. Copier-coller dans dix points d'accès signifie dix endroits à corriger lorsque l'algorithme change. La réponse d'Apidog est les scripts publics : des extraits réutilisables que vous écrivez une fois et que vous attachez là où c'est nécessaire.
Créez-en un sous Paramètres > Scripts publics, puis ajoutez-le à l'onglet Pré-processeurs ou Post-processeurs d'une requête. Dans une liste de processeurs, un script public et un script personnalisé se trouvent côte à côte, et l'ordre est important : les scripts publics s'exécutent avant les scripts personnalisés dans la même liste, et si vous avez plusieurs scripts publics, ils s'exécutent de haut en bas dans l'ordre indiqué.
Il y a un piège qui déroute les gens. Si vous souhaitez qu'un script personnalisé appelle une fonction définie dans un script public, cette fonction doit être globale. Une déclaration de function normale ou une fonction liée à const est locale à son propre script et invisible pour le suivant. Déclarez-la en l'assignant sans var, let ou const :
// In the Public Script: make sign() global by omitting the keyword
sign = function (payload, secret) {
const CryptoJS = require('crypto-js');
return CryptoJS.HmacSHA256(payload, secret).toString(CryptoJS.enc.Hex);
};
// In the Custom Script below it: call the global function by name
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));
Ajoutez d'abord le script public, placez le script personnalisé en dessous, et l'appel se résout. Si l'ordre est incorrect ou si vous ajoutez un const, vous obtiendrez une erreur de fonction indéfinie.
Bibliothèques, paquets externes et débogage
L'importation de crypto-js ci-dessus est l'une des bibliothèques qu'Apidog regroupe sans configuration. Vous pouvez require() n'importe laquelle d'entre elles directement :
crypto-js(v3.1.9-1) pour le hachage et HMACjsrsasign(v10.3.0) pour le travail JWT et RSA, ce qui nécessite Apidog 1.4.5 ou une version ultérieurechai(v4.2.0) pour les correspondances d'assertionlodash,moment,uuid,xml2js,cheerio,postman-collection,atob,btoa,csv-parse/lib/sync,tv4,ajv- Les modules intégrés de Node comme
path,assert,buffer,util,url,querystring,stream, etevents
Si vous avez besoin de quelque chose qui ne figure pas sur cette liste, importez-le à l'exécution avec $$.liveRequire(), qui récupère le paquet à la volée :
$$.liveRequire('nanoid', (nanoid) => {
const id = nanoid.nanoid();
pm.environment.set('request_id', id);
});
Ce chemin nécessite une connexion Internet, car Apidog télécharge le paquet lorsque le script s'exécute. Les bibliothèques intégrées ne le nécessitent pas.
Lorsqu'un script se comporte mal, déboguez-le en consignant les informations. pm.console.log() et console.log() affichent tous deux dans la console d'Apidog, vous pouvez donc vider une signature calculée ou un champ extrait et voir exactement ce que le script a produit avant l'envoi de la requête ou après son retour.
Deux autres limites qu'il est bon de mentionner pour qu'elles ne vous surprennent pas. pm.sendRequest(), pour déclencher un appel HTTP supplémentaire à l'intérieur d'un script, utilise un modèle de rappel plutôt que des promesses, alors écrivez-le avec un rappel, pas await. Et pm.nextRequest() de Postman pour enchaîner les requêtes n'est pas pris en charge ici. Lorsque vous avez besoin d'une véritable orchestration de flux de travail, avec des étapes de branchement et conditionnelles, Apidog utilise des scénarios de test à la place, où vous séquencez visuellement les requêtes avec des étapes Condition et If-Else. Si vous écrivez beaucoup de scripts, le générateur de script Apidog intégré peut également en rédiger un à partir d'une description en langage naturel pour vous donner un point de départ.
Automatiser le flux de travail avec l'interface de ligne de commande Apidog
Les scripts ne s'exécutent pas seulement lorsque vous cliquez sur Envoyer. Lorsque vous regroupez vos requêtes et assertions dans un scénario de test enregistré, l'interface de ligne de commande d'Apidog exécute l'intégralité de ce scénario sans interface graphique, pré-processeurs et post-processeurs inclus, ce qui intègre votre logique de signature et d'extraction de jetons dans la CI au lieu d'une étape manuelle.
Installez l'interface de ligne de commande et authentifiez-vous, puis exécutez un scénario par ID :
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
L'indicateur -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r sélectionne le rapporteur (cli, html, ou junit, séparés par des virgules pour plusieurs). Générez le jeton d'accès dans les paramètres de votre compte Apidog, exportez-le en tant que APIDOG_ACCESS_TOKEN, et le même scénario qui s'est exécuté sur votre bureau s'exécute maintenant en CI, pré-processeurs et post-processeurs inclus.
Une mise en garde honnête : un script qui s'appuie sur quelque chose présent uniquement sur votre machine, un fichier local ou un paquet que vous avez chargé une fois, peut réussir dans l'application de bureau et ensuite échouer dans l'interface de ligne de commande, car l'exécuteur n'a pas cette dépendance. Limitez les scripts aux bibliothèques intégrées ou à $$.liveRequire() afin qu'ils s'exécutent de la même manière partout.
FAQ
Les scripts Apidog sont-ils compatibles avec mes scripts Postman existants ?
Oui, en grande partie. Le moteur d'Apidog utilise la même API d'objet pm, donc pm.environment.set(), pm.response.json(), pm.test() et pm.expect() se comportent tous comme vous le savez. Les deux différences à retenir sont les noms d'onglets, Pré-processeurs et Post-processeurs plutôt que Script de pré-requête et Tests, et quelques appels non pris en charge comme pm.nextRequest(). La plupart des scripts peuvent être copiés-collés et exécutés.
Pourquoi pm.response renvoie-t-il undefined dans mon script de pré-requête ?
Parce qu'il n'y a pas encore de réponse. Les pré-processeurs s'exécutent avant l'envoi de la requête, donc rien n'est encore revenu à inspecter. Tout code qui lit pm.response (son statut, son corps, ses en-têtes) doit se trouver dans un post-processeur. Si vous avez besoin d'une valeur à l'étape de pré-traitement, récupérez-la à partir de pm.request, d'une variable ou d'une bibliothèque à la place.
Comment partager un script sur plusieurs requêtes ?
Utilisez les scripts publics sous Paramètres > Scripts publics. Écrivez la logique une fois, attachez-la à l'onglet Pré-processeurs ou Post-processeurs de chaque requête, et rappelez-vous que les scripts publics s'exécutent avant les scripts personnalisés dans la même liste. Pour appeler une fonction de script public à partir d'un script personnalisé, déclarez-la globale en l'assignant sans var, let ou const.
Puis-je importer un paquet npm qu'Apidog n'inclut pas ?
Oui, avec $$.liveRequire('package-name', (pkg) => { ... }), qui télécharge le paquet à l'exécution et nécessite une connexion Internet. Pour tout élément de la liste intégrée, comme crypto-js, moment ou uuid, utilisez un simple require() sans nécessiter de réseau. Notez que vous ne pouvez exiger qu'un module entier, pas un chemin de sous-module.
Où puis-je voir ce que mon script a affiché ?
Utilisez pm.console.log() ou console.log() et lisez la sortie dans la console d'Apidog après avoir envoyé la requête. C'est le moyen le plus rapide de confirmer qu'une signature a été calculée ou qu'un jeton a été extrait avant de le valider dans un scénario.
Conclusion
Les pré-processeurs et les post-processeurs transforment une requête statique en une requête qui se prépare et vérifie son propre travail. Signez avant d'envoyer, extrayez et affirmez après réception, et intégrez la logique partagée dans des scripts publics pour ne l'écrire qu'une seule fois. L'API pm et les bibliothèques incluses signifient que la plupart de ce que vous connaissez de Postman est directement transférable. Ouvrez Apidog, choisissez n'importe quelle requête, et ajoutez votre premier script personnalisé pour voir les deux étapes s'exécuter en un seul envoi. C'est gratuit pour commencer, aucune carte de crédit requise.