Blog

Comment utiliser Supertest pour tester les API HTTP dans Node.js

Oliver Kingsley

Oliver Kingsley

14 August 2025

Comment utiliser Supertest pour tester les API HTTP dans Node.js

Dans le paysage des API en rapide évolution, les équipes ont besoin de deux choses : un retour rapide au niveau du code et une validation de bout en bout fiable sur tous les environnements. Supertest fournit la première – des assertions HTTP ultra-rapides pour les services Node.js. Et lorsque vous êtes prêt à collaborer entre les rôles, à exécuter des tests de scénario, à simuler des dépendances et à publier de la documentation, une plateforme de test d'API comme Apidog complète le tableau. Ce guide officiel et objectif explique comment utiliser Supertest pour tester les API, où il excelle, et comment l'associer à Apidog pour accélérer la livraison en toute confiance.

Apidog
button

Qu'est-ce que Supertest ?

Supertest est une bibliothèque Node.js légère pour tester les serveurs HTTP. Elle s'appuie sur superagent et vous permet d'écrire des assertions expressives sur les codes de statut, les en-têtes et les corps de réponse, sans avoir à lancer de clients externes. C'est l'outil idéal lorsque vous :

Lorsque vous avez besoin de collaboration, de gouvernance de la conformité des API, d'orchestration d'environnement et de tests visuels, vous complétez Supertest avec une plateforme de test d'API comme Apidog. Le reste de cet article montre comment faire les deux.

button

Installer et configurer Supertest

Vous pouvez installer Supertest en quelques minutes. Utilisez npm, pnpm ou yarn :

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

Une API Express minimale (app.js) :

const express = require('express');

const app = express();



app.get('/greet', (req, res) => {

  const name = req.query.name || 'World';

  res.json({ message: `Hello, ${name}!` });

});



module.exports = app;

Un test simple (app.test.js) utilisant Supertest + Jest :

const request = require('supertest');

const app = require('./app');



describe('GET /greet', () => {

  it('greets anonymously', async () => {

    const res = await request(app)

      .get('/greet')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, World!');

  });



  it('greets by name', async () => {

    const res = await request(app)

      .get('/greet?name=Alice')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, Alice!');

  });

});

Mettez à jour package.json pour exécuter les tests :

{

  "scripts": {

    "test": "jest"

  }

}

Exécutez vos tests :

npm test

Si vous préférez Mocha ou Vitest, Supertest fonctionne de la même manière – l'API .expect() est identique.

Écrire d'excellentes assertions Supertest

La puissance de Supertest réside dans ses assertions chaînables – rapides à écrire et faciles à lire. Voici des modèles que vous utiliserez tous les jours :

request(app)

  .get('/users')

  .expect(200)

  .expect('Content-Type', /json/);
request(app)

  .get('/users')

  .expect(200)

  .expect(res => {

    if (!Array.isArray(res.body)) throw new Error('Expected an array');

    if (res.body.length === 0) throw new Error('Expected at least one user');

  });
request(app)

  .get('/health')

  .expect(200)

  .expect({ status: 'ok' });



request(app)

  .get('/health')

  .expect(200)

  .expect(/"status":"ok"/);
request(app)

  .post('/posts')

  .set('Authorization', 'Bearer test-token')

  .send({ title: 'Hello', body: 'World' })

  .expect(201)

  .expect(res => {

    if (!res.body.id) throw new Error('Missing id');

  });
const agent = request.agent(app);

await agent.get('/login').expect(200);

await agent.get('/me').expect(200).expect(res => {

  if (!res.body.user) throw new Error('Expected authenticated user');

});
Conseil : Gardez les tests petits et déterministes. Supertest excelle dans la validation des contrôleurs, des middlewares et des adaptateurs de manière isolée.

Supertest en CI/CD et dans les monorepos

Pour maintenir une qualité constante, exécutez Supertest en CI pour chaque pull request. Une configuration typique :

Exemple d'extrait GitHub Actions :

name: api-tests

on: [push, pull_request]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: '20'

      - run: npm ci

      - run: npm test -- --ci

Dans les monorepos, n'exécutez que les tests affectés et mettez en cache node_modules pour accélérer les boucles de rétroaction. Le faible surcoût de Supertest en fait un excellent choix pour les grandes bases de code.

Quand utiliser une plateforme de test d'API

Supertest est excellent pour un retour rapide au niveau du code. Mais les réalités de la production exigent davantage :

C'est là qu'une plateforme de test d'API comme Apidog brille. Elle unifie la conception d'API, la simulation, le test, le débogage et la documentation pour maintenir les équipes alignées et vos portes de qualité durables.

button
Interface utilisateur de test Apidog

Pourquoi Apidog complète Supertest

Un flux de travail combiné : Supertest + Apidog

Utilisez Supertest pour les vérifications centrées sur le développeur et Apidog pour la collaboration de bout en bout. Voici une répartition pragmatique des responsabilités :

Tâche
Supertest
Apidog
Vérifications unitaires du contrôleur/middleware
Excellent
Complémentaire
Régressions rapides de contrat (statut/en-têtes)
Excellent
Excellent
Gouvernance de schéma (OpenAPI)
Manuel
De première classe
Serveurs de simulation pour le front-end
Limité
Intégré
Scénarios basés sur les données
Limité
De première classe
Orchestration CI à travers les environnements
Bon
De première classe
Collaboration d'équipe/docs
Minimal
De première classe

Exemple de flux :

Modèles Supertest avancés

Quelques conseils supplémentaires qui portent leurs fruits :

Conclusion : Une approche équilibrée de la qualité des API

Les API de qualité sont construites avec à la fois rapidité et rigueur. Supertest offre aux développeurs un moyen rapide et expressif de vérifier les points de terminaison près du code – parfait pour des boucles de rétroaction courtes et pour détecter les régressions avant qu'elles ne sortent d'une branche. C'est simple, fiable et éprouvé sur de nombreux backends Node.js.

Cependant, à mesure que les systèmes se développent, vous avez besoin de collaboration, de gouvernance des contrats et d'exécution sensible à l'environnement. C'est là qu'Apidog – une plateforme de test d'API intégrée – élève votre flux de travail. En unifiant la conception des contrats (OpenAPI), les serveurs de simulation, les assertions visuelles, les variables d'environnement et l'orchestration CI, Apidog aide les équipes à avancer de concert de l'idée à la livraison. Le front-end, le back-end et l'assurance qualité peuvent partager la même source de vérité tandis que Supertest continue de protéger vos chemins de code avec des assertions rapides et déterministes.

Si vous voulez une vélocité confiante, utilisez les deux :

Cette approche équilibrée produit des API qui sont non seulement correctes aujourd'hui, mais aussi résilientes à mesure que votre produit évolue. Commencez à écrire vos vérifications Supertest dès maintenant – et donnez-leur vie dans un pipeline de qualité production avec Apidog.

button

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger