Тестовые утилиты

MDX сочетает возможности Markdown и JSX, позволяя включать компоненты React прямо в Markdown-файлы. Для обеспечения качества кода и корректной работы контента необходимо использовать специализированные тестовые утилиты. В экосистеме JavaScript наиболее популярными инструментами являются Jest, Testing Library и Storybook вместе с интеграцией MDX.

Настройка окружения для тестирования MDX

Для тестирования MDX-файлов требуется корректная конфигурация сборщика (например, Webpack или Vite) и трансформеров для Jest. Основные шаги:

  1. Установка зависимостей:
npm install --save-dev jest @testing-library/react @testing-library/jest-dom @mdx-js/react @babel/preset-react babel-jest
  1. Конфигурация Babel для Jest:
{
  "presets": ["@babel/preset-env", "@babel/preset-react"]
}
  1. Трансформация MDX для Jest:

Jest не понимает MDX-файлы по умолчанию. Для этого используют jest-transform-stub или собственный трансформер:

// jest.config.js
module.exports = {
  transform: {
    "^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx",
    "^.+\\.[jt]sx?$": "babel-jest"
  },
  moduleFileExtensions: ["js", "jsx", "ts", "tsx", "mdx"]
};

Основные подходы к тестированию MDX-компонентов

1. Тестирование рендеринга контента

MDX-файл в результате компиляции превращается в React-компонент. Это позволяет использовать стандартные инструменты Testing Library для проверки:

import { render, screen } from '@testing-library/react';
import MyDocument from './example.mdx';

test('рендерит заголовок и параграф', () => {
  render(<MyDocument />);
  expect(screen.getByText('Пример заголовка')).toBeInTheDocument();
  expect(screen.getByText('Это текстовый параграф.')).toBeInTheDocument();
});

Ключевые моменты:

  • Проверка наличия текста с помощью getByText.
  • Проверка атрибутов HTML через getByRole или querySelector.

2. Тестирование кастомных MDX-компонентов

MDX позволяет использовать React-компоненты внутри Markdown. Для тестирования можно передавать кастомные компоненты через MDXProvider:

import { MDXProvider } from '@mdx-js/react';
import { render, screen } from '@testing-library/react';
import MyDocument from './example.mdx';

const components = {
  h1: ({ children }) => <h1 style={{ color: 'red' }}>{children}</h1>
};

test('применяет кастомный компонент к заголовку', () => {
  render(
    <MDXProvider components={components}>
      <MyDocument />
    </MDXProvider>
  );
  const header = screen.getByText('Пример заголовка');
  expect(header).toHaveStyle('color: red');
});

Это позволяет контролировать внешний вид и поведение MDX-компонентов на уровне тестов.

3. Интеграция с Jest snapshots

MDX-компоненты удобно проверять через snapshot-тестирование. Это позволяет фиксировать структуру DOM и быстро обнаруживать изменения:

import { render } from '@testing-library/react';
import MyDocument from './example.mdx';

test('snapshot MDX документа', () => {
  const { container } = render(<MyDocument />);
  expect(container).toMatchSnapshot();
});

Особенности:

  • Snapshots сохраняют структуру DOM.
  • Полезны для проверки документации и статических страниц.

Тестирование интерактивных элементов

MDX-файлы могут содержать интерактивные компоненты, такие как кнопки и формы. В этом случае тестирование аналогично обычным React-компонентам:

import { render, screen, fireEvent } from '@testing-library/react';
import InteractiveMDX from './interactive.mdx';

test('обрабатывает клик по кнопке', () => {
  render(<InteractiveMDX />);
  const button = screen.getByText('Нажми меня');
  fireEvent.click(button);
  expect(screen.getByText('Кнопка нажата')).toBeInTheDocument();
});

Преимущества:

  • Возможность тестировать реактивное поведение MDX.
  • Проверка взаимодействий на уровне компонентов, а не только текста.

Полезные утилиты и библиотеки

  • @testing-library/react — для рендеринга MDX-компонентов и поиска элементов по тексту, ролям и атрибутам.
  • @testing-library/jest-dom — расширяет возможности Jest для проверки DOM-элементов.
  • @mdx-js/react — позволяет оборачивать MDX-компоненты и подменять стандартные теги.
  • Storybook + Storyshots — интеграция для snapshot-тестов MDX-документации.

Практические рекомендации

  • Всегда использовать MDXProvider для передачи кастомных компонентов в тестах.
  • Для больших MDX-документов разбивать тесты на логические блоки (например, заголовки, параграфы, интерактивные элементы).
  • Snapshot-тесты лучше комбинировать с конкретными проверками через Testing Library, чтобы обнаруживать изменения и в структуре, и в содержании.
  • Обновление snapshots следует выполнять только после внимательной проверки изменений, чтобы не пропустить ошибки контента.

Тестовые утилиты позволяют не только проверять корректность MDX-документов, но и гарантировать, что интеграция с React-компонентами сохраняет ожидаемое поведение при изменениях кода. Это особенно важно для проектов с динамическими документациями и образовательными платформами, где MDX часто используется для форматирования сложного контента.

Оглавление