Что такое jest-dom?

Что такое jest-dom?

Jest-dom — это специализированная библиотека-расширение для Jest, одного из самых популярных фреймворков для тестирования JavaScript и React-приложений. Её основная цель — предоставить набор пользовательских сопоставителей (custom matchers), которые позволяют писать более выразительные, читабельные и удобные тесты для DOM (Document Object Model). Эти матчеры существенно упрощают проверку состояния и содержимого веб-интерфейсов, делая код тестов ближе к естественному языку.

Проект является частью экосистемы Testing Library и официально называется @testing-library/jest-dom. Его можно рассматривать как «мост» между утилитарными методами @testing-library/dom (такими как getByRole, getByText) и механизмом утверждений (assertions) Jest.

Ключевые возможности и преимущества

Библиотека добавляет в Jest десятки специализированных матчеров, которые покрывают наиболее частые сценарии тестирования UI:

• Проверка видимости и доступности элементов:

  expect(element).toBeVisible();
  expect(element).toBeInTheDocument();
  expect(element).toHaveFocus();
  

• Проверка атрибутов, классов и стилей:

  expect(input).toHaveAttribute('type', 'checkbox');
  expect(button).toHaveClass('btn--primary');
  expect(div).toHaveStyle('display: none;');
  

• Проверка содержимого и форм:

  expect(element).toHaveTextContent('Hello, World!');
  expect(textarea).toHaveValue('Default text');
  expect(form).toHaveFormValues({ username: 'john', rememberMe: true });
  

• Валидация структуры и состояния:

  expect(element).toBeEmptyDOMElement();
  expect(element).toBeDisabled();
  expect(element).toBeRequired();
  expect(checkbox).toBeChecked();
  

Как это работает на практике

Без jest-dom проверки часто выглядят громоздко и требуют ручного доступа к свойствам DOM:

// Без jest-dom
expect(element).not.toBeNull();
expect(element.textContent).toBe('Submit');
expect(element.hasAttribute('disabled')).toBe(true);

С использованием jest-dom тесты становятся гораздо более декларативными и устойчивыми к изменениям в коде:

// С jest-dom
import '@testing-library/jest-dom';

test('кнопка должна быть в документе, содержать текст "Submit" и быть disabled', () => {
    render(<Button disabled>Submit</Button>);
    const button = screen.getByRole('button', { name: /submit/i });

    expect(button).toBeInTheDocument();
    expect(button).toHaveTextContent('Submit');
    expect(button).toBeDisabled();
});

Установка и настройка

Установка выполняется через npm или yarn:

npm install --save-dev @testing-library/jest-dom

Затем матчеры нужно добавить в конфигурацию Jest. Самый распространённый способ — импортировать библиотеку в специальный setup-файл (например, src/setupTests.js), на который указывает конфигурация Jest:

// jest.config.js
module.exports = {
  setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
};

// src/setupTests.js
import '@testing-library/jest-dom';

Философия и принципы

jest-dom неразрывно связан с философией Testing Library, которая гласит: «Тестируйте приложение так, как его использует пользователь». Это означает:

1. Фокус на поведении, а не реализации. Матчеры проверяют что видит пользователь (toBeVisible, toHaveTextContent), а не внутреннее состояние компонента.
2. Поощрение доступности (accessibility). Использование селекторов по роли (getByRole) в связке с этими матчерами автоматически стимулирует разработку доступных интерфейсов.
3. Улучшение читаемости и поддержки тестов. Тесты, написанные с помощью этих матчеров, читаются как техническое задание или список требований, что облегчает их понимание и рефакторинг.

Пример комплексного теста

Рассмотрим тест для простой формы входа:

import { render, screen, fireEvent } from '@testing-library/react';
import '@testing-library/jest-dom';
import LoginForm from './LoginForm';

test('форма логина валидирует ввод и показывает ошибку', async () => {
  render(<LoginForm />);

  // Находим элементы по их доступным ролям и labels
  const emailInput = screen.getByLabelText(/email/i);
  const submitButton = screen.getByRole('button', { name: /войти/i });

  // 1. Проверяем начальное состояние
  expect(emailInput).toBeEnabled();
  expect(submitButton).toBeEnabled();

  // 2. Симулируем некорректный ввод
  fireEvent.change(emailInput, { target: { value: 'invalid-email' } });
  fireEvent.click(submitButton);

  // 3. Ожидаем появление сообщения об ошибке
  const errorMessage = await screen.findByRole('alert');
  expect(errorMessage).toBeVisible();
  expect(errorMessage).toHaveTextContent(/неверный email/i);
  expect(emailInput).toHaveAttribute('aria-invalid', 'true');

  // 4. Исправляем ввод и проверяем успешный сценарий
  fireEvent.change(emailInput, { target: { value: 'valid@example.com' } });
  fireEvent.click(submitButton);
  expect(errorMessage).not.toBeInTheDocument();
});

Итог

Jest-dom (@testing-library/jest-dom) — это не просто набор удобных синтаксических «сахаров» для Jest. Это важная часть современной культуры тестирования фронтенд-приложений, которая помогает писать более надёжные, понятные и ориентированные на пользователя тесты. Она сокращает количество шаблонного кода, снижает вероятность ошибок в самих тестах и способствует созданию более доступных интерфейсов. Для любого разработчика, работающего с React и Testing Library, освоение jest-dom является обязательным шагом на пути к профессиональному тестированию UI.