Valider les réponses API dans les tests Playwright

Vos tests Playwright réussissent. Le bouton de connexion clique, le tableau de bord s'affiche, le graphique se dessine. Puis un client signale un bug : les chiffres du graphique sont incorrects. Vous enquêtez et découvrez que l'API a renvoyé un statut 200 avec une charge utile mal formée, et que votre suite de tests de bout en bout ne l'a jamais remarqué car elle ne vérifiait que l'affichage des pixels à l'écran. C'est l'écart que les tests de navigateur seuls ne peuvent pas combler, et c'est là que les assertions d'API deviennent non négociables. Des outils comme Apidog vous offrent un moyen de valider les contrats d'API, les schémas et la sémantique des réponses avec la même rigueur que vous appliquez à vos flux d'interface utilisateur (UI), puis d'exécuter les deux suites ensemble en CI.

TL;DR

Vous pouvez valider des API dans les tests Playwright en combinant la fixture request de Playwright et l'intercepteur page.route avec des scénarios Apidog qui ciblent la même spécification OpenAPI. Partagez les fixtures via un seul fichier de spécification, validez les schémas de réponse dans les deux couches et exécutez les deux suites dans une seule tâche CI afin qu'un changement de contrat échoue rapidement à l'un ou l'autre endroit.

Introduction

Playwright est le framework d'automatisation de navigateur par défaut pour de nombreuses équipes en 2026, et la documentation Playwright facilite les tests d'API : quelques appels request.get, un expect(response.status()).toBe(200), et le tour est joué. Les problèmes commencent lorsque vous passez à l'échelle. Vous vous retrouvez avec des centaines de tests qui vérifient les codes d'état mais pas la forme de la réponse, aucune source de vérité partagée entre vos flux de navigateur et vos flux d'API, et aucun moyen de simuler les API hors ligne lorsque le backend est lent ou en panne.

La solution est simple. Traitez votre spécification OpenAPI comme le contrat, pilotez les appels request de Playwright et les intercepteurs page.route à partir de ce contrat, et exécutez une suite de scénarios Apidog par rapport à la même spécification pour une validation approfondie du schéma, de la logique métier et des requêtes chaînées. Vous obtenez un retour rapide en CI, des limites de propriété claires entre les tests frontend et backend, et aucune fixture en double. Si vous souhaitez d'abord installer l'outil, Téléchargez Apidog et revenez ; les étapes ci-dessous supposent qu'il est disponible localement.

Voici ce que vous retirerez de cet article : un modèle mental clair sur la place des assertions d'API dans une suite Playwright, un modèle request.fixture fonctionnel, une configuration étape par étape pour le partage des fixtures entre Playwright et Apidog, des conseils avancés pour la CI et la simulation, et un tableau comparatif des principales alternatives. Pour un contexte plus large sur les choix d'outils de test, consultez notre avis sur les outils de test d'API pour les ingénieurs QA.

L'écart entre les tests Playwright et les assertions d'API

Un test Playwright typique se connecte, navigue vers une page et affirme qu'un élément d'interface utilisateur est visible. Cela vous indique que le flux visible par l'utilisateur fonctionne. Cela ne vous dit rien sur l'API qui le sous-tend. Trois modes de défaillance passent inaperçus :

Premièrement, les régressions de la forme de la charge utile. Le point de terminaison renvoie 200 avec un champ renommé de total_count en totalCount. L'interface utilisateur pourrait silencieusement forcer ou afficher zéro. Votre test Playwright voit un nombre à l'écran et réussit.

Deuxièmement, la dérive de la logique métier. Un point de terminaison de réduction applique une remise de 10 % au lieu des 15 % contractuels. L'interface utilisateur affiche ce que l'API renvoie, donc le test réussit. Seule l'équipe financière le remarque, des semaines plus tard.

Troisièmement, la couverture des chemins d'erreur. Les tests Playwright exécutent presque toujours le chemin nominal. Votre API a des dizaines de branches 4xx et 5xx : limites de débit, jetons expirés, échecs partiels, conflits d'idempotence. Aucune d'entre elles n'est exercée à moins que vous n'écriviez une suite de tests API distincte.

Vous pouvez corriger une partie de cela en ajoutant des appels request.get à l'intérieur de vos spécifications Playwright et en affirmant les corps de réponse. Cela fonctionne pour une poignée de points de terminaison. Cela s'effondre lorsque vous avez 200 points de terminaison et que vous souhaitez des scénarios chaînés comme « créer une commande, récupérer une commande, annuler une commande, vérifier le webhook de remboursement ». Playwright est avant tout un framework d'automatisation de navigateur ; il n'est pas conçu pour les workflows API avec état ou l'ergonomie des assertions au niveau du schéma. C'est là qu'un outil de test d'API dédié prend tout son sens.

La bonne répartition est :

• Les tests Playwright vérifient les flux UI, l'interception réseau et une fine couche de tests de fumée API à la limite d'une action utilisateur.
• Les scénarios Apidog vérifient la conformité du schéma, les workflows API chaînés, la conformité contractuelle et les chemins d'erreur en profondeur.

Les deux suites consomment la même spécification OpenAPI afin que vous n'ayez jamais deux versions de la vérité. Pour une vue plus approfondie de l'approche contract-first, notre article sur les outils de développement contract-first explique pourquoi la spécification doit guider.

Comment partager les fixtures entre Playwright et Apidog

La source unique de vérité est votre spécification OpenAPI, généralement openapi.yaml ou openapi.json à la racine du dépôt. Playwright la lit pour des assistants de requête typés et des charges utiles d'exemple ; Apidog l'importe directement pour peupler les étapes de scénario. Chaque fois que le backend livre un changement de contrat, les deux suites le reprennent.

Commencez par un dossier fixtures/ qui contient des données de test réutilisables : utilisateurs, jetons, exemples de charges utiles. Créez un fichier de fixture Playwright qui les charge et les expose aux tests :

// tests/fixtures/api.ts
import { test as base, APIRequestContext, expect } from '@playwright/test';
import { readFileSync } from 'fs';
import path from 'path';

type ApiFixtures = {
  apiRequest: APIRequestContext;
  authToken: string;
  sampleOrder: Record<string, unknown>;
};

export const test = base.extend<ApiFixtures>({
  apiRequest: async ({ playwright }, use) => {
    const ctx = await playwright.request.newContext({
      baseURL: process.env.API_BASE_URL ?? 'https://api.staging.example.com',
      extraHTTPHeaders: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
      },
    });
    await use(ctx);
    await ctx.dispose();
  },

  authToken: async ({ apiRequest }, use) => {
    const res = await apiRequest.post('/auth/token', {
      data: { email: 'qa@example.com', password: process.env.QA_PASSWORD },
    });
    expect(res.status()).toBe(200);
    const body = await res.json();
    await use(body.access_token);
  },

  sampleOrder: async ({}, use) => {
    const raw = readFileSync(
      path.join(__dirname, '..', '..', 'fixtures', 'order.json'),
      'utf8',
    );
    await use(JSON.parse(raw));
  },
});

export { expect };

Maintenant, vous importez test à partir de ce fichier de fixture au lieu de @playwright/test dans chaque spécification, et vous disposez d'un apiRequest typé, d'un authToken frais et de données sampleOrder prêtes à l'emploi. Le fichier order.json est la même charge utile qu'Apidog utilise comme corps d'exemple pour POST /orders dans vos scénarios. Modifiez-le une fois, les deux suites changent.

Du côté Apidog, ouvrez le projet, cliquez sur « Importer » et pointez-le vers le même openapi.yaml. Apidog génère des points de terminaison, des exemples de requêtes et des schémas de paramètres en quelques secondes. Ensuite, enregistrez vos charges utiles de fixture en tant que « Variables d'environnement » ou « Ensembles de données » Apidog :

// tests/orders.spec.ts
import { test, expect } from './fixtures/api';

test('POST /orders returns a valid order with 15 percent discount', async ({
  apiRequest,
  authToken,
  sampleOrder,
}) => {
  const res = await apiRequest.post('/orders', {
    headers: { Authorization: `Bearer ${authToken}` },
    data: { ...sampleOrder, coupon: 'SAVE15' },
  });

  expect(res.status()).toBe(201);
  const body = await res.json();

  expect(body).toMatchObject({
    id: expect.any(String),
    status: 'pending',
    discount_pct: 15,
    total_cents: expect.any(Number),
  });
  expect(body.total_cents).toBeLessThan(sampleOrder.subtotal_cents);
});

Dans Apidog, l'étape de scénario correspondante envoie la même charge utile, puis exécute la vérification de schéma JSON intégrée par rapport au composant Order dans openapi.yaml. Cela vous donne de la profondeur : chaque champ est vérifié par type, les champs requis sont vérifiés, les valeurs d'énumération sont appliquées. Playwright capture l'assertion sémantique de grande valeur (discount_pct: 15) ; Apidog capture chaque champ qui dérive, même ceux que vous avez oublié d'affirmer manuellement. Si vous êtes nouveau dans les tests pilotés par spécification, notre guide sur les workflows API axés sur la conception montre le modèle environnant.

Pour les équipes qui utilisent déjà Postman et envisagent de changer, les alternatives auto-hébergées à Postman couvrent les mécanismes de migration.

Mettre en place le workflow Apidog + Playwright

Voici une configuration propre et reproductible qui vous permet de passer de zéro à une CI à double suite en environ une heure.

Étape 1 : Une spécification pour les gouverner toutes. Placez openapi.yaml à la racine du dépôt. Traitez-le comme du code : revues de PR requises, les changements majeurs nécessitent une augmentation de version majeure. Si vous n'en avez pas encore, générez un brouillon à partir de vos routes existantes à l'aide d'un plugin de framework (FastAPI, NestJS et d'autres émettent OpenAPI nativement), puis modifiez-le manuellement. Apidog peut également rétro-concevoir une spécification à partir du trafic si vous importez un fichier HAR.

Étape 2 : Connecter Playwright. Installez Playwright (npm init playwright@latest) et ajoutez le fichier de fixture montré ci-dessus. Ajoutez un script npm run test:e2e et un playwright.config.ts qui pointe vers votre environnement de staging. Gardez les tests petits ; un scénario par spécification.

Étape 3 : Ajouter la couche de scénarios Apidog. Dans votre projet Apidog, importez openapi.yaml, puis construisez un scénario par parcours utilisateur critique : inscription, paiement, remboursement, livraison de webhook, et ainsi de suite. Chaque scénario est une séquence d'appels API avec des assertions chaînées. Apidog prend en charge les variables d'environnement, les scripts de pré-requête et les assertions post-réponse. Exportez le scénario sous forme de JSON exécutable en ligne de commande via l'Apidog CLI (apidog-cli run scenario.json).

Étape 4 : Interception réseau dans Playwright. Lorsque l'interface utilisateur récupère des données que vous ne souhaitez pas atteindre en direct, utilisez page.route pour intercepter et simuler. Les réponses simulées proviennent des mêmes fichiers de fixture, de sorte que le contrat reste cohérent :

test('dashboard renders cached order list when offline', async ({
  page,
  sampleOrder,
}) => {
  await page.route('**/api/orders', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ orders: [sampleOrder] }),
    });
  });

  await page.goto('/dashboard');
  await expect(page.getByTestId('order-row')).toHaveCount(1);
});

Ensuite, dans Apidog, exécutez le même scénario GET /orders contre votre backend réel ou contre un serveur de simulation Apidog. Même fixture, deux couches de vérification.

Étape 5 : Intégration CI. Ajoutez un workflow GitHub Actions qui exécute les deux suites en parallèle :

name: tests
on: [push, pull_request]
jobs:
  playwright:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm i -g apidog-cli
      - run: apidog-cli run ./apidog/scenarios/checkout.json --reporters cli,junit

L'échec de l'une ou l'autre tâche bloque la fusion. Utilisez --reporters junit pour que GitHub annote les assertions échouées en ligne sur la PR. La documentation GitHub Actions couvre les builds matriciels et la mise en cache si vous souhaitez étendre cela. Pour les équipes sans fonction QA dédiée, le guide des outils de test d'API pour les ingénieurs QA explique comment attribuer la propriété de chaque suite.

Étape 6 : Détection de dérive. Planifiez une tâche quotidienne qui compare votre openapi.yaml en direct avec la version contre laquelle vos tests ont été exécutés pour la dernière fois. Si un champ a changé de type, la différence fait échouer la build avant même l'exécution des tests. Cela intercepte la classe de bugs « 200 OK avec charge utile incorrecte » avec laquelle nous avons commencé.

Techniques avancées et astuces de pro

Quelques astuces qui rapportent une fois la configuration de base opérationnelle.

Épinglez l'afficheur de trace Playwright. Définissez trace: 'on-first-retry' dans playwright.config.ts. Lorsqu'un test instable échoue en CI, vous obtenez une chronologie complète des appels réseau, des instantanés DOM et des journaux de console. Associez-le à apidog-cli --report html pour le côté API. Ensemble, ils vous montrent si l'interface utilisateur a échoué en premier ou si l'API a dérivé.

Utilisez les serveurs de simulation Apidog pour les exécutions hors ligne. Apidog peut lancer un serveur de simulation à partir de votre spécification OpenAPI en un clic. Pointez votre environnement de développement local vers celui-ci lorsque l'équipe backend est en cours de déploiement ou que la base de données de staging est réinitialisée. Votre suite Playwright s'exécute avec succès contre la simulation, et vos scénarios Apidog vérifient le véritable backend en parallèle. Pour en savoir plus sur ce modèle, consultez notre article sur la génération de tests API assistée par l'IA où les simulations sont centrales.

Limitez le nombre de tentatives à deux. retries: 2 dans playwright.config.ts. Si un test nécessite trois tentatives pour réussir, il est instable et vous avez un vrai problème. Ne le masquez pas avec retries: 5. Il en va de même pour les scénarios Apidog : définissez retry: 1 par requête, maximum.

Échouez en cas de dérive de schéma. Lorsque Apidog détecte une non-concordance de schéma, quittez avec un code d'erreur par défaut. Ne laissez pas un avertissement passer inaperçu. Si vous devez autoriser une fenêtre d'échec souple, protégez-la derrière une variable d'environnement comme ALLOW_SCHEMA_DRIFT=true et exigez un commentaire sur la PR expliquant pourquoi.

Étiquetez les tests par priorité. Utilisez test.describe.configure({ mode: 'serial' }) de Playwright pour les flux avec état et étiquetez les autres avec @smoke, @regression, @nightly. Exécutez les tests de fumée à chaque push, la régression sur les PR vers main, et la suite complète de scénarios Apidog chaque nuit. Économise des minutes de CI sans perdre de couverture.

Erreurs courantes à éviter :

• Affirmer seulement status === 200. Ajoutez au moins une vérification de champ de corps.
• Coder en dur les jetons bearer dans les fixtures. Utilisez un beforeAll pour récupérer de nouveaux jetons.
• Laisser Playwright et Apidog importer des fichiers de fixture différents. Une seule source, point final.
• Ignorer l'Apidog CLI en CI parce que « l'outil UI est suffisant ». Ce n'est pas le cas ; la CLI est ce qui fait échouer la build.
• Traiter les stubs page.route comme un substitut aux vrais tests API. Ils sont pour l'isolation, pas pour la couverture.

Pour les équipes générant des tests avec l'IA, le guide comment tester les API des agents IA couvre les cas non déterministes qui nécessitent une attention particulière.

Alternatives et comparaison d'outils

Plusieurs combinaisons d'outils peuvent valider les API aux côtés des tests de navigateur. Voici comment se comparent les principales options.

Si vous venez d'outils plus anciens de l'ère SOAP, nos articles sur les alternatives aux scripts Groovy de SoapUI et les alternatives à ReadyAPI couvrent le chemin de migration. Pour les workflows axés sur le local, les extensions VSCode de client REST valent la peine d'être lues.

Le jumelage Playwright + Apidog l'emporte pour les équipes qui ont une spécification OpenAPI, livrent plusieurs services et souhaitent un pipeline CI unique qui détecte à la fois les régressions UI et API sans payer deux licences SaaS par ingénieur.

Cas d'utilisation réels

Paiement e-commerce. Une équipe de vente au détail exécute des tests Playwright pour le flux du panier à la confirmation et des scénarios Apidog pour l'intention de paiement, la vérification de fraude et la chaîne API de décrémentation des stocks. Lorsque la passerelle de paiement a changé un champ de réponse de error_code en errorCode, Apidog l'a détecté en 90 secondes ; Playwright aurait affiché un écran générique « échec du paiement » et aurait pris des heures à trier.

Tableau de bord SaaS avec données graphiques. Un produit d'analyse B2B valide le rendu de l'interface utilisateur avec les instantanés Playwright et utilise Apidog pour affirmer que les points de terminaison d'agrégation renvoient des sommes, des centiles et des séries temporellement regroupées corrects. Un bug où le point de terminaison de latence p99 supprimait silencieusement les valeurs aberrantes a été détecté au niveau de l'API ; le graphique semblait correct.

Workflow basé sur les webhooks. Une équipe fintech utilise Playwright pour le portail utilisateur et des scénarios Apidog pour la livraison de webhook, la logique de réessai et l'idempotence. Le script d'Apidog vérifie que les ID de webhook en double sont rejetés, que les signatures sont valides et que la fenêtre de cohérence éventuelle est inférieure à 30 secondes.

Conclusion

Playwright excelle dans les flux de navigateur. Il n'est pas conçu pour les tests d'API approfondis. L'associer à Apidog vous offre :

• Une spécification OpenAPI comme contrat entre les deux suites.
• Des fixtures partagées pour que les données de test ne dérivent jamais.
• Une validation au niveau du schéma sur chaque point de terminaison, au-delà des seuls codes d'état.
• Des serveurs de simulation pour le développement hors ligne.
• Un pipeline CI unique qui échoue en cas de régressions UI ou API.
• Une interception réseau dans Playwright, des chaînes de scénarios approfondies dans Apidog.
• Une propriété claire : les ingénieurs UI possèdent les spécifications Playwright, les ingénieurs API possèdent les scénarios Apidog.

Commencez par un parcours critique, comme le paiement ou l'inscription. Câblez la fixture Playwright, construisez le scénario Apidog correspondant, exécutez les deux en CI. Développez à partir de là. Téléchargez Apidog, importez votre spécification OpenAPI, et vous pouvez avoir le premier scénario en cours d'exécution dès aujourd'hui.

FAQ

Puis-je valider les API dans les tests Playwright sans Apidog ? Oui, en utilisant la fixture request de Playwright et des appels expect manuels. Vous couvrirez les codes d'état et quelques champs de corps. Pour la validation de schéma, les scénarios chaînés, les simulations et la couverture des chemins d'erreur à grande échelle, un outil dédié comme Apidog est plus rapide et produit moins de faux positifs. Consultez notre comparaison des outils de test d'API pour les ingénieurs QA pour les compromis.

Ai-je besoin d'une spécification OpenAPI pour utiliser cette configuration ? Vous en avez besoin pour en tirer tous les avantages. Sans spécification, vous pouvez toujours exécuter Playwright et Apidog côte à côte, mais vous perdez la source de vérité partagée et devez maintenir les exemples de charges utiles à deux endroits. La génération d'une spécification à partir de routes existantes prend un jour ou deux.

Comment gérer l'authentification entre les deux outils ? Utilisez une étape beforeAll qui récupère un nouveau jeton de votre point de terminaison d'authentification, puis stockez-le dans une fixture Playwright et une variable d'environnement Apidog. Faites pivoter les jetons à chaque exécution de test afin que les jetons périmés ne provoquent jamais d'instabilités.

Les scénarios Apidog peuvent-ils remplacer entièrement Playwright ? Non. Apidog excelle dans les workflows API mais ne rend pas les navigateurs. Pour les assertions d'interface utilisateur (texte visible, mise en page, flux de clics), vous avez toujours besoin de Playwright. Les deux outils couvrent des surfaces différentes.

Que faire si mon backend n'a pas d'environnement de staging stable ? Utilisez le serveur de simulation intégré d'Apidog. Il lance une simulation avec état à partir de votre spécification OpenAPI en un clic, renvoyant des exemples de réponses définis dans la spécification. Votre suite Playwright et vos scénarios Apidog s'exécutent tous deux correctement contre la simulation, et vous revenez au vrai backend lorsque le staging est sain.

Comment garder la CI rapide à mesure que la suite grandit ? Étiquetez les tests par priorité et n'exécutez que @smoke à chaque push. Exécutez la régression complète et la suite de scénarios Apidog sur les PR vers main et selon un calendrier nocturne. Parallélisez Playwright avec workers: 4 et les scénarios Apidog avec l'option --parallel de la CLI.

Ai-je besoin d'un plan Apidog payant pour la CI ? L'Apidog CLI s'exécute localement et en CI sans licence par siège pour l'exécution des scénarios. Vérifiez la page de tarification actuelle avant d'adopter à grande échelle. Le niveau gratuit couvre la plupart des petites équipes.