Команда cy.contains()

Команда cy.contains() в Cypress предназначена для поиска элементов на странице по текстовому содержимому. Она является мощным инструментом для работы с динамическими элементами, где идентификаторы или классы могут быть нестабильными, а текстовая метка остаётся уникальной и постоянной.

Синтаксис и базовое использование

Базовый синтаксис команды выглядит следующим образом:

cy.contains(content)
cy.contains(selector, content)
cy.contains(content, options)
cy.contains(selector, content, options)

content — текст, который необходимо найти на странице. Может быть строкой или регулярным выражением.
selector — (необязательный) CSS-селектор, ограничивающий область поиска.
options — дополнительные параметры поиска (например, { matchCase: true } для учёта регистра).

Пример базового поиска элемента по тексту:

cy.contains('Войти').click()

В данном случае Cypress ищет первый видимый элемент на странице, содержащий текст “Войти”, и выполняет по нему клик.

Использование с CSS-селекторами

Команда cy.contains() позволяет сначала сузить область поиска до определённого селектора, а затем искать текст внутри него:

cy.contains('form', 'Отправить').click()

Здесь поиск будет производиться только внутри <form> элементов. Это особенно полезно, когда на странице встречаются одинаковые тексты, но в разных контекстах.

Поиск с помощью регулярных выражений

Регулярные выражения позволяют реализовать гибкий поиск текста, не зависящий от точного совпадения.

Примеры:

cy.contains(/^Войти$/)      // точное совпадение
cy.contains(/войти/i)       // нечувствительный к регистру поиск
cy.contains(/Отправ.*/i)    // поиск текста, начинающегося с "Отправ"

Регулярные выражения упрощают тестирование динамического текста, частично совпадающего с шаблоном.

Параметры `options`

Основные опции для cy.contains():

matchCase — учитывает регистр при поиске (true или false).
timeout — время ожидания появления элемента. По умолчанию Cypress ожидает до 4 секунд, но опция позволяет увеличить ожидание для медленных страниц.

Пример использования:

cy.contains('Загрузить', { matchCase: true, timeout: 10000 }).click()

Комбинация с другими командами Cypress

cy.contains() можно комбинировать с цепочкой команд:

cy.contains('Товары')
  .parent()          // переходим к родительскому элементу
  .find('button')    // ищем кнопку внутри родителя
  .click()

Такая цепочка позволяет точечно воздействовать на элементы, которые иначе сложно однозначно идентифицировать.

Отличие от `cy.get()`

cy.get() ищет элементы по селекторам, игнорируя текст.
cy.contains() ищет по тексту, что упрощает работу с кнопками, ссылками и динамическими метками.

Иногда комбинируют оба метода:

cy.get('ul.menu').contains('Контакты').click()

Сначала ограничивается область поиска ul.menu, затем выбирается элемент с текстом “Контакты”.

Особенности поведения

Поиск только видимых элементов — Cypress игнорирует элементы, скрытые через CSS (display: none или visibility: hidden).
Первый подходящий элемент — если текст встречается в нескольких местах, выбирается первый найденный видимый элемент.
Динамическое ожидание — команда автоматически ждёт появления текста на странице до истечения таймаута.

Практические сценарии применения

Поиск кнопок с конкретным текстом:

cy.contains('Добавить в корзину').click()

Проверка наличия текстового сообщения:

cy.contains('Ошибка при входе').should('be.visible')

Работа с элементами в пределах конкретной формы или блока:

cy.contains('div.card', 'JavaScript для начинающих')
  .find('button.buy')
  .click()

Игнорирование регистра при поиске:

cy.contains(/войти/i).click()