Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les tests end-to-end avec Supertest

Cette leçon teste l'API de bout en bout, par de vraies requêtes HTTP envoyées avec Supertest. L'application de test est construite à partir d'AppModule. L'exécution du fichier généré par nest new, ada...

0 chapitres 0 QCM Accès gratuit
Les tests end-to-end avec Supertest

À propos de ce cours

Cette leçon teste l'API de bout en bout, par de vraies requêtes HTTP envoyées avec Supertest. L'application de test est construite à partir d'AppModule. L'exécution du fichier généré par nest new, adapté à notre API, révèle un piège : sans les réglages de main.ts, le préfixe /api et le ValidationPipe manquent, d'où un 404 et une erreur 500 au lieu d'un 400. La correction partage une fonction configurerApp entre main.ts et les tests. Les tests couvrent ensuite statuts, corps, en-têtes, validation, conflits, et le remplacement du service d'e-mail par overrideProvider. Activités corrigées.

Objectifs de la leçon

  • Construire l'application complète dans un test.
  • Envoyer des requêtes et vérifier statuts, corps et en-têtes avec Supertest.
  • Partager la configuration de main.ts avec les tests.
  • Remplacer un service externe avec overrideProvider.
Le principe

Un test end-to-end traite l'API comme une boîte noire : il envoie des requêtes HTTP et vérifie les réponses, exactement comme un client. Cette fois, tout s'exécute : routage, guards, pipes, filtres, contrôleurs, services. Supertest (installé par nest new) envoie les requêtes au serveur de l'application sans même ouvrir de port réseau.

Test end-to-end avec Supertest

L'application complète reçoit de vraies requêtes HTTP.

L'API testée

📄 src/stagiaires/stagiaires.service.ts

import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
import { CreerStagiaireDto } from './stagiaire.dto';
import { MailService } from './mail.service';

@Injectable()
export class StagiairesService {
  private liste: (CreerStagiaireDto & { id: number })[] = [];
  constructor(private readonly mail: MailService) {}

  lister() { return this.liste; }

  trouver(id: number) {
    const s = this.liste.find((x) => x.id === id);
    if (!s) throw new NotFoundException(`Stagiaire ${id} introuvable`);
    return s;
  }

  async creer(dto: CreerStagiaireDto) {
    if (this.liste.some((s) => s.email === dto.email)) throw new ConflictException('E-mail déjà utilisé');
    const s = { id: this.liste.length + 1, ...dto };
    this.liste.push(s);
    await this.mail.envoyer(dto.email, 'Bienvenue');
    return s;
  }
}

📄 src/stagiaires/stagiaires.controller.ts

import { Body, Controller, Get, Headers, Param, ParseIntPipe, Post, UnauthorizedException } from '@nestjs/common';
import { CreerStagiaireDto } from './stagiaire.dto';
import { StagiairesService } from './stagiaires.service';

@Controller('stagiaires')
export class StagiairesController {
  constructor(private readonly service: StagiairesService) {}

  @Get()
  lister() { return this.service.lister(); }

  @Get(':id')
  trouver(@Param('id', ParseIntPipe) id: number) { return this.service.trouver(id); }

  // Création réservée à l'administration (clé simplifiée pour l'exemple ; JWT au chapitre 13)
  @Post()
  creer(@Body() dto: CreerStagiaireDto, @Headers('x-cle') cle?: string) {
    if (cle !== 'cle-admin') throw new UnauthorizedException();
    return this.service.creer(dto);
  }
}
Le piège du fichier généré

nest new crée test/app.e2e-spec.ts. Adaptons-le naïvement à notre API :

📄 test/stagiaires.e2e-spec.ts (version naïve)

import { INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { App } from 'supertest/types';
import { AppModule } from '../src/app.module';

// Comme le fichier généré par « nest new » : l'application est créée SANS les réglages de main.ts
describe('Stagiaires (e2e, version naïve)', () => {
  let app: INestApplication<App>;

  beforeAll(async () => {
    const module = await Test.createTestingModule({ imports: [AppModule] }).compile();
    app = module.createNestApplication();
    await app.init();
  });
  afterAll(() => app.close());

  it('GET /api/stagiaires → 200', () => request(app.getHttpServer()).get('/api/stagiaires').expect(200));

  it('POST invalide → 400', () =>
    request(app.getHttpServer()).post('/stagiaires').set('x-cle', 'cle-admin').send({ nom: 'S', email: 'faux' }).expect(400));
});

Résultat réellement obtenu :

$ npm run test:e2e
FAIL test/stagiaires.e2e-spec.ts
  Stagiaires (e2e, version naïve)
    ✕ GET /api/stagiaires → 200 (79 ms)
    ✕ POST invalide → 400 (45 ms)

  ● Stagiaires (e2e, version naïve) › GET /api/stagiaires → 200

    expected 200 "OK", got 404 "Not Found"

      16 |   afterAll(() => app.close());
      17 |
    > 18 |   it('GET /api/stagiaires → 200', () => request(app.getHttpServer()).get('/api/stagiaires').expect(200));
         |                                                                                             ^
      19 |
      20 |   it('POST invalide → 400', () =>
      21 |     request(app.getHttpServer()).post('/stagiaires').set('x-cle', 'cle-admin').send({ nom: 'S', email: 'faux' }).expect(400));

      at Object.<anonymous> (stagiaires.e2e-spec.ts:18:93)
      ----
      at Test._assertStatus (../node_modules/supertest/lib/test.js:535:14)
      at ../node_modules/supertest/lib/test.js:591:13
      at Test._assertFunction (../node_modules/supertest/lib/test.js:568:13)
      at Test.assert (../node_modules/supertest/lib/test.js:432:23)
      at localAssert (../node_modules/supertest/lib/test.js:382:38)
      at Server.<anonymous> (../node_modules/supertest/lib/test.js:126:7)

  ● Stagiaires (e2e, version naïve) › POST invalide → 400

    expected 400 "Bad Request", got 500 "Internal Server Error"

      19 |
      20 |   it('POST invalide → 400', () =>
    > 21 |     request(app.getHttpServer()).post('/stagiaires').set('x-cle', 'cle-admin').send({ nom: 'S', email: 'faux' }).expect(400));
         |                                                                                                                  ^
      22 | });
      23 |

      at Object.<anonymous> (stagiaires.e2e-spec.ts:21:114)
      ----
      at Test._assertStatus (../node_modules/supertest/lib/test.js:535:14)
      at ../node_modules/supertest/lib/test.js:591:13
      at Test._assertFunction (../node_modules/supertest/lib/test.js:568:13)
      at Test.assert (../node_modules/supertest/lib/test.js:432:23)
      at localAssert (../node_modules/supertest/lib/test.js:382:38)
      at Server.<anonymous> (../node_modules/supertest/lib/test.js:126:7)

Test Suites: 1 failed, 1 total
Tests:       2 failed, 2 total
Snapshots:   0 total
Time:        1.268 s
Ran all test suites.

Les deux tests échouent, et pour une raison qui n'a rien à voir avec l'API : createNestApplication() crée l'application sans passer par main.ts. Pas de préfixe /api (d'où le 404), pas de ValidationPipe: les données invalides sont acceptées, le service est appelé et l'envoi d'e-mail plante (500). Pire : un test qui ne vérifierait que le cas valide passerait, sur une application différente de celle de production.

La solution : une fonction partagée

📄 src/configurer-app.ts

import { INestApplication, ValidationPipe } from '@nestjs/common';

// Réglages communs à main.ts ET aux tests e2e : une seule source de vérité
export function configurerApp(app: INestApplication) {
  app.setGlobalPrefix('api');
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
  return app;
}

📄 src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { configurerApp } from './configurer-app';

async function bootstrap() {
  const app = configurerApp(await NestFactory.create(AppModule));
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
Les tests e2e

📄 test/stagiaires.e2e-spec.ts

import { INestApplication } from '@nestjs/common';
import { Test } from '@nestjs/testing';
import request from 'supertest';
import { App } from 'supertest/types';
import { AppModule } from '../src/app.module';
import { configurerApp } from '../src/configurer-app';
import { MailService } from '../src/stagiaires/mail.service';

describe('Stagiaires (e2e)', () => {
  let app: INestApplication<App>;
  const mail = { envoyer: jest.fn().mockResolvedValue('ok') };     // aucun e-mail réel pendant les tests
  const admin = { 'x-cle': 'cle-admin' };
  const sami = { nom: 'Sami Ben Ali', email: 'sami@exemple.tn', groupe: 'DEV101' };

  beforeAll(async () => {
    const module = await Test.createTestingModule({ imports: [AppModule] })
      .overrideProvider(MailService).useValue(mail)                  // remplacer UN provider du vrai module
      .compile();
    app = configurerApp(module.createNestApplication());            // les MÊMES réglages que main.ts
    await app.init();
  });

  afterAll(() => app.close());

  it('GET /api/stagiaires → 200 et liste vide au départ', () =>
    request(app.getHttpServer()).get('/api/stagiaires').expect(200).expect([]));

  it('POST sans clé → 401', () =>
    request(app.getHttpServer()).post('/api/stagiaires').send(sami).expect(401));

  it('POST avec données invalides → 400 et messages de validation', async () => {
    const r = await request(app.getHttpServer()).post('/api/stagiaires').set(admin).send({ nom: 'S', email: 'faux', admin: true });
    expect(r.status).toBe(400);
    expect(r.body.message).toEqual(expect.arrayContaining([
      'property admin should not exist', 'email must be an email', 'nom must be longer than or equal to 2 characters',
    ]));
  });

  it('POST valide → 201, puis e-mail « envoyé » et stagiaire consultable', async () => {
    const r = await request(app.getHttpServer()).post('/api/stagiaires').set(admin).send(sami).expect(201);
    expect(r.body).toEqual({ id: 1, ...sami });
    expect(mail.envoyer).toHaveBeenCalledWith('sami@exemple.tn', 'Bienvenue');

    await request(app.getHttpServer()).get('/api/stagiaires/1').expect(200).expect((res) => {
      expect(res.body.nom).toBe('Sami Ben Ali');
    });
  });

  it('POST du même e-mail → 409', () =>
    request(app.getHttpServer()).post('/api/stagiaires').set(admin).send(sami).expect(409));

  it('GET /api/stagiaires/abc → 400 ; /api/stagiaires/99 → 404', async () => {
    await request(app.getHttpServer()).get('/api/stagiaires/abc').expect(400);
    await request(app.getHttpServer()).get('/api/stagiaires/99').expect(404, { message: 'Stagiaire 99 introuvable', error: 'Not Found', statusCode: 404 });
  });
});

Résultat réellement obtenu :

$ npm run test:e2e -- --verbose
PASS test/stagiaires.e2e-spec.ts
  Stagiaires (e2e)
    ✓ GET /api/stagiaires → 200 et liste vide au départ (69 ms)
    ✓ POST sans clé → 401 (65 ms)
    ✓ POST avec données invalides → 400 et messages de validation (9 ms)
    ✓ POST valide → 201, puis e-mail « envoyé » et stagiaire consultable (14 ms)
    ✓ POST du même e-mail → 409 (6 ms)
    ✓ GET /api/stagiaires/abc → 400 ; /api/stagiaires/99 → 404 (8 ms)

Test Suites: 1 passed, 1 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        1.383 s
Ran all test suites.
Ce qu'il faut retenir du code
  • request(app.getHttpServer()) puis la méthode (.get, .post, .patch, .delete), .set(en-têtes) (un jeton : .set('Authorization', `Bearer ${jeton}`)), .send(corps).
  • .expect(201) vérifie le statut ; .expect(statut, corps) le corps exact ; .expect((res) => { … }) une vérification libre ; ou bien on récupère la réponse avec await et on utilise expect(r.body)… de Jest.
  • beforeAll / afterAll: une seule application pour tout le fichier (la créer prend du temps). Les tests partagent donc l'état : le 409 n'est possible que parce que le test précédent a créé Sami. C'est acceptable en e2e quand les tests racontent un scénario, mais l'ordre compte.
  • overrideProvider(MailService).useValue(…): on garde tout le vrai module, sauf l'e-mail. On peut même vérifier l'appel (toHaveBeenCalledWith).
  • app.close() à la fin : sinon Jest reste bloqué (« Jest did not exit ») à cause des connexions ouvertes, notamment vers la base de données.

Et la base de données ? Un test e2e qui utilise la vraie base de développement risque d'en effacer ou d'en modifier les données. On utilise une base dédiée aux tests, vidée à chaque exécution, configurée par un fichier .env.test (Jest définit NODE_ENV=test). C'est l'objet du TP 11, qui vérifie aussi ce qu'aucun mock ne peut vérifier : contraintes d'unicité, clés étrangères, verrous.

Activités

Activité 1 Tester l'authentification

Dans le projet du TP 8, écrivez un test e2e : inscription (201), connexion (200, jeton reçu), GET /api/auth/profil sans jeton (401), avec jeton (200 et bon e-mail), avec un jeton modifié (401).

Voir le corrigé
it('parcours de connexion', async () => {
  await http.post('/api/auth/inscription').send({ email: 'e2e@exemple.tn', nom: 'Test E2E', motDePasse: 'Stagiaire2026' }).expect(201);
  const { body } = await http.post('/api/auth/connexion').send({ email: 'e2e@exemple.tn', motDePasse: 'Stagiaire2026' }).expect(200);
  await http.get('/api/auth/profil').expect(401);
  const profil = await http.get('/api/auth/profil').set('Authorization', `Bearer ${body.access_token}`).expect(200);
  expect(profil.body.email).toBe('e2e@exemple.tn');
  await http.get('/api/auth/profil').set('Authorization', `Bearer ${body.access_token}x`).expect(401);
});

Activité 2 Diagnostiquer

Un test e2e attend 400 pour un e-mail invalide et reçoit 201. Les tests unitaires du DTO passent. Donnez deux causes possibles.

Voir le corrigé

(1) L'application de test n'a pas de ValidationPipe: configurerApp n'est pas appelé (piège de la leçon). (2) Le pipe est là mais le DTO n'est pas une classe (une interface ou un type: rien à valider), ou le paramètre est typé any. Dans les deux cas, le test e2e a joué son rôle : il a trouvé un écart que les tests unitaires ne pouvaient pas voir.

Activité 3 Des tests indépendants

Réorganisez les tests e2e de la leçon pour qu'ils ne dépendent plus de leur ordre : chaque test crée ses propres données. Comment réinitialiser le service en mémoire entre deux tests ?

Voir le corrigé

Créer l'application dans beforeEach (et la fermer dans afterEach) : chaque test repart d'un service vide. C'est plus lent, mais chaque test est autonome. Avec une base de données, on vide plutôt les tables dans beforeEach (TRUNCATE ou repository.clear()) en gardant une seule application. Dans le test du 409, on crée d'abord le stagiaire, puis on tente le doublon.

Activité 4 Vérifier les en-têtes

Ajoutez un test qui vérifie que GET /api/stagiaires renvoie Content-Type: application/json, et, pour l'API du chapitre 09 qui ajoute un en-tête x-duree-ms, que cet en-tête est présent et numérique.

Voir le corrigé
it('en-têtes', () =>
  http.get('/api/stagiaires')
    .expect('Content-Type', /application\/json/)
    .expect((res) => expect(Number(res.headers['x-duree-ms'])).not.toBeNaN()));

À retenir

  • Test.createTestingModule({ imports: [AppModule] }) puis createNestApplication() et init().
  • createNestApplication() ignore main.ts : partager configurerApp(app) (préfixe, pipes) entre main.ts et les tests.
  • request(app.getHttpServer()).post(url).set(entêtes).send(corps).expect(statut).
  • overrideProvider(Service).useValue(doublure) pour les services externes (e-mail, paiement).
  • beforeAll / afterAll avec app.close() ; base dédiée aux tests (.env.test).

Cet article vous a-t-il aidé ?