Утверждения: матчеры и 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.