Comment générer des données de simulation conditionnelles dans Apidog (Règles personnalisées et Scripts de simulation)

Le Smart mock génère une fausse API en quelques secondes à partir du schéma de vos endpoints. Il renvoie des données plausibles (e-mails, noms, dates, identifiants) et suffit généralement à débloquer le développement frontend. En revanche, il ne peut pas choisir une réponse différente selon la requête : par exemple, renvoyer 200 pour un utilisateur connu et 401 pour les autres, ou simuler un 500 à la demande.

Essayez Apidog dès aujourd’hui

Apidog couvre ce besoin avec deux mécanismes :

• Les attentes de mock : des règles conditionnelles qui renvoient un statut, des en-têtes et un corps précis.
• Les scripts de mock : du JavaScript pour calculer une réponse à partir de la requête.

Pour les bases, consultez l’aperçu du mocking d’API. Ce workflow s’inscrit dans une approche contract-first documentée par l’OpenAPI Initiative.

Ce qu’est un mock conditionnel

Un mock conditionnel suit une règle simple :

Si la requête correspond à certaines conditions, renvoyer une réponse donnée.

Apidog propose deux niveaux de personnalisation.

1. Valeurs dynamiques dans le schéma
   
   Vous fixez une valeur ou utilisez Faker.js pour générer une donnée à chaque appel. Cela modifie le contenu des champs, mais pas la forme de réponse selon la requête.

2. Attentes de mock
   
   Une attente est une règle nommée avec :

   • des conditions facultatives ;
   • un corps de réponse ;
   • un code HTTP ;
   • des en-têtes ;
   • éventuellement un délai de réponse.

Les attentes permettent donc de simuler des branches métier : erreur d’authentification, état d’une commande, rate limiting ou indisponibilité temporaire.

Générer des valeurs dynamiques avec Faker.js

Dans le schéma d’un endpoint, les champs de type chaîne peuvent utiliser une expression Faker.js au format {{$category.method}}.

{
  "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')}}"
}

Vous pouvez :

• borner un entier avec {{$number.int(min=1000,max=9999)}} ;
• définir une plage de dates avec {{$date.between(...)}} ;
• concaténer du texte fixe et plusieurs expressions ;
• adapter les données générées à une locale.

La référence Faker.js dans Apidog liste les méthodes disponibles.

Le Smart mock reste dynamique, mais il n’est pas conditionnel. Pour sélectionner une réponse selon la requête, utilisez des attentes.

Exemple : POST /login avec 200 ou 401

Supposons un endpoint POST /login qui reçoit :

{
  "username": "[e-mail]",
  "password": "whatever"
}

Objectif :

• retourner 200 et un jeton pour [e-mail] ;
• retourner 401 pour tout autre utilisateur.

1. Ouvrir la liste des attentes

Selon votre mode de travail :

• en mode DEBUG (Requête-d’abord), ouvrez l’endpoint puis l’onglet Mock ;

• en mode DESIGN (Conception-d’abord), ouvrez l’endpoint puis l’onglet Mock avancé.

Les deux vues ouvrent la même liste d’attentes. Si nécessaire, téléchargez Apidog, puis créez ou importez l’endpoint /login.

2. Créer l’attente de succès

Créez une Nouvelle attente avec les paramètres suivants :

• Nom d’attente : login-success
• Condition :
  • type : paramètre de corps ;
  • nom : username ;
  • opérateur : égal à ;
  • valeur : [e-mail]

Pour les corps JSON, le champ de nom utilise un chemin JSON. Une propriété imbriquée s’écrit par exemple user.email.

Définissez les Données de réponse :

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Le statut par défaut est 200, vous pouvez donc enregistrer directement.

3. Créer l’attente de repli 401

Ajoutez une seconde attente :

• Nom d’attente : login-failure
• Conditions : aucune

Sans condition, cette attente devient la règle de repli. Utilisez ce corps :

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Dans l’onglet Plus, définissez :

• Code de statut HTTP : 401
• éventuellement un Délai de réponse ;
• éventuellement des en-têtes personnalisés.

Par exemple, un délai de 400 ms permet de vérifier que votre indicateur de chargement s’affiche correctement.

4. Respecter l’ordre des règles

Les attentes sont évaluées de haut en bas. La première correspondance est utilisée.

Placez donc :

1. login-success
2. login-failure

Si la règle sans condition est placée en premier, elle interceptera toutes les requêtes et votre scénario de succès ne sera jamais atteint.

Testez les deux cas avec l’URL de mock de votre endpoint :

# utilisateur connu -> 200 avec un jeton
curl -X POST https://<votre-hôte-mock>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# tout autre utilisateur -> 401
curl -X POST https://<votre-hôte-mock>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Exemple : réponses différentes pour /orders/{id}

Vous pouvez aussi conditionner une réponse avec un paramètre de chemin.

Cas d’usage : afficher différents états dans une UI sans backend réel.

Créez une attente par état, puis ajoutez une règle finale sans condition pour tous les autres identifiants.

Commande expédiée

Créez l’attente order-shipped :

• condition : paramètre de chemin id égal à 5001.

{
  "id": 5001,
  "status": "shipped",
  "total": 129.90,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Commande annulée

Créez l’attente order-cancelled :

• condition : paramètre de chemin id égal à 5002.

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Ajoutez ensuite une attente sans condition qui renvoie une commande générique en attente.

Placez toujours les règles spécifiques avant la règle de repli.

Vous pouvez combiner plusieurs conditions. Par exemple, une condition sur id et une condition sur un en-tête. Les conditions sont combinées avec une logique ET : toutes doivent correspondre.

Les conditions peuvent cibler :

• les paramètres de chemin ;
• les paramètres de requête ;
• les en-têtes ;
• les cookies ;
• le corps JSON ;
• les adresses IP.

Forcer un état d’erreur à la demande

Ne dépendez pas d’un backend défaillant pour tester votre UI d’erreur.

Ajoutez une attente contrôlée par le client, par exemple :

• type : en-tête ;
• nom : X-Mock-Scenario ;
• valeur : server-error.

Dans l’onglet Plus, définissez le statut 500, puis utilisez ce corps :

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Votre endpoint peut alors continuer à retourner 200 par défaut, tout en retournant 500 lorsque le client envoie :

X-Mock-Scenario: server-error

Appliquez le même principe pour :

• 404 ;
• 429, avec un en-tête Retry-After ;
• 503.

Pour automatiser la validation de ces scénarios, associez cette configuration à des assertions d’API.

Dans un projet partagé, chaque attente peut être activée ou désactivée indépendamment pour les environnements de mock local et cloud. Vous pouvez donc conserver une règle 500 localement sans l’exposer à vos coéquipiers dans le mock cloud.

Quand utiliser un script de mock

Les attentes sont déclaratives : elles correspondent à une requête et renvoient une réponse prédéfinie.

Utilisez un script de mock lorsque la réponse doit être calculée à partir de la requête, par exemple :

• calculer un total de commande ;
• dériver un champ depuis le corps ;
• modifier la forme de sortie selon plusieurs entrées.

Le script se trouve dans la section Script de mock, en bas de l’onglet Mock.

Les objets disponibles sont :

• $$.mockRequest pour lire la requête ;
• $$.mockResponse pour construire la réponse.

$$.mockRequest expose notamment :

• getParam(key) ;
• headers ;
• cookies ;
• body ;
• formdata ;
• urlencoded.

$$.mockResponse expose notamment :

• setBody() ;
• setCode() ;
• setDelay() ;
• json() ;
• headers ;
• code.

Exemple : calculer le total d’une commande à partir des articles reçus.

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 d’exécution est le suivant :

1. Smart mock génère une réponse initiale.
2. Le script lit $$.mockRequest.
3. Le script modifie $$.mockResponse.
4. Apidog renvoie la réponse finale.

Pour étendre cette logique, consultez la référence JavaScript MDN.

Règle importante : scripts et attentes ne se combinent pas

Les scripts de mock fonctionnent uniquement avec Smart mock.

Ils ne s’appliquent pas :

• aux attentes de mock ;
• aux exemples de réponse.

Si une attente correspond à la requête, le script ne s’exécute pas.

Choisissez donc une stratégie par endpoint :

Besoin	Solution
Réponse fixe selon une condition	Attente de mock
Statut 401, 500 ou 429 contrôlé par le client	Attente de mock
Corps calculé à partir de la requête	Script de mock
Données plausibles générées depuis le schéma	Smart mock

Comprendre la priorité de résolution

Pour chaque requête de mock, Apidog applique cet ordre :

1. Les attentes sont évaluées de haut en bas.
2. La première attente dont toutes les conditions correspondent renvoie sa réponse.
3. Si aucune attente ne correspond, Apidog utilise la Priorité de la méthode de mock définie dans :

   Paramètres du projet
   → Paramètres des fonctionnalités
   → Paramètres de mock

C’est à cette étape que Smart mock, ainsi que son éventuel script de mock, produit la réponse.

En pratique :

• placez les règles les plus spécifiques en haut ;
• placez les règles générales plus bas ;
• ajoutez une attente sans condition à la fin si vous voulez un fallback maîtrisé ;
• laissez Smart mock générer le reste.

Pour choisir la meilleure approche selon votre scénario, consultez les cas d’utilisation du mocking d’API.

Pièges à éviter

Avant de déboguer une attente qui semble ignorée, vérifiez les points suivants :

• Les conditions de paramètre ne prennent pas en charge les {{variables}}. Utilisez des valeurs littérales.
• Les conditions sur le corps ne prennent en charge que JSON, pas XML.
• Pour un corps JSON, utilisez un chemin JSON dans le champ de nom, par exemple user.email.
• Le format du corps doit correspondre à la spécification de l’endpoint. Un endpoint form-data doit utiliser une condition form-data, pas JSON.
• Les scripts de mock ne fournissent pas de fonction de journalisation.
• L’objet pm n’est pas disponible dans les scripts de mock.
• Les variables Apidog ne peuvent pas être utilisées dans les scripts de mock : gardez leur logique autonome.

La distinction entre mock local et cloud est fonctionnelle : vous pouvez activer ou désactiver les attentes indépendamment par environnement.

Automatiser le workflow avec la CLI Apidog

Le serveur de mock est une fonctionnalité de l’interface et du cloud Apidog : il n’existe pas de commande CLI qui démarre un serveur de mock en cours d’exécution.

En revanche, l’interface CLI d’Apidog permet de gérer les ressources qui alimentent les mocks : endpoints et schémas.

Comme les réponses sont générées depuis le schéma, la qualité du mock dépend directement de votre contrat API. Vous pouvez mettre à jour ce contrat dans votre code, le synchroniser, puis garder les mocks alignés sans modifier manuellement chaque réponse.

Une fois le frontend débloqué par le mock, exécutez les scénarios de test en CI pour vérifier le backend réel :

apidog run -t <scenario_id> -e <env_id> -r cli

Le mock et les tests partagent ainsi la même source de vérité.

Consultez le guide d’installation de la CLI Apidog et l’intégration de l’interface CLI Apidog dans GitHub Actions.

FAQ

Pourquoi mon attente est-elle ignorée ?

Vérifiez d’abord l’ordre des règles : une attente générale sans condition placée avant une attente spécifique intercepte la requête.

Vérifiez aussi le format :

• chemin JSON pour les corps JSON ;
• condition form-data pour les endpoints de formulaire ;
• format conforme à votre spécification.

L’aperçu du mocking d’API peut vous aider à revoir la configuration de base.

Puis-je utiliser un script et une attente sur la même réponse ?

Non. Les scripts de mock fonctionnent seulement avec Smart mock. Si une attente correspond, le script est ignoré.

Utilisez les attentes pour les branchements conditionnels et les scripts pour les réponses calculées.

Comment retourner 401 ou 500 sans modifier le 200 par défaut ?

Créez une attente dédiée avec une condition contrôlable depuis le client, comme un en-tête. Dans l’onglet Plus, définissez le code HTTP approprié.

La réponse normale reste 200 tant que cette condition n’est pas envoyée.

Les conditions peuvent-elles utiliser des variables d’environnement ?

Non. Les variables Apidog au format {{variable}} ne sont pas disponibles dans les attentes de mock. Utilisez des valeurs littérales.

Que se passe-t-il si aucune attente ne correspond ?

Apidog revient à la priorité de méthode de mock configurée dans les paramètres du projet. Smart mock génère alors une réponse depuis votre schéma.

Ajoutez une attente sans condition si vous préférez contrôler explicitement le fallback.

Conclusion

Utilisez Smart mock pour générer rapidement des données plausibles depuis votre schéma. Utilisez les attentes de mock dès que votre API doit se comporter comme une vraie API conditionnelle :

• 200 pour un utilisateur connu, 401 sinon ;
• réponses différentes selon un identifiant ;
• 500, 429 ou 503 à la demande ;
• délais et en-têtes personnalisés.

Réservez les scripts de mock aux réponses calculées à partir de la requête. Enfin, gardez toujours l’ordre de priorité en tête : règles spécifiques d’abord, fallback ensuite, puis données générées par Smart mock.

Téléchargez Apidog pour créer votre premier mock conditionnel.