byRole

Итак, начнем с подробного разбора самого главного запроса в Testing Library: byRole. Это методы getByRole, getAllByRole, queryByRole, queryAllByRole, findByRole, findAllByRole.

Документация: https://testing-library.com/docs/queries/byrole

Собственно роль

Первым параметром метод принимает собственно роль нужного элемента в виде строки. Это может быть button, heading, switch и так далее.

Речь идет не об атрибуте role, а прежде всего о дефолтной (встроенной) роли элементов. Например, элемент button имеет роль button, даже без явного указания на это. Вот тут можно почитать про роли элементов.

Опции

Вторым параметром можно передать объект с кучей дополнительных опций, которые помогут найти нужный элемент. Например, если у вас на странице куча кнопок, а нужно найти конкретную.

Тут будет много опций для поиска по aria- атрибутам.

🔸hidden: boolean

По умолчанию значение равно false - из-за этого в поиск не включаются "недоступные" элементы (display: none, aria-hidden, role=none).

🔸name: TextMatch

Для элемента формы - это текст лейбла, для кнопки - собственно текст кнопки. Также может использоваться значение атрибута aria-label.

Что за тип такой TextMatch? Это составной тип, который может быть обычной строкой, регулярным выражением или даже функцией.

Функция принимает два аргумента: content: string (собственно текстовый контент, по которому производится поиск) и element (DOMElement) и должна вернуть true или false.

screen.getByText((content, element) => content.startsWith('Hello'))

🔸description: TextMatch

Это для атрибута aria-describedby.

🔸selected: boolean

Отбор по значению атрибута aria-selected.

🔸busy: boolean

Отбор по значению атрибута aria-busy.

🔸checked: boolean

Отбор по значению атрибута aria-checked.

🔸pressed: boolean

Отбор по значению атрибута aria-pressed.

🔸suggest: boolean

Эта настройка для того, чтобы Testing Library предлагала вам запросы получше, чем тот, что написали вы.

🔸current: boolean | string

Отбор по значению атрибута aria-current.

🔸expanded: boolean

Отбор по значению атрибута aria-expanded.

🔸queryFallbacks: boolean

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

🔸level: number

Уровень заголовка для роли heading. Учитывает как семантику тега, так и атрибут aria-level.

🔸value

Это для группы атрибутов aria-value, например, aria-valuemin, aria-valuetext. Указывается в виде объекта:

screen.getByRole('spinbutton', { value: { min: 5, max: 10 }})

#тестирование #testinglibrary #документация

ByLabelText, ByPlaceholderText

Два запроса, предназначенных в основном для интерактивных элементов форм: поиск по тексту лейбла и по плейсхолдеру.

ByLabelText

Поле ввода может быть связано с лейблом разными способами:

- через атрибуты for и id
- через атрибут aria-labelledby
- если поле находится внутри label
- лейбл можно указать в атрибуте aria-label

Сигнатура:

screen.getByLabelText(
  text: TextMatch,
  options: {
    selector?: string = '*',
    exact?: boolean = true,
    normalizer?: NormalizeFn
  }
)

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

Вторым параметром идет объект настроект:
- selector - можно дополнительно указать селектор нужного элемента
- exact - если текст задан в виде строки, то этот параметр определяет должен ли поиск быть точным (по полной строке, с учетом регистра символов) или нет
- normalizer - по умолчанию Testing Library нормализует текст (убирает лишние пробелы). Можно передать собственный нормализатор

ByPlaceholderText

Очень похожий метод, только ищет элемент по тексту плейсхолдера. Менее предпочтительный, следует использовать только если элемент нельзя найти по лейблу или роли.

Сигнатура:

screen.getByPlaceholderText(
  text: TextMatch,
  options: {
    exact?: boolean = true,
    normalizer?: NormalizerFn
  }
)

#тестирование #testinglibrary #документация #примерыкода

ByDisplayValue

Еще один запрос для интерактивных элементов, у которых может быть value (input, textarea, select). Соответственно поиск происходит по текущему значению value - это текст, который отображается в инпуте. Настроек у запроса немного:

screen.getByDisplayValue(
  value: TextMatch, 
  options?: {
    exact?: boolean = true,
    normalizer?: NormalizerFn,
  }
)

#тестирование #testinglibrary #документация #примерыкода

ByText

Есть возможность искать элементы по текстовому контенту. Это сработает для всех элементов, у которых есть textContent, а также для инпутов с типом submit или button.

Настройки у запроса стандартные:

getByText(
  text: TextMatch,
  options?: {
    selector?: string = '*',
    exact?: boolean = true,
    ignore?: string|boolean = 'script, style',
    normalizer?: NormalizerFn,
 })

Новая для нас настройка - ignore, она указывает, какие селекторы игнорировать при поиске.

#тестирование #testinglibrary #документация #примерыкода

ByAltText, ByTitle

Еще два запроса для поиска по значению атрибутов:

- alt - в основном для изображений
- title

screen.getByAltText(
  text: TextMatch,
  options?: {
    exact?: boolean = true,
    normalizer?: NormalizerFn,
 })

screen.getByTitle(
  title: TextMatch,
  options?: {
    exact?: boolean = true,
    normalizer?: NormalizerFn,
  })

#тестирование #testinglibrary #документация #примерыкода

ByTestId

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

screen.getByTestId(
  text: TextMatch,
  options?: {
    exact?: boolean = true,
    normalizer?: NormalizerFn,
})

#тестирование #testinglibrary #документация #примерыкода