Kurs NestJS · Moduł 7: Testowanie

PROJEKT - kompleksowe testowanie systemu legionów

5 min czytania ·
W tej lekcji7

Przez cały moduł pisaliśmy testy pojedynczo: tu test serwisu, tam test kontrolera, gdzie indziej test przez HTTP. Projekt jest miejscem, w którym mają stać się zestawem - takim, który ktoś uruchomi za pół roku i uwierzy w jego wynik.

Twoim zadaniem jest pokrycie testami systemu zarządzania legionami: legiony i kohorty, przypisywanie legionistów, planowanie wypraw, śledzenie tributów.

Trzy poziomy, trzy pytania

Zanim napiszesz pierwszy plik, ustal, na jakie pytanie odpowiada każdy poziom:

  • Test jednostkowy - czy ta metoda liczy poprawnie, gdy wszystko dookoła jest zamockowane?
  • Test integracyjny - czy moduły dogadują się między sobą, z prawdziwym kontenerem zależności?
  • Test E2E - czy pełna ścieżka użytkownika działa przez HTTP, od żądania do odpowiedzi?

Każdy poziom kosztuje inaczej. Jednostkowych pisz najwięcej, bo są tanie i wskazują palcem winowajcę; E2E najmniej, bo są wolne, a gdy padają, mówią tylko „coś jest nie tak".

Given-When-Then

Każdy test, niezależnie od poziomu, ma tę samą trójdzielną budowę. Given to warunki wstępne, When to akcja, Then to oczekiwany wynik:

it('should create a legion with the given name', async () => {
  // Given - warunki wstępne
  const dto = { name: 'Legio X Equestris', maxSoldiers: 5000 };
  mockRepository.save.mockResolvedValue({ id: 1, ...dto });

  // When - akcja
  const result = await service.create(dto);

  // Then - oczekiwany wynik
  expect(result.id).toBe(1);
  expect(mockRepository.save).toHaveBeenCalledWith(dto);
});

Nie myl tego podziału z trzema poziomami testów - Given nie oznacza testu jednostkowego, a Then testu E2E. Nie chodzi też o rodzaje atrap: mock, spy i stub to narzędzia, których używasz w części Given. Ani o warstwy HTTP: dane, żądanie i kod odpowiedzi są tylko jednym z możliwych wypełnień tego szkieletu.

Wartość wzorca jest praktyczna. Gdy w teście brakuje wyraźnego When, zwykle znaczy to, że test sprawdza dwie akcje naraz - i przy porażce nie będziesz wiedzieć, która zawiodła.

Dwie zasady, które decydują o wiarygodności

Testy muszą być niezależne od siebie i izolowane. To pierwsza zasada testowania jednostkowego i jedyna, której złamanie psuje cały zestaw naraz.

Testy dzielące stan przechodzą w kolejności, w jakiej je napisano, a padają po zmianie kolejności, po uruchomieniu równoległym albo po dopisaniu jednego testu w środku pliku. Najgorsze, że wyglądają wtedy na wykrywające błąd - a wykrywają tylko własne powiązanie.

Dwa nieporozumienia warto od razu odsunąć. Nazwy testów mają być długie i opisowe, nie jak najkrótsze: nazwa testu jest komunikatem błędu, który zobaczysz na czerwonym tle w CI, i t1 nie powie ci wtedy nic. Testować trzeba też przypadki brzegowe (edge cases), nie tylko ścieżkę pozytywną (happy path) - bo błędy mieszkają dokładnie tam, gdzie nikt nie zaglądał: pusta lista, wartość zero, znak specjalny w nazwie.

Hooki i mockowanie zależności

Izolację zapewniają hooki, a ich kolejność wykonania jest stała: beforeAll() → beforeEach() → test/it() → afterAll():

describe('LegionsController', () => {
  let controller: LegionsController;
  let module: TestingModule;

  const mockLegionsService = {
    findAll: jest.fn(),
    create: jest.fn(),
  };

  beforeAll(async () => {
    module = await Test.createTestingModule({
      controllers: [LegionsController],
      providers: [{ provide: LegionsService, useValue: mockLegionsService }],
    }).compile();

    controller = module.get(LegionsController);
  });

  beforeEach(() => {
    jest.clearAllMocks();
  });

  afterAll(async () => {
    await module.close();
  });
});

Podział pracy między hookami wynika wprost z ich kolejności. beforeAll wykonuje się raz - tu buduje się kosztowny moduł testowy. beforeEach wykonuje się przed każdym testem i to on realizuje zasadę izolacji: jest.clearAllMocks() kasuje historię wywołań, żeby test nie widział śladów po poprzedniku. afterAll sprząta na końcu - zamyka moduł, połączenia, otwarte uchwyty.

Zwróć uwagę na zapis atrapy w providers. Kolejność jest zawsze ta sama: { provide: otwiera obiekt, LegionsService, wskazuje token do podmiany, useValue: zapowiada wartość, a mockLegionsService } ją podaje. Czyta się to jak zdanie: „w miejsce LegionsService użyj tej oto wartości".

Samo mockowanie repozytorium sprowadza się do jednej linijki na przypadek: mockRepository.save.mockResolvedValue(expectedResult) sprawia, że metoda zwróci gotowy wynik zamiast dotykać bazy. Do sprawdzenia ścieżki błędu użyjesz mockRejectedValue.

Test E2E

Na najwyższym poziomie mówisz do aplikacji tak, jak zrobi to klient - przez HTTP, biblioteką supertest:

it('GET /legions returns all legions', async () => {
  const response = await request(app.getHttpServer())
    .get('/legions')
    .expect(200)
    .expect((res) => expect(res.body).toHaveLength(3));
});

it('POST /legions rejects a body without a name', async () => {
  await request(app.getHttpServer())
    .post('/legions')
    .send({ maxSoldiers: 5000 })
    .expect(400);
});

Asercja składa się z czterech ogniw w stałej kolejności: const response = await request(app.getHttpServer()) otwiera żądanie do działającej aplikacji, .get('/legions') wskazuje metodę i ścieżkę, .expect(200) sprawdza kod odpowiedzi, a .expect(res => expect(res.body).toHaveLength(3)) zagląda do jej treści.

Drugi test pokazuje rzecz, o której łatwo zapomnieć: sprawdzaj też odrzucenia. Żądanie bez wymaganego pola musi dostać 400, i to jedyny sposób, by upewnić się, że ValidationPipe jest naprawdę podpięty w konfiguracji testowej, a nie tylko w main.ts.

Gdy test nie przechodzi

Czerwony test debuguje się w czterech krokach, zawsze w tej kolejności:

  1. Przeczytaj komunikat błędu i stack trace. Jest w nim zwykle wszystko: czego oczekiwano, co otrzymano, i w której linii.
  2. Zidentyfikuj, która asercja zawiodła. Przy kilku expect w jednym teście to nie jest oczywiste - stąd zalecenie, by testów nie przeciążać.
  3. Sprawdź dane wejściowe i mocki. Najczęstsza przyczyna nie leży w kodzie, tylko w atrapie, która zwraca co innego, niż myślisz - albo pamięta wywołanie z poprzedniego testu.
  4. Napraw test albo testowany kod. Dopiero teraz, gdy wiadomo, co jest zepsute.

Kolejność ma znaczenie, bo naturalny odruch - zacząć od czwartego kroku i poprawiać kod na wyczucie - kończy się zmianą działającej implementacji pod błędny test.

Co oddajesz

Projekt jest gotowy, gdy zawiera:

  1. Testy jednostkowe serwisów z zamockowanymi repozytoriami, pokrywające także ścieżki błędów.
  2. Testy integracyjne sprawdzające współpracę modułów na prawdziwym TestingModule.
  3. Testy E2E dla kluczowych ścieżek, z asercjami na kodzie odpowiedzi i na treści.
  4. Osobne bloki describe dla każdego poziomu, tak by dało się je uruchamiać niezależnie.
  5. Raport pokrycia z uzasadnieniem tego, czego świadomie nie pokryłeś.

Na koniec wykonaj próbę, która sprawdza cały zestaw naraz: uruchom testy w losowej kolejności (jest --randomize). Jeśli którykolwiek padnie, masz gdzieś współdzielony stan - a zestaw, który przechodzi tylko w jednej kolejności, nie mówi prawdy o kodzie.

Prześlij link do repozytorium, gdy skończysz.

Kod do tej lekcji: src/legion-test-project.spec.ts
// PROJEKT: Kompleksowe Testowanie Systemu Zarzadzania Legion
import { Test, TestingModule } from '@nestjs/testing';
import { Injectable, NotFoundException } from '@nestjs/common';

// === SERWISY DO PRZETESTOWANIA ===

@Injectable()
class CohortService {
  private cohorts = new Map<string, any>();

  create(data: { name: string; type: string; garrison: number }) {
    if (!data.name || !data.type) {
      throw new Error('Name and type are required');
    }
    const id = `cohort-${Date.now()}`;
    const cohort = { id, ...data, status: 'docked' };
    this.cohorts.set(id, cohort);
    return cohort;
  }

  findOne(id: string) {
    const cohort = this.cohorts.get(id);
    if (!cohort) throw new NotFoundException(`Cohort ${id} not found`);
    return cohort;
  }

  findAll() { return Array.from(this.cohorts.values()); }

  deploy(id: string) {
    const cohort = this.findOne(id);
    cohort.status = 'deployed';
    return cohort;
  }
}

@Injectable()
class LegionService {
  constructor(private cohortService: CohortService) {}

  getLegionStrength() {
    const cohorts = this.cohortService.findAll();
    return {
      total: cohorts.length,
      deployed: cohorts.filter(s => s.status === 'deployed').length,
      docked: cohorts.filter(s => s.status === 'docked').length,
      totalGarrison: cohorts.reduce((sum, s) => sum + s.garrison, 0),
    };
  }

  deployLegion() {
    const cohorts = this.cohortService.findAll();
    return cohorts.map(s => this.cohortService.deploy(s.id));
  }
}

// === TESTY ===

describe('Legion Management - Complete Test Suite', () => {
  // UNIT TESTS
  describe('CohortService - Unit Tests', () => {
    let service: CohortService;
    beforeEach(() => { service = new CohortService(); });

    it('should create a cohort', () => {
      const cohort = service.create({
        name: 'Trireme Roma', type: 'warcohort', garrison: 200,
      });
      expect(cohort.id).toBeDefined();
      expect(cohort.status).toBe('docked');
    });

    it('should throw on invalid data', () => {
      expect(() => service.create({
        name: '', type: '', garrison: 0,
      })).toThrow('Name and type are required');
    });

    it('should throw NotFoundException', () => {
      expect(() => service.findOne('unknown')).toThrow(NotFoundException);
    });

    it('should deploy a cohort', () => {
      const cohort = service.create({
        name: 'Corvus', type: 'warcohort', garrison: 150,
      });
      const deployed = service.deploy(cohort.id);
      expect(deployed.status).toBe('deployed');
    });
  });

  // INTEGRATION TESTS
  describe('LegionService - Integration', () => {
    let legionService: LegionService;
    let cohortService: CohortService;

    beforeEach(async () => {
      const module: TestingModule = await Test.createTestingModule({
        providers: [LegionService, CohortService],
      }).compile();
      legionService = module.get(LegionService);
      cohortService = module.get(CohortService);
    });

    it('should calculate legion strength', () => {
      cohortService.create({ name: 'S1', type: 'war', garrison: 200 });
      cohortService.create({ name: 'S2', type: 'war', garrison: 150 });
      const strength = legionService.getLegionStrength();
      expect(strength.total).toBe(2);
      expect(strength.totalGarrison).toBe(350);
    });

    it('should deploy entire legion', () => {
      cohortService.create({ name: 'S1', type: 'war', garrison: 200 });
      cohortService.create({ name: 'S2', type: 'war', garrison: 150 });
      const deployed = legionService.deployLegion();
      expect(deployed.every(s => s.status === 'deployed')).toBe(true);
    });
  });
});

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Wzorzec Given-When-Then w testach oznacza:

  2. 2. Która z poniższych zasad jest kluczowa przy pisaniu testów jednostkowych?

Zadania praktyczne w grze

  • Edytor kodu

    Przetestuj czy kontroler odrzuca niepoprawne dane wejściowe

  • Edytor kodu

    Napisz test metody create() z zamockowanym repository.save()

  • Klikanie w kolejności

    Ułóż kolejność wykonywania hooków w pliku testowym:

  • Układanie w pionie

    Ułóż asercję sprawdzającą odpowiedź HTTP w teście E2E:

  • Układanie w pionie

    Uporządkuj kroki debugowania niezdanego testu:

  • Układanie w poziomie

    Ułóż konfigurację mock providera w TestingModule:

  • Edytor kodu

    Napisz pełen zestaw testów obejmujący kontroler, serwis i endpoint HTTP

  1. PytanieWzorzec Given-When-Then
  2. Zadanie z kodemPraktyka: Test walidacji DTO
  3. PytanieProces code review testów
  4. Zadanie z kodemPraktyka: Test z mockiem bazy danych
  5. Kliknij w kolejnościSortowanie: Test lifecycle hooks
  6. Ułóż w kolejnościSortowanie poziome: expect chain
  7. Ułóż w kolejnościSortowanie pionowe: Debugging failed test
  8. Ułóż w kolejnościSortowanie poziome: Mock provider config
  9. Zadanie z kodemPraktyka: Kompletny system testów

Przydatne artykuły