React: тестируем компоненты с помощью Jest и Testing Library

Привет, друзья!

В данном туториале я покажу вам, как тестировать компоненты на React с помощью Jest и Testing Library.

Список основных задач, которые мы решим на протяжении туториала:

1. Создание шаблона React-приложения с помощью Vite.
2. Создание компонента для получения приветствия от сервера.
3. Установка и настройка Jest.
4. Установка и настройка Testing Library.
5. Тестирование компонента с помощью Testing Library:
   
   1. Используя стандартные возможности.
   2. С помощью кастомного рендера.
   3. С помощью кастомных запросов.
6. Тестирование компонента с помощью снимков Jest.

Репозиторий с кодом проекта.

Если вам это интересно, прошу под кат.

Создание шаблона

Обратите внимание: для работы с зависимостями я буду использовать Yarn.

Vite — это продвинутый сборщик модулей (bundler) для JavaScript-приложений. Он более производительный и не менее кастомизируемый, чем Webpack.

Vite CLI позволяет создавать готовые к разработке проекты, в том числе, с помощью некоторых шаблонов.

Создаем шаблон React-приложения:

# react-testing - название проекта
# --template react - используемый шаблон
yarn vite create react-testing --template react

Переходим в созданную директорию и устанавливаем зависимости:

cd react-testing
yarn

Убедиться в работоспособности приложения можно, выполнив команду yarn dev.

Приводим структуру проекта к следующему виду:

- node_modules
- src
  - App.jsx
  - main.jsx
- .gitignore
- index.html
- package.json
- vite.config.js
- yarn.lock

{ task: 'setup project', status: 'done' }

Создание компонента

Для обращения к API мы будем использовать Axios:

yarn add axios

Создаем в директории src файл FetchGreeting.jsx следующего содержания:

import { useState } from 'react'
import axios from 'axios'

// пропом компонента является адрес конечной точки
// для получения приветствия от сервера
const FetchGreeting = ({ url }) => {
  // состояние приветствия
  const [greeting, setGreeting] = useState('')
  // состояние ошибки
  const [error, setError] = useState(null)
  // состояние нажатия кнопки
  const [btnClicked, setBtnClicked] = useState(false)

  // метод для получения приветствия от сервера
  const fetchGreeting = (url) =>
    axios
      .get(url)
      // если запрос выполнен успешно
      .then((res) => {
        const { data } = res
        const { greeting } = data
        setGreeting(greeting)
        setBtnClicked(true)
      })
      // если возникла ошибка
      .catch((e) => {
        setError(e)
      })

  // текст кнопки
  const btnText = btnClicked ? 'Готово' : 'Получить приветствие'

  return (
    <div>
      <button onClick={() => fetchGreeting(url)} disabled={btnClicked}>
        {btnText}
      </button>
      {/* если запрос выполнен успешно */}
      {greeting && <h1>{greeting}</h1>}
      {/* если возникла ошибка */}
      {error && <p role='alert'>Не удалось получить приветствие</p>}
    </div>
  )
}

export default FetchGreeting

{ task: 'create component', status: 'done' }

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

Устанавливаем Jest:

yarn add jest

По умолчанию средой для тестирования является Node.js, поэтому нам потребуется еще один пакет:

yarn add jest-environment-jsdom

Создаем в корне проекта файл jest.config.js (настройки Jest) следующего содержания:

module.exports = {
  // среда тестирования - браузер
  testEnvironment: 'jest-environment-jsdom',
}

Для транспиляции кода перед запуском тестов Jest использует Babel. Поскольку мы будем работать с JSX нам потребуется два "пресета":

yarn add @babel/preset-env @babel/preset-react

Создаем в корне проекта файл babel.config.js (настройки Babel) следующего содержания:

module.exports = {
  presets: [
    '@babel/preset-env',
    ['@babel/preset-react', { runtime: 'automatic' }]
  ]
}

Настройка runtime: 'automatic' добавляет React в глобальную область видимости, что позволяет не импортировать его явно в каждом файле.

Дефолтной директорией с тестами для Jest является __tests__. Создаем эту директорию в корне проекта.

Создаем в директории __tests__ файл fetch-greeting.test.jsx следующего содержания:

test.todo('получение приветствия')

Объекты describe, test, expect и другие импортируются в пространство модуля Jest. Почитать об этом можно здесь и здесь.

test.todo(name: string) — это своего рода заглушка для теста, который мы собираемся писать.

Добавляем в раздел scripts файла package.json команду для запуска тестов:

"test": "jest"

Выполняем эту команду с помощью yarn test:

Получаем в терминале нашу "тудушку" и сообщение об успешном выполнении "теста".

Кажется, что можно приступать к тестированию компонента. Почти, есть один нюанс.

Дело в том, что Jest спроектирован для работы с Node.js и не поддерживает ESM из коробки. Более того, поддержка ESM является экспериментальной и в будущем может претерпеть некоторые изменения. Почитать об этом можно здесь.

Для того, чтобы все работало, как ожидается, нужно сделать 2 вещи.

Можно определить в package.json тип кода как модуль ("type": "module"), но это сломает Vite. Можно изменить расширение файла с тестом на .mjs, но мне такой вариант не нравится. А можно сообщить Jest расширения файлов, которые следует обрабатывать как ESM:

// jest.config.js
module.exports = {
  testEnvironment: 'jest-environment-jsdom',
  // !
  extensionsToTreatAsEsm: ['.jsx'],
}

Также необходимо каким-то образом передать Jest флаг --experimental-vm-modules. Существует несколько способов это сделать, но наиболее подходящим с точки зрения обеспечения совместимости с разными ОС является следующий:

1. Устанавливаем cross-env с помощью yarn add cross-env.
2. Редактируем команду для запуска тестов:

"test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest"

{ task: 'setup jest', status: 'done' }

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

Устанавливаем обертку Testing Library для React:

yarn add @testing-library/react

Для обеспечения интеграции с Jest нам также потребуется следующий пакет:

yarn add @testing-library/jest-dom

Для тестирования отправки запроса на сервер и получения от него приветствия необходим фиктивный (mock) сервер. Одним из самых простых решений для этого является msw:

yarn add msw

{ task: 'setup testing library', status: 'done' }

Тестирование компонента с помощью Testing Library

Стандартные возможности

Реализуем тестирование компонента с помощью стандартных возможностей, предоставляемых Testing Library.

Начнем с импорта зависимостей:

// msw
import { rest } from 'msw'
import { setupServer } from 'msw/node'
// см. ниже
import { render, fireEvent, waitFor, screen } from '@testing-library/react'
// см. ниже
import '@testing-library/jest-dom'
// компонент
import FetchGreeting from '../src/FetchGreeting'

Создаем фиктивный сервер:

const server = setupServer(
  rest.get('/greeting', (req, res, ctx) =>
    res(ctx.json({ greeting: 'Привет!' }))
  )
)

В ответ на GET HTTP-запрос сервер будет возвращать объект с ключом greeting и значением Привет!.

Определяем глобальные хуки:

// запускаем сервер перед выполнением тестов
beforeAll(() => server.listen())
// сбрасываем обработчики к дефолтной реализации после каждого теста
afterEach(() => server.resetHandlers())
// останавливаем сервер после всех тестов
afterAll(() => server.close())

Мы напишем 2 теста:

• для получения приветствия и его рендеринга;
• для обработки ошибки сервера.

Поскольку тестируется один и тот же функционал, имеет смысл сгруппировать тесты с помощью describe:

describe('получение приветствия', () => {
  // todo
})

Начнем с теста для получения приветствия и его рендеринга:

test('-> успешное получение и отображение приветствия', async function () {
  // рендерим компонент
  // https://testing-library.com/docs/react-testing-library/api/#render
  render(<FetchGreeting url='/greeting' />)

  // имитируем нажатие кнопки для отправки запроса
  // https://testing-library.com/docs/dom-testing-library/api-events#fireevent
  //
  // screen привязывает (bind) запросы к document.body
  // https://testing-library.com/docs/queries/about/#screen
  fireEvent.click(screen.getByText('Получить приветствие'))

  // ждем рендеринга заголовка
  // https://testing-library.com/docs/dom-testing-library/api-async/#waitfor
  await waitFor(() => screen.getByRole('heading'))

  // текстом заголовка должно быть `Привет!`
  expect(screen.getByRole('heading')).toHaveTextContent('Привет!')
  // текстом кнопки должно быть `Готово`
  expect(screen.getByRole('button')).toHaveTextContent('Готово')
  // кнопка должна быть заблокированной
  expect(screen.getByRole('button')).toBeDisabled()
})

О запросах типа getByRole можно почитать здесь, а список всех стандартных запросов можно найти здесь.

О кастомных сопоставлениях (matchers), которыми @testing-library/jest-dom расширяет объект expect из Jest можно почитать здесь.

Перед тем, как приступать к реализации теста для обработки ошибки сервера установим еще один пакет:

yarn add @testing-library/user-event

Данный пакет рекомендуется использовать для имитации пользовательских событий (типа нажатия кнопки) вместо fireEvent. Почитать об этом можно здесь.

// `it` - синоним `test`
it('-> обработка ошибки сервера', async () => {
  // после этого сервер в ответ на запрос
  // будет возвращать ошибку со статус-кодом `500`
  server.use(rest.get('/greeting', (req, res, ctx) => res(ctx.status(500))))

  // рендерим компонент
  render(<FetchGreeting url='greeting' />)

  // имитируем нажатие кнопки
  // рекомендуемый подход
  // https://testing-library.com/docs/user-event/setup
  const user = userEvent.setup()
  // если не указать `await`, тогда `Testing Library`
  // не успеет обернуть обновление состояния компонента
  // в `act` и мы получим предупреждение в терминале
  await user.click(screen.getByText('Получить приветствие'))

  // ждем рендеринга сообщения об ошибке
  await waitFor(() => screen.getByRole('alert'))

  // текстом сообщения об ошибке должно быть `Не удалось получить приветствие`
  expect(screen.getByRole('alert')).toHaveTextContent(
    'Не удалось получить приветствие'
  )
  // кнопка не должна быть заблокированной
  expect(screen.getByRole('button')).not.toBeDisabled()
})

Запускаем тесты с помощью команды yarn test:

{ task: 'default testing', status: 'done' }

Кастомный рендер

Предположим, что мы хотим распределить состояние приветствия между несколькими компонентами, например, с помощью провайдера.

Создаем в директории src файл GreetingProvider.jsx следующего содержания:

import { createContext, useContext, useReducer } from 'react'

// начальное состояние
const initialState = {
  error: null,
  greeting: null
}

// константы
const SUCCESS = 'SUCCESS'
const ERROR = 'ERROR'

// редуктор
function greetingReducer(state, action) {
  switch (action.type) {
    case SUCCESS:
      return {
        error: null,
        greeting: action.payload
      }
    case ERROR:
      return {
        error: action.payload,
        greeting: null
      }
    default:
      return state
  }
}

// создатель операций
const createGreetingActions = (dispatch) => ({
  setSuccess(success) {
    dispatch({
      type: SUCCESS,
      payload: success
    })
  },
  setError(error) {
    dispatch({
      type: ERROR,
      payload: error
    })
  }
})

// контекст
const GreetingContext = createContext()

// провайдер
export const GreetingProvider = ({ children }) => {
  const [state, dispatch] = useReducer(greetingReducer, initialState)

  const actions = createGreetingActions(dispatch)

  return (
    <GreetingContext.Provider value={{ state, actions }}>
      {children}
    </GreetingContext.Provider>
  )
}

// кастомный хук
export const useGreetingContext = () => useContext(GreetingContext)

Оборачиваем компонент FetchGreeting провайдером в файле App.jsx:

import { GreetingProvider } from './GreetingProvider'
import FetchGreeting from './FetchGreeting'

function App() {
  return (
    <div className='App'>
      <GreetingProvider>
        <FetchGreeting url='/greeting' />
      </GreetingProvider>
    </div>
  )
}

export default App

Редактируем FetchGreeting.jsx:

import { useState } from 'react'
import axios from 'axios'
import { useGreetingContext } from './GreetingProvider'

const FetchGreeting = ({ url }) => {
  // извлекаем состояние и операции из контекста
  const { state, actions } = useGreetingContext()
  const [btnClicked, setBtnClicked] = useState(false)

  const fetchGreeting = (url) =>
    axios
      .get(url)
      .then((res) => {
        const { data } = res
        const { greeting } = data
        // !
        actions.setSuccess(greeting)
        setBtnClicked(true)
      })
      .catch((e) => {
        // !
        actions.setError(e)
      })

  const btnText = btnClicked ? 'Готово' : 'Получить приветствие'

  return (
    <div>
      <button onClick={() => fetchGreeting(url)} disabled={btnClicked}>
        {btnText}
      </button>
      {/* ! */}
      {state.greeting && <h1 data-cy='heading'>{state.greeting}</h1>}
      {state.error && <p role='alert'>Не удалось получить приветствие</p>}
    </div>
  )
}

export default FetchGreeting

Для того, чтобы не оборачивать явно каждый тестируемый компонент в провайдеры, из которых он потребляет тот или иной контекст (состояние, тема, локализация и т.д.), предназначен кастомный рендер.

Создаем в корне проекта директорию testing. В этой директории создаем файл test-utils.jsx следующего содержания:

import { render } from '@testing-library/react'
import { GreetingProvider } from '../src/GreetingProvider'

// все провайдеры приложения
const AllProviders = ({ children }) => (
  <GreetingProvider>{children}</GreetingProvider>
)

// кастомный рендер
const customRender = (ui, options) =>
  render(ui, {
    // обертка для компонента
    wrapper: AllProviders,
    ...options
  })

// повторно экспортируем `Testing Library`
export * from '@testing-library/react'
// перезаписываем метод `render`
export { customRender as render }

Для того, чтобы иметь возможность импортировать кастомный рендер просто из test-utils необходимо сделать 2 вещи:

1. Сообщить Jest названия директорий с модулями:

// jest.config.js
module.exports = {
  testEnvironment: 'jest-environment-jsdom',
  extensionsToTreatAsEsm: ['.jsx'],
  // !
  moduleDirectories: ['node_modules', 'testing']
}

1. Добавить синоним пути в файле jsconfig.json (создаем этот файл в корне проекта):

{
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "test-utils": [
        "./testing/test-utils"
      ]
    }
  }
}

Для TypeScript-проекта синонимы путей (и другие настройки) определяются в файле tsconfig.json.

Редактируем файл fetch-greeting.test.jsx:

// импортируем стандартные утилиты `Testing Library` и кастомный рендер
import { render, fireEvent, waitFor, screen } from 'test-utils'

Запускаем тест с помощью yarn test и убеждаемся в том, что тесты по-прежнему выполняются успешно.

{ task: 'testing with custom render', status: 'done' }

Кастомные запросы

Что если нам оказалось недостаточно стандартных запросов, предоставляемых Testing Library? Что если мы, например, хотим получать ссылку на DOM-элемент с помощью атрибута data-cy? Для этого предназначены кастомные запросы.

Создаем в директории testing файл custom-queries.js следующего содержания:

import { queryHelpers, buildQueries } from '@testing-library/react'

const queryAllByDataCy = (...args) =>
  queryHelpers.queryAllByAttribute('data-cy', ...args)

const getMultipleError = (c, dataCyValue) =>
  `Обнаружено несколько элементов с атрибутом data-cy: ${dataCyValue}`

const getMissingError = (c, dataCyValue) =>
  `Не обнаружен элемент с атрибутом data-cy: ${dataCyValue}`

// генерируем кастомные запросы
const [
  queryByDataCy,
  getAllByDataCy,
  getByDataCy,
  findAllByDataCy,
  findByDataCy
] = buildQueries(queryAllByDataCy, getMultipleError, getMissingError)

// и экспортируем их
export {
  queryByDataCy,
  queryAllByDataCy,
  getByDataCy,
  getAllByDataCy,
  findByDataCy,
  findAllByDataCy
}

Далее кастомные запросы можно внедрить в кастомный рендер:

// test-utils.js
import { render, queries } from '@testing-library/react'
import * as customQueries from './custom-queries'

const customRender = (ui, options) =>
  render(ui, {
    wrapper: AllProviders,
    // !
    queries: { ...queries, ...customQueries },
    ...options
  })

Определяем атрибут data-cy у заголовка в компоненте FetchGreeting:

{state.greeting && <h1 data-cy='heading'>{state.greeting}</h1>}

И получаем ссылку на этот элемент в тесте с помощью кастомного запроса:

const { getByDataCy } = render(<FetchGreeting url='/greeting' />)

expect(getByDataCy('heading')).toHaveTextContent('Привет!')

Запускаем тест с помощью yarn test:

И получаем ошибку.

Ни в документации Testing Library, ни в документации Jest данная ошибка не описывается. Как видим, она возникает в файле node_modules/@testing-library/dom/dist/get-queries-for-element.js:

function getQueriesForElement(element, queries = defaultQueries, initialValue = {}) {
  return Object.keys(queries).reduce((helpers, key) => {
    // получаем запрос по ключу
    const fn = queries[key];
    // и передаем в запрос элемент в качестве аргумента
    // здесь возникает ошибка
    // `fn.bind не является функцией`
    helpers[key] = fn.bind(null, element);
    return helpers;
  }, initialValue);
}

Это наводит на мысль, что проблема заключается в наших кастомных запросах. Давайте на них взглянем:

// test-utils.jsx
console.log(customQueries)

Запускаем тест:

Видим ключ __esModule со значением true. Свойство __esModule функцией не является, поэтому при попытке вызова bind на нем выбрасывается исключение. Но откуда оно взялось в нашем модуле?

Коротко о главном:

• test-utils.jsx является модулем для тестирования;
• Jest автоматически создает "моковые" версии таких модулей — объекты заменяются, API сохраняется;
• перед созданием мока код модуля транспилируется с помощью Babel;
• Jest запускается в режиме поддержки ESM, поэтому Babel добавляет свойство __esModule в каждый мок.

Одним из самых простых способов решения данной проблемы является запрос оригинального модуля (без создания его моковой версии) с помощью метода requireActual объекта jest.

Для того, чтобы иметь возможность использовать этот объект в ESM, его следует импортировать из @jest/globals:

yarn add @jest/globals

import { jest } from '@jest/globals'
// import * as customQueries from './custom-queries'
const customQueries = jest.requireActual('./custom-queries')

Запускаем тест. Теперь все работает, как ожидается.

{ task: 'testing with custom queries', status: 'done' }

Тестирование компонента с помощью снимков Jest

Конечно, можно исследовать каждый DOM-элемент компонента по отдельности с помощью сопоставлений типа toHaveTextContent, но, согласитесь, что это не очень удобно. Легко можно пропустить какой-нибудь элемент или атрибут.

Для исследования текущего состояния всего UI за один раз предназначены снимки (snapshots).

На самом деле, в нашем распоряжении уже имеется все необходимое для тестирования компонента с помощью снимков. Одним из значений, возвращаемых методом render является container, который можно передать в метод expect и вызвать метод toMatchSnapshot:

describe('получение приветствия', () => {
  test('-> успешное получение и отображение приветствия', async function () {
    // получаем контейнер
    const { container, getByDataCy } = render(<FetchGreeting url='/greeting' />)
    // тестируем текущее состояние `UI` с помощью снимка
    expect(container).toMatchSnapshot()

    fireEvent.click(screen.getByText('Получить приветствие'))

    await waitFor(() => screen.getByRole('heading'))
    // состояние `UI` изменилось, поэтому нужен еще один снимок
    expect(container).toMatchSnapshot()

    expect(getByDataCy('heading')).toHaveTextContent('Привет!')
    expect(screen.getByRole('button')).toHaveTextContent('Готово')
    expect(screen.getByRole('button')).toBeDisabled()
  })

  it('-> обработка ошибки сервера', async () => {
    server.use(rest.get('/greeting', (req, res, ctx) => res(ctx.status(500))))

    // получаем контейнер
    const { container } = render(<FetchGreeting url='greeting' />)
    // снимок 1
    expect(container).toMatchSnapshot()

    const user = userEvent.setup()
    await user.click(screen.getByText('Получить приветствие'))

    await waitFor(() => screen.getByRole('alert'))
    // снимок 2
    expect(container).toMatchSnapshot()

    expect(screen.getByRole('alert')).toHaveTextContent(
      'Не удалось получить приветствие'
    )
    expect(screen.getByRole('button')).not.toBeDisabled()
  })
})

Запускаем тест:

При первом выполнении теста, в котором используются снимки, Jest генерирует снимки и складывает их в директорию __snapshots__ в директории с тестом. В нашем случае запуск теста привел к генерации файла fetch-greeting.test.jsx.snap следующего содержания:

exports[`получение приветствия -> обработка ошибки сервера 1`] = `
<div>
  <div>
    <button>
      Получить приветствие
    </button>
  </div>
</div>
`;

exports[`получение приветствия -> обработка ошибки сервера 2`] = `
<div>
  <div>
    <button>
      Получить приветствие
    </button>
    <p
      role="alert"
    >
      Не удалось получить приветствие
    </p>
  </div>
</div>
`;

exports[`получение приветствия -> успешное получение и отображение приветствия 1`] = `
<div>
  <div>
    <button>
      Получить приветствие
    </button>
  </div>
</div>
`;

exports[`получение приветствия -> успешное получение и отображение приветствия 2`] = `
<div>
  <div>
    <button
      disabled=""
    >
      Готово
    </button>
    <h1
      data-cy="heading"
    >
      Привет!
    </h1>
  </div>
</div>
`;

Как видим, снимок правильно отражает все изменения состояния UI компонента.

Снова запускаем тест:

{ task: 'snapshot testing', status: 'done' }

Парочка полезных советов:

• для обновления снимка следует передать флаг --updateSnapshot или просто -u при вызове Jest: yarn test -u;
• для указания тестов для выполнения или снимков для обновления при вызове Jest можно передать флаг --testPathPattern со значением директории с тестами (в виде строки или регулярного выражения): yarn test -u --testPathPattern=components/fetchGreeting.

Для того, чтобы иметь возможность импортировать статику (изображения, шрифты, аудио, видео и т.д.) в тестируемых компонентах, необходимо реализовать кастомный трансформер для Jest.

Создаем в директории testing файл file-transformer.js следующего содержания:

// формат `CommonJS` в данном случае является обязательным
const path = require('path')

module.exports = {
  process: (sourceText, sourcePath, options) => ({
    code: `module.exports = ${JSON.stringify(path.basename(sourcePath))}`
  })
}

И настраиваем трансформацию в файле jest.config.js:

module.exports = {
  testEnvironment: 'jest-environment-jsdom',
  extensionsToTreatAsEsm: ['.jsx'],
  moduleDirectories: ['node_modules', 'testing'],
  // !
  transform: {
    // дефолтное значение, в случае кастомизации должно быть указано явно
    '\\.[jt]sx?$': 'babel-jest',
    // трансформация файлов
    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$':
      '<rootDir>/testing/file-transformer.js'
  }
}

Пожалуй, это все, что я хотел рассказать о тестировании React-компонентов с помощью Jest и Testing Library. Надеюсь, вы нашли для себя что-то интересное и не зря потратили время.

Благодарю за внимание и happy coding!