Kurs NestJS · Moduł 7: Testowanie
PROJEKT - kompleksowe testowanie systemu legionów
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:
- Przeczytaj komunikat błędu i stack trace. Jest w nim zwykle wszystko: czego oczekiwano, co otrzymano, i w której linii.
- Zidentyfikuj, która asercja zawiodła. Przy kilku
expectw jednym teście to nie jest oczywiste - stąd zalecenie, by testów nie przeciążać. - 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.
- 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:
- Testy jednostkowe serwisów z zamockowanymi repozytoriami, pokrywające także ścieżki błędów.
- Testy integracyjne sprawdzające współpracę modułów na prawdziwym
TestingModule. - Testy E2E dla kluczowych ścieżek, z asercjami na kodzie odpowiedzi i na treści.
- Osobne bloki
describedla każdego poziomu, tak by dało się je uruchamiać niezależnie. - 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. Wzorzec Given-When-Then w testach oznacza:
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
Zadania po tej lekcji
- PytanieWzorzec Given-When-Then
- Zadanie z kodemPraktyka: Test walidacji DTO
- PytanieProces code review testów
- Zadanie z kodemPraktyka: Test z mockiem bazy danych
- Kliknij w kolejnościSortowanie: Test lifecycle hooks
- Ułóż w kolejnościSortowanie poziome: expect chain
- Ułóż w kolejnościSortowanie pionowe: Debugging failed test
- Ułóż w kolejnościSortowanie poziome: Mock provider config
- Zadanie z kodemPraktyka: Kompletny system testów