Kurs JavaScript i TypeScript · Moduł 11: Testowanie z Jest

Matchery w Jest

6 min czytania ·
W tej lekcji6

Samo "czy wynik się zgadza" to często za mało. Czasem chcesz wiedzieć, czy lista gatunków zawiera raptora, czy zdrowie mieści się w normie albo czy funkcja podniosła alarm. Do każdego z tych pytań Jest ma osobne narzędzie.

Matchery to metody, które pozwalają sprawdzać wartości na różne sposoby. W kontekście Parku Jurajskiego - to różne typy sensorów, z których każdy wykrywa inny rodzaj zagrożenia. Dopisujesz je po kropce za expect(...), a zasada wyboru jest prosta: bierz najbardziej precyzyjny czujnik, bo wtedy Jest wypisze najczytelniejszy komunikat błędu.

Podstawowe matchery porównujące

toBe - ścisłe porównanie (===)

toBe używa ścisłego porównania. Sprawdza identyczność - idealny dla typów prymitywnych. Dokładniej: Jest porównuje wartości funkcją Object.is, która działa jak === z dwoma wyjątkami - NaN jest równe NaN, a 0 i -0 są rozróżniane:

test('toBe - porównanie prymitywów', () => {
  const dinoCount = 15;
  expect(dinoCount).toBe(15);      // liczba

  const species = 'T-Rex';
  expect(species).toBe('T-Rex');    // string

  const isAlive = true;
  expect(isAlive).toBe(true);       // boolean
});

Każda z trzech asercji porównuje prymityw: liczbę, tekst i wartość logiczną. Dla nich liczy się wyłącznie sama wartość, więc toBe jest tu najprostszym wyborem.

toEqual - porównanie strukturalne

toEqual sprawdza równość strukturalną obiektów. Porównuje zawartość, nie referencje. To ważne, bo dwa obiekty o identycznej treści to dwa osobne okazy w pamięci, więc dla toBe zawsze będą różne:

test('toEqual - porównanie obiektów', () => {
  const dino1 = { name: 'Rex', species: 'T-Rex' };
  const dino2 = { name: 'Rex', species: 'T-Rex' };

  // toBe FAIL - różne referencje (obiekty w pamięci)
  // expect(dino1).toBe(dino2); // To nie zadziała!

  // toEqual PASS - ta sama zawartość
  expect(dino1).toEqual(dino2); // To zadziała!

  // Działa też z zagnieżdżonymi obiektami
  const enclosure = {
    name: 'Zone A',
    dinosaurs: [
      { name: 'Rex', diet: 'carnivore' }
    ]
  };

  expect(enclosure).toEqual({
    name: 'Zone A',
    dinosaurs: [
      { name: 'Rex', diet: 'carnivore' }
    ]
  });
});

toEqual schodzi rekurencyjnie w głąb zagnieżdżonych obiektów i tablic, pole po polu. Jest przy tym pobłażliwy: ignoruje pola o wartości undefined i nie sprawdza, czy obiekt jest instancją tej samej klasy. Gdy te szczegóły mają znaczenie, użyj toStrictEqual - ja sięgam po niego zawsze, gdy nie mam powodu do pobłażliwości.

Matchery dla tablic i stringów

toContain - czy zawiera element?

Gdy nie interesuje Cię cała lista, tylko obecność jednego okazu, użyj toContain. Działa zarówno z tablicami, jak i ze stringami:

test('toContain - sprawdzanie zawartości', () => {
  const dinosaurs = ['T-Rex', 'Velociraptor', 'Triceratops'];

  expect(dinosaurs).toContain('T-Rex');
  expect(dinosaurs).toContain('Velociraptor');

  // Dla stringów
  const report = 'Dinozaur T-Rex w strefie A';
  expect(report).toContain('T-Rex');
  expect(report).toContain('strefie A');
});

Dla tablicy toContain sprawdza, czy któryś element jest ściśle równy szukanemu, a dla stringa, czy zawiera podany fragment. Uwaga na obiekty: toContain porównuje referencje, więc do szukania obiektu po zawartości służy toContainEqual.

toHaveLength - sprawdzanie długości

Liczba okazów na wybiegu to kolejne częste pytanie. toHaveLength sprawdza właściwość length, więc zadziała z tablicami i ze stringami:

test('toHaveLength - sprawdzanie ilości', () => {
  const carnivores = ['T-Rex', 'Velociraptor', 'Spinosaurus'];
  expect(carnivores).toHaveLength(3);

  const emptyEnclosure = [];
  expect(emptyEnclosure).toHaveLength(0);

  // Działa też ze stringami
  const code = 'DINO-001';
  expect(code).toHaveLength(8);
});

Zapis expect(carnivores).toHaveLength(3) daje ten sam wynik co expect(carnivores.length).toBe(3), ale przy porażce Jest pokaże całą tablicę, a nie tylko liczbę. Pusta tablica ma długość 0 i to również poprawne sprawdzenie.

Matchery dla wartości prawdziwych/fałszywych

toBeTruthy i toBeFalsy

W JavaScripcie każda wartość w warunku if zamienia się na true albo false. toBeTruthy i toBeFalsy sprawdzają właśnie wynik tej konwersji, a nie konkretną wartość:

test('sprawdzanie prawdziwości', () => {
  // Truthy values
  expect(1).toBeTruthy();
  expect('text').toBeTruthy();
  expect([]).toBeTruthy();      // pusta tablica jest truthy!
  expect({}).toBeTruthy();      // pusty obiekt jest truthy!

  // Falsy values
  expect(0).toBeFalsy();
  expect('').toBeFalsy();
  expect(null).toBeFalsy();
  expect(undefined).toBeFalsy();
  expect(false).toBeFalsy();
});

Pułapka czyha w pierwszej grupie: pusta tablica i pusty obiekt są truthy. Jeśli chcesz sprawdzić, że wybieg jest pusty, toBeFalsy nie pomoże - użyj toHaveLength(0).

toBeNull, toBeUndefined, toBeDefined

Zakładamy, że getDinosaur zwraca obiekt dinozaura albo null, gdy okazu nie ma w rejestrze. Trzy matchery rozróżniają trzy różne stany braku wartości:

test('sprawdzanie null i undefined', () => {
  const activeDino = getDinosaur('Rex-001');
  const extinctDino = getDinosaur('Unknown');

  expect(activeDino).toBeDefined();
  expect(activeDino).not.toBeNull();

  expect(extinctDino).toBeNull();
  expect(extinctDino).toBeDefined(); // null jest defined!

  let uninitializedDino;
  expect(uninitializedDino).toBeUndefined();
});

toBeDefined oznacza tylko "różne od undefined", dlatego null przechodzi ten test. Jeśli chcesz wykluczyć oba puste stany naraz, sprawdź konkretną wartość, zamiast polegać na toBeDefined.

Matchery liczbowe

Czujniki parku zwracają liczby: zdrowie, napięcie ogrodzenia, temperaturę inkubatora. Do porównań służą matchery, których nazwy czyta się jak zwykłe zdania po angielsku:

test('porównania liczbowe', () => {
  const health = 85;

  expect(health).toBeGreaterThan(80);
  expect(health).toBeGreaterThanOrEqual(85);
  expect(health).toBeLessThan(100);
  expect(health).toBeLessThanOrEqual(85);

  // Dla liczb zmiennoprzecinkowych - NIE używaj toBe!
  expect(0.1 + 0.2).toBeCloseTo(0.3);
});

Ostatnia linia to ważna lekcja o liczbach zmiennoprzecinkowych: 0.1 + 0.2 daje w JavaScripcie 0.30000000000000004, więc toBe(0.3) by nie przeszło. toBeCloseTo domyślnie porównuje z dokładnością do dwóch miejsc po przecinku.

Testowanie wyjątków - toThrow

toThrow sprawdza, czy funkcja rzuca wyjątek. UWAGA: musisz opakować wywołanie w funkcję! Bez opakowania błąd wybuchnie, zanim expect zdąży go złapać. W przykładzie releaseDinosaur wypuszcza okaz tylko przy odpowiednim poziomie zabezpieczeń:

function releaseDinosaur(dinosaur, securityLevel) {
  if (securityLevel < 5) {
    throw new Error('Poziom bezpieczeństwa za niski!');
  }
  if (dinosaur.species === 'T-Rex' && securityLevel < 9) {
    throw new Error('T-Rex wymaga poziomu bezpieczeństwa 9!');
  }
  return { released: true };
}

test('toThrow - testowanie wyjątków', () => {
  const rex = { name: 'Rex', species: 'T-Rex' };

  // POPRAWNIE - opakuj w funkcję strzałkową
  expect(() => releaseDinosaur(rex, 3)).toThrow();
  expect(() => releaseDinosaur(rex, 3)).toThrow('Poziom bezpieczeństwa za niski!');
  expect(() => releaseDinosaur(rex, 7)).toThrow('T-Rex wymaga poziomu bezpieczeństwa 9!');

  // Sprawdź, że NIE rzuca wyjątku
  expect(() => releaseDinosaur(rex, 9)).not.toThrow();
});

Argument toThrow zawęża sprawdzenie: string oznacza, że komunikat błędu musi zawierać ten fragment, wyrażenie regularne - że musi do niego pasować, a klasa błędu - że wyjątek musi być jej instancją. Polecam zawsze podawać komunikat bo samo toThrow() przepuści każdy wyjątek, także TypeError spowodowany literówką.

Modyfikator not

Każdy matcher można zanegować za pomocą .not. Przydaje się, gdy chcesz potwierdzić nieobecność, na przykład że stegozaur nie trafił na wybieg drapieżników:

test('modyfikator not', () => {
  const dinosaurs = ['T-Rex', 'Triceratops'];

  expect(dinosaurs).not.toContain('Stegosaurus');
  expect(dinosaurs.length).not.toBe(0);
  expect(dinosaurs).not.toEqual([]);

  const health = 85;
  expect(health).not.toBeLessThan(50);
});

not odwraca wynik dowolnego matchera, ale nie nadużywaj go: not.toBeLessThan(50) czyta się trudniej niż toBeGreaterThanOrEqual(50). Sięgaj po not tam, gdzie zdanie "nie zawiera" brzmi naturalnie.

W lekcji o mockowaniu poznasz matchery, które sprawdzają wywołania funkcji, a przy TypeScripcie - matchery asymetryczne, które weryfikują sam kształt obiektu. W laboratorium poniżej przetestujesz uproszczoną wersję expect z tymi samymi matcherami.

Pamiętaj: matcher to czujnik - dobierz taki, który wykrywa dokładnie to zagrożenie, którego szukasz.

Kod do tej lekcji: index.js
// Matchery w Jest - rozne typy sprawdzen
console.log("=== Park Jurajski - Sensory i Matchery ===\n");

// Mini expect z wieloma matcherami
let passed = 0, failed = 0;

function expect(actual) {
  function check(condition, msg) {
    if (condition) { passed++; console.log("  [PASS] " + msg); }
    else { failed++; console.log("  [FAIL] " + msg); }
  }

  return {
    toBe(expected) {
      check(actual === expected, `${actual} === ${expected}`);
    },
    toEqual(expected) {
      check(JSON.stringify(actual) === JSON.stringify(expected),
        `deepEqual: ${JSON.stringify(actual)}`);
    },
    toContain(item) {
      const has = Array.isArray(actual) ? actual.includes(item) : actual.includes(item);
      check(has, `contains "${item}"`);
    },
    toHaveLength(len) {
      check(actual.length === len, `length ${actual.length} === ${len}`);
    },
    toBeTruthy() {
      check(!!actual, `${actual} is truthy`);
    },
    toBeFalsy() {
      check(!actual, `${actual} is falsy`);
    },
    toBeGreaterThan(n) {
      check(actual > n, `${actual} > ${n}`);
    },
    toBeLessThan(n) {
      check(actual < n, `${actual} < ${n}`);
    },
    toBeCloseTo(expected) {
      check(Math.abs(actual - expected) < 0.01, `${actual} ~= ${expected}`);
    },
    toBeNull() {
      check(actual === null, `${actual} is null`);
    },
    toBeUndefined() {
      check(actual === undefined, `is undefined`);
    },
    toBeDefined() {
      check(actual !== undefined, `is defined`);
    },
    not: {
      toBe(expected) { check(actual !== expected, `${actual} !== ${expected}`); },
      toContain(item) {
        const has = Array.isArray(actual) ? actual.includes(item) : actual.includes(item);
        check(!has, `not contains "${item}"`);
      },
      toThrow() { /* simplified */ }
    }
  };
}

// --- toBe vs toEqual ---
console.log("--- toBe vs toEqual ---");

const dino1 = { name: "Rex", species: "T-Rex" };
const dino2 = { name: "Rex", species: "T-Rex" };

console.log("toBe porownuje referencje (===):");
console.log("  dino1 === dino2?", dino1 === dino2, "(false - rozne obiekty)");
console.log("\ntoEqual porownuje zawartosc:");
expect(dino1).toEqual(dino2);

// --- toContain ---
console.log("\n--- toContain ---");
const dinosaurs = ["T-Rex", "Velociraptor", "Triceratops"];
expect(dinosaurs).toContain("T-Rex");
expect(dinosaurs).not.toContain("Stegosaurus");

const report = "Dinozaur T-Rex w strefie A";
expect(report).toContain("T-Rex");

// --- toHaveLength ---
console.log("\n--- toHaveLength ---");
const carnivores = ["T-Rex", "Velociraptor", "Spinosaurus"];
expect(carnivores).toHaveLength(3);

// --- Truthy / Falsy ---
console.log("\n--- Truthy / Falsy ---");
expect(1).toBeTruthy();
expect("text").toBeTruthy();
expect(0).toBeFalsy();
expect("").toBeFalsy();
expect(null).toBeFalsy();

// --- Liczby ---
console.log("\n--- Porownania liczbowe ---");
const health = 85;
expect(health).toBeGreaterThan(80);
expect(health).toBeLessThan(100);
expect(0.1 + 0.2).toBeCloseTo(0.3);

// --- null / undefined ---
console.log("\n--- null / undefined ---");
expect(null).toBeNull();
expect(undefined).toBeUndefined();
expect("value").toBeDefined();

// --- toThrow ---
console.log("\n--- toThrow ---");
function releaseDinosaur(dino, level) {
  if (level < 5) throw new Error("Poziom za niski!");
  return { released: true };
}

try {
  releaseDinosaur({}, 3);
  console.log("  [FAIL] Should have thrown");
  failed++;
} catch (e) {
  console.log("  [PASS] Threw: " + e.message);
  passed++;
}

try {
  releaseDinosaur({}, 9);
  console.log("  [PASS] No throw for level 9");
  passed++;
} catch (e) {
  console.log("  [FAIL] Should not throw");
  failed++;
}

console.log(`\n=== Wyniki: ${passed} passed, ${failed} failed ===`);

Hasła z dokumentacji w tej lekcji

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. Jaka jest główna różnica między matcherami toBe i toEqual w Jest?

  2. 2. Jak poprawnie użyć matchera toThrow w Jest?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Dla każdego testu użyj właściwego matchera: toBe, toContain, toHaveLength, toBeGreaterThan, toEqual.

  • Układanie w poziomie

    Ułóż elementy asercji porównującej obiekt:

  • Edytor kodu

    Napisz testy sprawdzające zarówno pozytywne jak i negatywne warunki.

  1. PytanieRóżnica między toBe a toEqual
  2. PytanieMatcher toThrow
  3. Zadanie z kodemĆwiczenie z matcherami
  4. Ułóż w kolejnościSkładnia expect z toEqual
  5. PytanieMatcher toContain
  6. Zadanie z kodemMatcher not i negacja

Przydatne artykuły