Снимки Aria

Обзор​

В Playwright снимки aria представляют собой YAML-представление дерева доступности страницы. Эти снимки можно сохранить и сравнить позднее, чтобы проверить, сохраняется ли структура страницы неизменной или соответствует определённым ожиданиям.

Формат YAML описывает иерархическую структуру доступных элементов на странице, подробно описывая роли, атрибуты, значения и текстовое содержимое. Структура следует деревному синтаксису, где каждый узел представляет собой доступный элемент, а отступы указывают вложенные элементы.

Ниже приведен простой пример снимка aria для домашней страницы playwright.dev:

- banner:
  - heading /Playwright enables reliable/ [level=1]
  - link "Get started"
  - link "Star microsoft/playwright on GitHub"
- main:
  - img "Browsers (Chromium, Firefox, WebKit)"
  - heading "Any browser • Any platform • One API"

Каждый доступный элемент в дереве представлен в виде узла YAML:

- role "name" [attribute=value]

• роль: Указывает роль ARIA или HTML элемента (например, heading, list, listitem, button).
• "имя": Доступное имя элемента. Строки в кавычках указывают точные значения, /patterns/ используются для регулярных выражений.
• [атрибут=значение]: Атрибуты и значения в квадратных скобках представляют собой конкретные атрибуты ARIA, такие как checked, disabled, expanded, level, pressed, или selected.

Эти значения взяты из атрибутов ARIA или рассчитаны на основе семантики HTML. Для проверки структуры дерева доступности страницы используйте панель доступности Chrome DevTools.

Сопоставление снимков​

Метод утверждения expect(locator).toMatchAriaSnapshot() в Playwright сравнивает доступную структуру области действия локейтера с предварительно определённым шаблоном снимка aria, помогая валидировать состояние страницы по отношению к требованиям тестирования.

Для следующего DOM:

<h1>title</h1>

Вы можете сопоставить его с помощью следующего шаблона снимка:

await expect(page.locator('body')).toMatchAriaSnapshot(`
  - heading "title"
`);

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

• Если структура дерева соответствует шаблону, тест пройден; в противном случае он завершается неудачей, указывая на несоответствие между ожидаемым и фактическим состоянием доступности.
• Сравнение регистрозависимое и сворачивает пробелы, поэтому отступы и переводы строк игнорируются.
• Сравнение чувствительно к порядку, что означает, что порядок элементов в шаблоне снимка должен соответствовать порядку в дереве доступности страницы.

Частичное сопоставление​

Вы можете выполнить частичные сопоставления узлов, опуская атрибуты или доступные имена, что позволяет проверять определённые части дерева доступности без необходимости точного соответствия. Эта гибкость полезна для динамических или неважных атрибутов.

<button>Submit</button>

снимок aria

- button

В этом примере роль кнопки сопоставляется, но доступное имя ("Отправить") не указано, что позволяет тесту пройти независимо от метки кнопки.

Для элементов с атрибутами ARIA, такими как checked или disabled, опускание этих атрибутов позволяет выполнить частичное сопоставление, фокусируясь только на роли и иерархии.

<input type="checkbox" checked>

снимок aria для частичного соответствия

- checkbox

В этом частичном соответствии атрибут checked игнорируется, поэтому тест пройдёт независимо от состояния флажка.

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

<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

снимок aria для частичного соответствия

- list
  - listitem: Feature B

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

Сопоставление с регулярными выражениями​

Регулярные выражения позволяют гибко сопоставлять элементы с динамичным или переменным текстом. Доступные имена и текст могут поддерживать шаблоны регулярных выражений.

<h1>Issues 12</h1>

снимок aria с регулярным выражением

- heading /Issues \d+/

Создание снимков​

Создание снимков aria в Playwright помогает гарантировать и поддерживать структуру вашего приложения. Вы можете создавать снимки различными способами в зависимости от вашей тестовой настройки и рабочего процесса.

1. Создание снимков с помощью генератора кода Playwright​

Если вы используете генератор кода Playwright, создание снимков aria упрощается с его интерактивным интерфейсом:

• Действие "Утвердить снимок": В генераторе кода вы можете использовать действие "Утвердить снимок", чтобы автоматически создать утверждение снимка для выбранных элементов. Это быстрый способ зафиксировать снимок aria в рамках вашего записанного тестового потока.
• Вкладка "Снимок Aria": Вкладка "Снимок Aria" в интерфейсе генератора кода визуально представляет снимок aria для выбранного локейтера, позволяя изучить, проверить и убедиться в ролях элементов, атрибутах и доступных именах для помощи в создании и проверке снимков.

2. Обновление снимков с помощью @playwright/test и флага --update-snapshots​

При использовании исполнителя тестов Playwright (@playwright/test) вы можете автоматически обновлять снимки, выполняя тесты с флагом --update-snapshots:

npx playwright test --update-snapshots

Эта команда пересоздаёт снимки для утверждений, включая снимки aria, заменяя устаревшие. Это полезно, когда изменения структуры приложения требуют новых снимков в качестве эталона. Обратите внимание, что Playwright будет ждать максимального времени ожидания expect, указанного в настройках исполнителя тестов, чтобы убедиться, что страница стабилизировалась перед созданием снимка. Возможно, потребуется настроить --timeout , если тест столкнётся с таймаутом при создании снимков.

Пустой шаблон для создания снимков​

Передача пустой строки в качестве шаблона в утверждении создаёт снимок на лету:

await expect(locator).toMatchAriaSnapshot('');

Обратите внимание, что Playwright будет ждать максимального времени ожидания expect, указанного в настройках исполнителя тестов, чтобы убедиться, что страница стабилизировалась перед созданием снимка. Возможно, потребуется настроить --timeout , если тест столкнётся с таймаутом при создании снимков.

Файлы исправлений снимков​

При обновлении снимков Playwright создаёт файлы исправлений, которые фиксируют различия. Эти файлы исправлений можно просмотреть, применить и добавить в систему управления версиями, что позволяет командам отслеживать изменения структуры со временем и обеспечивать согласованность обновлений с требованиями приложения.

3. Использование метода Locator.ariaSnapshot​

Метод locator.ariaSnapshot() позволяет программно создать YAML-представление доступных элементов в области действия локейтера, что особенно полезно для динамического создания снимков во время выполнения тестов.

Пример:

const snapshot = await page.locator('body').ariaSnapshot();
console.log(snapshot);

Эта команда выводит снимок aria в области действия указанного локейтера в формате YAML, который можно валидировать или сохранять по мере необходимости.

Примеры дерева доступности​

Заголовки с атрибутами уровня​

Заголовки могут включать атрибут level , указывающий их уровень заголовка.

<h1>Title</h1>
<h2>Subtitle</h2>

снимок aria

- heading "Title" [level=1]
- heading "Subtitle" [level=2]

Узлы текста​

Самостоятельные или описательные текстовые элементы отображаются как текстовые узлы.

<div>Sample accessible name</div>

снимок aria

- text: Sample accessible name

Многострочный текст в строке​

Многострочный текст, такой как абзацы, нормализуется в снимке aria.

<p>Line 1<br>Line 2</p>

снимок aria

- paragraph: Line 1 Line 2

Ссылки​

Ссылки отображают свой текст или составленное содержимое из псевдоэлементов.

<a href="#more-info">Read more about Accessibility</a>

снимок aria

- link "Read more about Accessibility"

Поле ввода текста​

Элементы ввода типа text показывают содержимое атрибута value.

<input type="text" value="Enter your name">

снимок aria

- textbox: Enter your name

Списки с элементами​

Упорядоченные и неупорядоченные списки включают свои элементы списка.

<ul aria-label="Main Features">
  <li>Feature 1</li>
  <li>Feature 2</li>
</ul>

снимок aria

- list "Main Features":
  - listitem: Feature 1
  - listitem: Feature 2

Сгруппированные элементы​

Группы захватывают вложенные элементы, такие как элементы <details> с содержимым сводки.

<details>
  <summary>Summary</summary>
  <p>Detail content here</p>
</details>

мгновенный снимок aria

- group: Summary

Атрибуты и состояния​

Часто используемые атрибуты ARIA, такие как checked, disabled, expanded, level, pressed, и selected, представляют состояния управления.

Флажок с атрибутом checked​

<input type="checkbox" checked>

мгновенный снимок aria

- checkbox [checked]

Кнопка с атрибутом pressed​

<button aria-pressed="true">Toggle</button>

мгновенный снимок aria

- button "Toggle" [pressed=true]