Le Smart mock vous procure une fausse API en quelques secondes. Il lit le schéma de votre endpoint et renvoie des données plausibles : un e-mail réaliste, un horodatage sensé, un nom qui n'est pas xJ8kQ. Pour la plupart des travaux frontend, c'est suffisant pour vous débloquer.
Puis vous rencontrez un cas que le Smart mock ne peut pas gérer. Vous voulez que /login renvoie 200 pour un utilisateur connu et 401 sinon. Vous voulez que /orders/{id} renvoie une commande expédiée pour un ID et une commande annulée pour un autre. Vous voulez forcer un 500 à la demande afin que votre gestion des erreurs soit exercée avant qu'elle n'atteigne la production. Le Smart mock renvoie une seule forme par endpoint, il ne peut donc pas se ramifier en fonction de la requête. C'est cette lacune que ce guide comble.
Apidog y remédie avec deux fonctionnalités : les attentes de mock pour des réponses conditionnelles basées sur des règles, et les scripts de mock pour une logique que les règles ne peuvent pas exprimer. Cette explication détaillée montre les deux avec des exemples concrets, et elle explique l'ordre de priorité afin que vos règles personnalisées l'emportent sur le Smart mock à chaque fois. Si vous débutez avec les bases, l'aperçu du mocking d'API est un bon échauffement, et Apidog est l'outil que nous utiliserons tout au long de ce guide. L'OpenAPI Initiative documente le flux de travail "contract-first" qui rend tout cela possible.
Ce que signifie réellement le mocking conditionnel
Un mock conditionnel est une règle : lorsque la requête entrante ressemble à ceci, renvoie cela. Apidog construit ces règles à partir de deux couches.
La première couche est la personnalisation au niveau des champs à l'intérieur du schéma de l'endpoint. Vous épinglez un champ à une valeur fixe, ou vous y attachez une expression dynamique Faker.js afin qu'il varie à chaque appel. Cela contrôle ce qu'un champ contient, mais cela renvoie toujours une seule forme de réponse pour l'endpoint.
La deuxième couche est l'attente de mock de réponse complète. Une attente est une règle nommée avec des conditions facultatives et son propre corps de réponse, son code de statut et ses en-têtes. Une attente sans condition renvoie des données fixes sans condition. Une attente avec des conditions ne renvoie ses données que lorsque la requête correspond. Empilez-en quelques-unes et vous obtenez un véritable branchement : réponse B lorsque la requête correspond à la condition A, un corps d'erreur lorsqu'un en-tête est manquant, une charge utile différente par paramètre de chemin.
Cette deuxième couche rend possibles les états d'erreur à la demande et les corps de réponse par requête. Le reste de ce guide s'y attardera.
Valeurs dynamiques au niveau des champs d'abord
Avant le branchement, il est utile de voir comment un champ unique obtient sa valeur, car vos réponses conditionnelles réutiliseront la même syntaxe.
À l'intérieur du schéma d'un endpoint, tout champ de type chaîne de caractères peut contenir une expression Faker.js écrite comme {{$category.method}}. Apidog la résout à chaque appel de mock, en utilisant les types de champs que votre définition JSON Schema a déjà déclarés.
{
"id": "{{$number.int(min=1000,max=9999)}}",
"customer": "{{$person.fullName}}",
"email": "{{$internet.email}}",
"product": "{{$commerce.productName}}",
"shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
"orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}
Les méthodes paramétrées fonctionnent, donc {{$number.int(min=1000,max=9999)}} borne la valeur et {{$date.between(...)}} fixe une plage et un format. Vous pouvez concaténer du texte statique et plusieurs expressions dans un seul champ, c'est ainsi que l'adresse ci-dessus est construite. Si vous avez besoin de données spécifiques à une région, Apidog prend en charge des locales de mock personnalisables afin que vos noms, adresses et numéros de téléphone correspondent à une langue ou un pays donné. La référence Faker.js dans Apidog couvre le catalogue complet des méthodes.
C'est le domaine du Smart mock. C'est dynamique, mais ce n'est pas conditionnel. Pour se brancher sur la requête, vous passez aux attentes.
Exemple : un endpoint de connexion qui renvoie 200 ou 401
Le cas canonique : POST /login prend un corps JSON avec username et password. Un utilisateur connu devrait obtenir 200 avec un jeton. Tous les autres devraient obtenir 401.
Ouvrez le bon onglet
L'endroit où vous configurez cela dépend de votre mode de travail :
- En mode DEBUG (Requête-d'abord), ouvrez l'endpoint et cliquez sur l'onglet Mock.
- En mode DESIGN (Conception-d'abord), ouvrez l'endpoint et cliquez sur l'onglet Mock avancé.
Les deux mènent à la même liste d'attentes. Si vous souhaitez suivre et que vous n'avez pas encore l'application, Téléchargez Apidog et importez ou créez d'abord un endpoint /login.
Ajoutez l'attente de succès
Cliquez sur Nouvelle attente. Donnez-lui un nom d'attente comme login-success. Ajoutez maintenant une condition. Comme username se trouve dans le corps de la requête JSON, vous le faites correspondre en tant que paramètre de corps : mettez le chemin JSON de la propriété cible, username, dans le champ nom, et définissez la condition pour qu'elle soit égale à alice@example.com.
Les conditions de paramètre de corps sont uniquement JSON, et elles sont mises en correspondance via le chemin JSON dans le champ nom, de sorte que les propriétés imbriquées utilisent des chemins de points comme user.email. Remplissez les Données de réponse avec la charge utile de succès :
{
"token": "mock-jwt-{{$string.uuid}}",
"user": {
"id": 4821,
"username": "alice@example.com",
"role": "member"
}
}
Enregistrez. Le Code de statut HTTP par défaut est 200, vous n'avez donc rien d'autre à toucher pour le scénario heureux.
Ajoutez l'attente d'échec
Cliquez à nouveau sur Nouvelle attente. Nommez-la login-failure et laissez ses conditions vides afin qu'elle agisse comme la règle de rattrapage. Définissez ses Données de réponse sur le corps d'erreur :
{
"error": "invalid_credentials",
"message": "Username or password is incorrect."
}
Celle-ci a besoin d'un statut non par défaut. Ouvrez l'onglet Plus de l'attente et définissez le Code de statut HTTP sur 401. Pendant que vous y êtes, notez que l'onglet Plus est également l'endroit où vous définissez le Délai de réponse en millisecondes (0 par défaut) et tous les en-têtes de réponse personnalisés. Un délai de 400 ms est un moyen simple de s'assurer que votre indicateur de chargement s'affiche réellement.
L'ordre compte
Les attentes sont évaluées de haut en bas, et la première correspondance l'emporte. Donc login-success doit se situer au-dessus de login-failure. Une requête avec username égal à alice@example.com correspond à la première règle et renvoie le jeton. Tout le reste tombe sur la règle d'échec inconditionnelle et obtient le 401. Si vous inversiez l'ordre, la règle sans condition correspondrait à tout et votre cas de succès ne se déclencherait jamais.
Copiez l'URL de mock de l'endpoint et testez les deux chemins :
# utilisateur connu -> 200 avec un jeton
curl -X POST https://<votre-hôte-mock>/login \
-H "Content-Type: application/json" \
-d '{"username":"alice@example.com","password":"whatever"}'
# tout autre -> 401
curl -X POST https://<votre-hôte-mock>/login \
-H "Content-Type: application/json" \
-d '{"username":"stranger@example.com","password":"whatever"}'
Exemple : différents corps pour /orders/{id} par statut
Le deuxième cas courant se branche sur un paramètre de chemin. Vous voulez que /orders/{id} renvoie une commande expédiée pour un ID et une commande annulée pour un autre, afin que votre UI puisse afficher chaque état sans avoir de backend réel.
Créez une attente par état. Pour chacune, ajoutez une condition sur le paramètre de chemin id, puis remplissez les Données de réponse correspondantes.
Attente order-shipped, condition : paramètre de chemin id est égal à 5001.
{
"id": 5001,
"status": "shipped",
"total": 129.90,
"trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
"shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}
Attente order-cancelled, condition : paramètre de chemin id est égal à 5002.
{
"id": 5002,
"status": "cancelled",
"total": 0,
"cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
"refundIssued": true
}
Ajoutez une dernière attente sans conditions qui renvoie une commande générique en attente, de sorte que tout autre ID reçoive toujours une réponse valide au lieu de passer au travers. Ordonnez les règles spécifiques au-dessus de la règle de rattrapage, enregistrez, et vous avez un mock qui rend chaque état de commande à la demande. Le mélange de conditions fonctionne également : ajoutez une condition d'en-tête à côté de la condition de chemin et les deux doivent être vraies, car Apidog combine plusieurs conditions avec la logique ET (une intersection des conditions, selon la terminologie des documents).
Les conditions ne se limitent pas au corps et au chemin. Vous pouvez faire correspondre les paramètres de requête, les paramètres d'en-tête, les paramètres de cookie, et même les adresses IP, ce qui vous permet de restreindre une réponse à des clients spécifiques pendant un test.
Forcer les états d'erreur à la demande
Vous n'avez pas besoin d'un backend cassé pour tester les réponses erronées. Une attente plus l'onglet Plus vous donne n'importe quel statut que vous souhaitez.
Pour forcer un 500, ajoutez une attente dont la condition est quelque chose que vous contrôlez depuis le client, par exemple un en-tête X-Mock-Scenario égal à server-error. Définissez ses Données de réponse sur un corps d'erreur réaliste et son Code de statut HTTP sur 500 dans l'onglet Plus.
{
"error": "internal_error",
"requestId": "{{$string.uuid}}",
"message": "Something went wrong on our end. Please retry."
}
Maintenant, le même endpoint sert un 200 normal par défaut et un 500 chaque fois que vous envoyez cet en-tête. Faites de même pour 404, 429 (avec un en-tête Retry-After défini dans l'onglet Plus), ou 503. Votre gestion des erreurs frontend a enfin quelque chose à intercepter. Si vous effectuez des assertions sur ces réponses dans des vérifications automatisées, le guide sur les assertions d'API se marie bien avec cette configuration.
Un détail pour les projets partagés : chaque attente peut être activée ou désactivée indépendamment pour les environnements de mock locaux et cloud à partir de la liste des attentes. Ainsi, vous pouvez garder une règle 500 active localement tout en la désactivant dans le mock cloud que vos coéquipiers utilisent.
Quand les règles ne suffisent pas : les scripts de mock
Les attentes sont déclaratives. Elles correspondent et renvoient, mais elles ne peuvent pas calculer. Lorsque vous avez besoin d'un champ dérivé de la requête, d'un total calculé à partir d'articles de ligne, ou d'un corps qui change de forme en fonction de plusieurs entrées à la fois, vous vous tournez vers un script de mock.
Un script de mock est du JavaScript qui s'exécute sur la réponse de mock. Il se trouve dans la section Script de mock en bas de l'onglet Mock et est activé par un interrupteur. Le script expose deux variables globales :
$$.mockRequest: lit la requête entrante viagetParam(key), plusheaders,cookies,body,formdataeturlencoded.$$.mockResponse: façonne la réponse sortante viasetBody(),setCode(),setDelay(),json(), et les propriétésheadersetcode.
Voici un script qui calcule le total d'une commande à partir des articles de ligne publiés et renvoie l'en-tête de devise de l'appelant :
const body = $$.mockRequest.body;
const items = body.items || [];
const subtotal = items.reduce((sum, item) => {
return sum + item.price * item.quantity;
}, 0);
const currency = $$.mockRequest.headers["x-currency"] || "USD";
$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
orderId: Math.floor(Math.random() * 90000) + 10000,
currency: currency,
subtotal: subtotal,
tax: Number((subtotal * 0.08).toFixed(2)),
total: Number((subtotal * 1.08).toFixed(2))
});
Le flux est le suivant : le Smart mock génère une réponse initiale, votre script lit $$.mockRequest et le $$.mockResponse actuel, applique sa logique, appelle $$.mockResponse.setBody() (et setCode, setDelay, ou headers si nécessaire), et le moteur renvoie le résultat final. La référence JavaScript MDN est un excellent compagnon si vous souhaitez pousser la logique plus loin avec des méthodes de tableau ou des calculs de date.
La seule règle qui pose problème
Les scripts de mock ne fonctionnent qu'avec le Smart mock. Ils ne s'appliquent pas aux attentes de mock ou aux exemples de réponse. C'est la chose la plus importante à internaliser : vous ne pouvez pas combiner un script de mock avec une réponse basée sur une attente. Si une attente correspond à la requête, le script ne s'exécute jamais. Choisissez donc une approche par endpoint. Utilisez les attentes lorsque vous vous branchez sur des conditions fixes et renvoyez des corps prédéfinis. Utilisez un script de mock lorsque vous avez besoin d'une sortie calculée à partir de la base générée par Smart mock.
Comment l'ordre de priorité est résolu
Mettez tout cela ensemble et voici l'ordre qu'Apidog suit pour toute requête de mock :
- Il vérifie vos attentes, de haut en bas. La première attente dont toutes les conditions correspondent l'emporte, et sa réponse est renvoyée. C'est pourquoi les règles personnalisées l'emportent sur le Smart mock : une attente correspondante court-circuite tout ce qui se trouve en dessous.
- Si aucune attente ne correspond, Apidog revient à la Priorité de la méthode de mock que vous avez définie dans Paramètres du projet - Paramètres des fonctionnalités - Paramètres de mock. C'est le niveau où le Smart mock (et tout script de mock qui y est attaché) produit la réponse.
Le modèle mental est simple : les règles spécifiques d'abord, les données générées ensuite. Ordonnez vos attentes du plus spécifique au moins spécifique, gardez une règle de rattrapage sans condition en bas si vous voulez une correspondance garantie, et laissez le Smart mock gérer tout le reste. Pour une exploration plus approfondie de quand s'appuyer sur chaque couche, le guide sur les cas d'utilisation du mocking d'API associe les scénarios courants aux fonctionnalités.
Pièges à connaître avant de déployer
Quelques contraintes vous éviteront une session de débogage déroutante :
- Les conditions de paramètre ne prennent pas en charge les
{{variables}}. Les variables de projet et d'environnement Apidog ne sont pas disponibles dans les attentes de mock, donc mettez des valeurs littérales dans vos conditions. - Les conditions de paramètre de corps sont uniquement JSON, pas XML, et doivent être mises en correspondance via le chemin JSON dans le champ nom.
- Le format du corps de la requête dans une condition doit correspondre à la spécification de l'API. Un endpoint de type form-data doit être mocké avec un placement form-data, pas JSON.
- Dans les scripts de mock, il n'y a pas de fonction de journalisation, l'objet
pmest indisponible (c'est un environnement d'exécution différent des scripts de test), et les variables Apidog ne peuvent pas être utilisées. Gardez la logique du script autonome.
Aucune de ces fonctionnalités n'est soumise à un gating de plan dans la documentation. La seule distinction locale/cloud est fonctionnelle : l'activation/désactivation indépendante par environnement décrite précédemment, et non un paywall.
Automatisez le workflow avec l'interface CLI d'Apidog
Le mocking dans Apidog est une fonctionnalité d'interface graphique et de cloud. Le moteur de mock sert vos endpoints à partir des URL de mock locales et cloud, et il n'y a pas de commande CLI qui lance un serveur de mock en cours d'exécution. Ce que l'interface CLI d'Apidog ajoute, c'est le contrôle des ressources à partir desquelles ces mocks sont construits.
Les réponses de mock sont générées à partir du schéma de l'endpoint, de sorte que la précision de votre mock suit la précision de votre spécification. La CLI, et les agents de codage AI qui l'animent (Cursor, Claude Code, Trae, Codex), peuvent créer et mettre à jour les endpoints et les schémas dans votre projet. Modifiez le contrat dans le code, synchronisez-le, et la sortie du mock reste correcte sans que personne n'ait à rouvrir l'application.
Une fois que le mock a débloqué le travail frontend, les scénarios de test du même projet s'exécutent sans interface graphique en CI pour valider le backend réel par rapport au contrat décrit par le mock :
apidog run -t <scenario_id> -e <env_id> -r cli
Cette seule commande exécute vos scénarios de test et rapporte les résultats, de sorte que le mock et la vérification partagent une source de vérité unique. Le guide d'installation de l'interface CLI d'Apidog couvre la configuration, et la présentation de l'interface CLI d'Apidog dans GitHub Actions l'intègre à un pipeline.
FAQ
Pourquoi mon attente est-elle ignorée même si la condition semble correcte ? Presque toujours un problème d'ordre ou d'incompatibilité de format. Les attentes sont évaluées de haut en bas et la première correspondance l'emporte, donc une règle générale sans condition placée au-dessus d'une règle spécifique interceptera la requête. Confirmez également que le format du corps correspond à la spécification (chemin JSON pour les corps JSON, placement form-data pour les endpoints de formulaire). L'aperçu du mocking d'API couvre les bases de la configuration si vous voulez revérifier.
Puis-je utiliser un script de mock et une attente de mock sur la même réponse ? Non. Les scripts de mock ne fonctionnent qu'avec le Smart mock. Ils sont ignorés par les attentes de mock et les exemples de réponse. Si une attente correspond, le script ne s'exécute jamais, choisissez donc une approche par endpoint : les attentes pour les branchements basés sur des règles, les scripts pour la sortie calculée.
Comment renvoyer un 401 ou 500 sans casser le 200 par défaut ? Ajoutez une attente dédiée avec une condition que vous contrôlez depuis le client (un en-tête fonctionne bien), puis ouvrez son onglet Plus et définissez le code de statut HTTP. La réponse par défaut reste 200 ; l'erreur ne se déclenche que lorsque la condition correspond.
Les conditions peuvent-elles utiliser mes variables d'environnement ? Non. Les valeurs {{variable}} d'Apidog ne sont pas disponibles dans les attentes de mock, et les conditions de paramètre ne prennent pas en charge les {{variables}}. Utilisez des valeurs littérales dans les conditions.
Que se passe-t-il si aucune attente ne correspond du tout ? Apidog revient à la priorité de la méthode de mock dans Paramètres du projet - Paramètres des fonctionnalités - Paramètres de mock, où le Smart mock génère une réponse à partir de votre schéma. L'ajout d'une attente de rattrapage sans condition est le moyen de garantir un fallback spécifique à la place.
Pour conclure
Le Smart mock gère le cas courant, et les attentes de mock gèrent tout ce qui contient un si : 200 pour un utilisateur connu et 401 sinon, un corps de commande différent par statut, un 500 à la demande. N'utilisez un script de mock que lorsque vous avez besoin d'une sortie calculée que les règles ne peuvent pas exprimer, et rappelez-vous qu'il s'exécute uniquement avec le Smart mock. Gardez à l'esprit l'ordre de priorité (les attentes spécifiques d'abord, les données générées ensuite) et vos mocks se brancheront exactement comme le font les vraies API. Téléchargez Apidog pour construire votre premier mock conditionnel, gratuitement, sans carte de crédit requise.