re:re:actable
Урок 023 минуты чтения

Утверждения: матчеры и snapshot-тесты

На этой странице
Кратко

Утверждение (assertion) — проверка expect(значение).матчер(ожидание). Главное различие: toBe сравнивает по ссылке/Object.is (примитивы), toEqual — по содержимому рекурсивно (объекты, массивы), toStrictEqual дополнительно учитывает undefined-поля и классы. Для частичных проверок есть toMatchObject и асимметричные матчеры (expect.any(String), expect.objectContaining, expect.stringMatching), которые позволяют не фиксировать нестабильные значения вроде id и дат. Для DOM — матчеры jest-dom (toBeInTheDocument, toBeVisible, toBeDisabled, toHaveValue, toHaveAccessibleName). Ошибки проверяют через toThrow и rejects.toThrow. Snapshot-тесты сохраняют вывод в файл и сравнивают при следующих запусках; они удобны для стабильного сериализуемого вывода (сгенерированный код, конфиги, сообщения об ошибках), но большие снимки DOM — анти-паттерн: их не читают на ревью и обновляют не глядя. Предпочитай маленькие inline-снимки и явные утверждения.

Вопрос

Какие матчеры есть в Vitest и чем toBe отличается от toEqual? Когда уместны snapshot-тесты?

Базовые матчеры

expect(2 + 2).toBe(4);                              // Object.is
expect({ a: 1 }).toEqual({ a: 1 });                 // глубокое сравнение
expect({ a: 1, b: undefined }).toEqual({ a: 1 });   // ✓ toEqual игнорирует undefined-поля
expect({ a: 1, b: undefined }).not.toStrictEqual({ a: 1 }); // toStrictEqual — нет
 
expect(user).toMatchObject({ name: "Анна", role: "admin" }); // подмножество полей
expect(list).toHaveLength(3);
expect(list).toContain("apple");                    // элемент массива / подстрока
expect(list).toContainEqual({ id: 1 });             // объект в массиве по значению
expect(value).toBeNull();
expect(value).toBeDefined();
expect(value).toBeTruthy();                         // осторожно: слабая проверка
expect(0.1 + 0.2).toBeCloseTo(0.3);                 // дробные числа
expect(price).toBeGreaterThan(0);
expect("Ошибка: нет связи").toMatch(/нет связи/);

Асимметричные матчеры

expect(createdOrder).toEqual({
  id: expect.any(String),                           // id генерируется — проверяем только тип
  status: "pending",
  createdAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
  items: expect.arrayContaining([expect.objectContaining({ sku: "A1" })]),
  meta: expect.anything(),                          // что угодно, кроме null/undefined
});
 
expect(onSubmit).toHaveBeenCalledWith(expect.objectContaining({ email: "a@b.ru" }));

Ошибки и промисы

expect(() => parseAmount("abc")).toThrow("Некорректная сумма");
expect(() => parseAmount("abc")).toThrow(ValidationError);
 
await expect(api.getOrder("404")).rejects.toThrow(NotFoundError);
await expect(api.getOrder("1")).resolves.toMatchObject({ id: "1" });
// ⚠️ без await утверждение не дождётся результата и тест пройдёт всегда

Матчеры для моков

expect(fn).toHaveBeenCalled();
expect(fn).toHaveBeenCalledTimes(1);
expect(fn).toHaveBeenCalledWith("a", 1);
expect(fn).toHaveBeenLastCalledWith("b");
expect(fn).toHaveReturnedWith(42);
expect(fn).not.toHaveBeenCalled();

jest-dom: матчеры для DOM

expect(screen.getByRole("button", { name: "Оплатить" })).toBeDisabled();
expect(screen.getByLabelText("Email")).toHaveValue("a@b.ru");
expect(screen.getByRole("checkbox")).toBeChecked();
expect(screen.queryByText("Ошибка")).not.toBeInTheDocument();
expect(screen.getByRole("dialog")).toBeVisible();
expect(screen.getByRole("textbox")).toHaveFocus();
expect(screen.getByRole("textbox")).toBeInvalid();             // aria-invalid / :invalid
expect(screen.getByRole("textbox")).toHaveAccessibleDescription("Минимум 8 символов");
expect(screen.getByRole("link")).toHaveAttribute("href", "/orders/42");
expect(screen.getByRole("alert")).toHaveTextContent(/не удалось/i);

Используй самый конкретный матчер: при падении toBeDisabled() скажет «элемент не disabled», а expect(btn.disabled).toBe(true) — только «expected false to be true».

Мягкие утверждения и сообщения

expect.soft(total).toBe(100);          // тест продолжится, все провалы покажутся в конце
expect(total, "сумма с учётом доставки").toBe(100); // своё сообщение при падении
expect.assertions(2);                  // в тесте должно выполниться ровно 2 утверждения

Snapshot-тесты

// Внешний файл __snapshots__/x.test.ts.snap
expect(generateSitemap(routes)).toMatchSnapshot();
 
// Inline — снимок прямо в тесте, виден на ревью
expect(formatError(err)).toMatchInlineSnapshot(`"Сервер недоступен (503). Повторите позже."`);
 
// Обновить снимки после осознанного изменения
// vitest -u
✓ Уместно✗ Анти-паттерн
Небольшой стабильный вывод: текст ошибки, сериализованный конфиг, сгенерированный кодСнимок всего DOM страницы на 500 строк
Inline-снимок, который читается на ревьюСнимки с датами, id, случайными значениями
Проверка, что вывод не изменился неожиданноЗамена осмысленных утверждений «на всякий случай»
vitest -u без просмотра диффа

Нестабильные поля в снимках заменяют асимметричными матчерами:

expect(order).toMatchSnapshot({ id: expect.any(String), createdAt: expect.any(String) });

Что важно помнить

  • toBe — примитивы и ссылки; toEqual — содержимое; toStrictEqual — строже.
  • Асимметричные матчеры для id, дат и частичных проверок.
  • await expect(...).rejects/resolves — обязательно с await.
  • jest-dom даёт понятные сообщения для DOM-проверок.
  • Snapshot — для маленького стабильного вывода, лучше inline.

Мини-шпаргалка

  • toBe, toEqual, toMatchObject, toContainEqual, toBeCloseTo.
  • expect.any, objectContaining, arrayContaining, stringMatching.
  • toThrow, rejects.toThrow, toHaveBeenCalledWith.
  • toBeDisabled, toHaveValue, toBeVisible, toHaveAccessibleName.
  • toMatchInlineSnapshot, vitest -u.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам