содержит

Получите элемент DOM, содержащий текст. Элементы DOM могут содержать больше, чем нужный текст, и всё ещё соответствовать. Кроме того, Cypress предпочитает некоторые элементы DOM по сравнению с самым глубоким найденным элементом.

Синтаксис

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

// ---or---

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

Использование

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

cy.get('.nav').contains('About') // Yield el in .nav containing 'About'
cy.contains('Hello') // Yield first el in document containing 'Hello'

Неправильное использование

cy.title().contains('My App') // Errors, 'title' does not yield DOM element
cy.getCookies().contains('_key') // Errors, 'getCookies' does not yield DOM element

Аргументы

content (Строка, Число, Регулярное выражение)

Получите элемент DOM, содержащий содержимое.

selector (Строковый селектор)

Укажите селектор для фильтрации элементов DOM, содержащих текст. Cypress проигнорирует стандартный порядок предпочтения для указанного селектора. Использование селектора позволяет возвращать более поверхностные элементы (более высокие в дереве), содержащие указанный текст.

options (Объект)

Передайте объект опций, чтобы изменить стандартное поведение .contains().

Опция	Значение по умолчанию	Описание
`matchCase`	`true`	Проверка чувствительности к регистру
`log`	`true`	Отображает команду в Журнале команд
`timeout`	`defaultCommandTimeout`	Время ожидания `.contains()` до истечения времени ожидания
`includeShadowDom`	`includeShadowDom` значение опции конфигурации	Указывать ли на прохождение границ тени DOM и включать элементы в тени DOM в возвращаемых результатах.

Возвращаемые значения

.contains() возвращает новый найденный элемент DOM.

Примеры

Содержимое

Поиск первого элемента, содержащего некоторый текст

<ul>
  <li>apples</li>
  <li>oranges</li>
  <li>bananas</li>
</ul>

// yields <li>apples</li>
cy.contains('apples')

Поиск `input[type='submit']` по значению

Получите элемент формы и выполните поиск в его потомках для содержимого "Отправить форму!"

<div id="main">
  <form>
    <div>
      <label>name</label>
      <input name="name" />
    </div>
    <div>
      <label>age</label>
      <input name="age" />
    </div>
    <input type="submit" value="submit the form!" />
  </form>
</div>

// yields input[type='submit'] element then clicks it
cy.get('form').contains('submit the form!').click()

Число

Поиск первого элемента, содержащего число

Несмотря на то, что <span> является самым глубоким элементом, содержащим "4", Cypress автоматически возвращает <button> элементы над тегами span из-за упорядочения предпочтения элементов.

<button class="btn btn-primary" type="button">
  Messages <span class="badge">4</span>
</button>

// yields <button>
cy.contains(4)

Регулярное выражение

Поиск первого элемента с текстом, соответствующим регулярному выражению

<ul>
  <li>apples</li>
  <li>oranges</li>
  <li>bananas</li>
</ul>

// yields <li>bananas</li>
cy.contains(/^b\w+/)

Селектор

Указание селектора для возвращения определённого элемента

Фактически, <html>, <body>, <ul>, и первый <li> в примере ниже все содержат "яблоки".

Обычно Cypress возвращает первый <li> , так как это самый глубокий элемент, содержащий "яблоки".

Чтобы переопределить возвращаемый элемент, можно передать 'ul' в качестве селектора.

<html>
  <body>
    <ul>
      <li>apples</li>
      <li>oranges</li>
      <li>bananas</li>
    </ul>
  </body>
</html>

// yields <ul>...</ul>
cy.contains('ul', 'apples')

Поддержание формы в качестве объекта

Вот пример, использующий селектор, чтобы убедиться, что <form> остаётся объектом для последующего цепного вызова.

<form>
  <div>
    <label>name</label>
    <input name="name" />
  </div>
  <button type="submit">Proceed</button>
</form>

cy.get('form') // yields <form>...</form>
  .contains('form', 'Proceed') // yields <form>...</form>
  .submit() // yields <form>...</form>

Без явного селектора объектом станет <button>. Использование явного селектора гарантирует, что в цепочке команд объектом останется <form>.

Чувствительность к регистру

Вот пример использования опции matchCase для игнорирования чувствительности к регистру.

<div>Capital Sentence</div>

cy.get('div').contains('capital sentence') // fail
cy.get('div').contains('capital sentence', { matchCase: false }) // pass

Примечания

Области

.contains() ведет себя по-разному, если это начало цепочки команд или цепочка команд от уже существующей.

При запуске новой цепочки команд:

Это запрос ко всему document для поиска содержимого.

cy.contains('Log In')

При цепочке команд от уже существующей:

Это поиск внутри элемента <#checkout-container>.

cy.get('#checkout-container').contains('Buy Now')

Будьте внимательны при цепочке нескольких contains

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

// This doesn't work as intended
cy.contains('Delete User').click().contains('Yes, Delete!').click()

Поскольку второй .contains() привязан к команде, которая возвратила <button>, Cypress будет искать содержимое внутри <button>.

Другими словами, Cypress будет искать "Да, Удалить!" внутри элемента <button> содержащего "Удалить пользователя", что не соответствует нашему желанию.

В этом случае необходимо вызвать cy снова, что автоматически создаёт новую цепочку, ограниченную document.

cy.contains('Delete User').click()
cy.contains('Yes, Delete!').click()

Пробелы в начале, конце и дублирующие пробелы игнорируются тегом `<pre>`

В отличие от других тегов, <pre> не игнорирует пробелы в начале, конце и повторяющиеся пробелы, как показано ниже:

<!--Code for test-->
<h2>Other tags</h2>
<p>Hello, World !</p>

<h2>Pre tag</h2>
<pre>                 Hello,           World      !</pre>

Результат рендеринга:

Чтобы отразить это поведение, Cypress также не игнорирует их.

// test result for above code

cy.get('p').contains('Hello, World !') // pass
cy.get('p').contains('           Hello,          World   !') // fail

cy.get('pre').contains('Hello, World !') // fail
cy.get('pre').contains('                 Hello,           World      !') // pass

Неразрывный пробел

В cy.contains() можно использовать пробел, чтобы соответствовать тексту в HTML, использующему символ неразрывного пробела &ampnbsp;.

<span>Hello&ampnbsp;world</span>

// finds the span element
cy.contains('Hello world')

Совет: ознакомьтесь с утверждениями против текста с неразрывными пробелами в Как получить текстовое содержимое элемента?

Один элемент

Возвращается только первый соответствующий элемент

<ul id="header">
  <li>Welcome, Jane Lane</li>
</ul>
<div id="main">
  <span>These users have 10 connections with Jane Lane</span>
  <ul>
    <li>Jamal</li>
    <li>Patricia</li>
  </ul>
</div>

В примере ниже будет возвращён <li> в #header , так как это первый элемент, содержащий текст "Jane Lane".

// yields #header li
cy.contains('Jane Lane')

Если необходимо выбрать <span> вместо него, можно сузить возвращаемые элементы до .contains().

// yields <span>
cy.get('#main').contains('Jane Lane')

Предпочтения

Порядок предпочтения элементов

.contains() по умолчанию отдаёт предпочтение элементам, расположенным выше в дереве, когда они:

input[type='submit']
button
a
label

Cypress игнорирует порядок предпочтения элементов, если вы передаёте селектор в .contains().

Предпочтение тегов `<button>` перед другими более глубокими элементами

Несмотря на то, что <span> является самым глубоким элементом, содержащим "Поиск", Cypress отдаёт предпочтение элементам типа <button> перед span.

<form>
  <button>
    <i class="fa fa-search"></i>
    <span>Search</span>
  </button>
</form>

// yields <button>
cy.contains('Search').children('i').should('have.class', 'fa-search')

Предпочтение тегов `<a>` перед другими более глубокими элементами

Несмотря на то, что <span> является самым глубоким элементом, содержащим "Выход", Cypress отдаёт предпочтение элементам типа a перед span.

<nav>
  <a href="/users">
    <span>Users</span>
  </a>
  <a href="/signout">
    <span>Sign Out</span>
  </a>
</nav>

// yields <a>
cy.get('nav').contains('Sign Out').should('have.attr', 'href', '/signout')

Предпочтение тегов `<label>` перед другими более глубокими элементами

Несмотря на то, что <span> является самым глубоким элементом, содержащим "Возраст", Cypress отдаёт предпочтение элементам типа <label> перед <span>.

<form>
  <label>
    <span>Name:</span>
    <input name="name" />
  </label>
  <label>
    <span>Age:</span>
    <input name="age" />
  </label>
</form>

// yields label
cy.contains('Age').find('input').type('29')

Правила

Требования

.contains() может быть привязано к cy или к команде, возвращающей элемент(ы) DOM.

Утверждения

.contains() автоматически повторяется, пока элемент(ы) не существуют в DOM
.contains() автоматически повторяется, пока все цепные утверждения не пройдут

Таймауты

.contains() может истечь, ожидая, пока элемент(ы) будут существовать в DOM .
.contains() может истечь, ожидая, пока утверждения не пройдут.

Журнал команд

Элемент содержит текст "Новый пользователь"

cy.get('h1').contains('New User')

Приведённые выше команды будут отображены в журнале команд как:

При нажатии на команду contains в журнале команд консоль выводит следующее:

История

Версия	Изменения
5.2.0	Добавлена опция `includeShadowDom`.
4.0.0	Добавлена поддержка опции `matchCase`.