Перейти к основному содержимому

Тестирование снимков

Обзор​

С помощью тестирования снимков в Playwright вы можете проверять дерево доступности страницы по заранее определенному шаблону снимка.

await page.goto('https://playwright.dev/');
await expect(page).toMatchAriaSnapshot(`
- banner:
- heading /Playwright enables reliable end-to-end/ [level=1]
- link "Get started":
- /url: /docs/intro
- link "Star microsoft/playwright on GitHub":
- /url: https://github.com/microsoft/playwright
- link /[\\d]+k\\+ stargazers on GitHub/
`);

Тестирование утверждений vs Тестирование снимков​

Тестирование снимков и тестирование утверждений служат разным целям в автоматизации тестирования:

Тестирование утверждений​

Тестирование утверждений — это целенаправленный подход, при котором вы утверждаете конкретные значения или условия для элементов или компонентов. Например, с помощью Playwright, expect(locator).toHaveText() проверяет, что элемент содержит ожидаемый текст, а expect(locator).toHaveValue() подтверждает, что поле ввода имеет ожидаемое значение. Тесты утверждений специфичны и обычно проверяют текущее состояние элемента или свойства по сравнению с ожидаемым, заранее определенным состоянием. Они хорошо работают для предсказуемых, однозначных проверок, но ограничены в охвате при тестировании более широкой структуры или вариаций.

Преимущества

  • Ясность: Намерение теста явно и легко понять.
  • Специфичность: Тесты сосредоточены на конкретных аспектах функциональности, что делает их более устойчивыми к несвязанным изменениям.
  • Отладка: Ошибки предоставляют целенаправленную обратную связь, указывая непосредственно на проблемный аспект.

Недостатки

  • Многословность для сложных выводов: Написание утверждений для сложных структур данных или больших выводов может быть громоздким и подверженным ошибкам.
  • Затраты на обслуживание: По мере развития кода ручное обновление утверждений может быть трудоемким.

Тестирование снимков​

Тестирование снимков захватывает "снимок" или представление всего состояния элемента, компонента или данных в данный момент, который затем сохраняется для будущих сравнений. При повторном запуске тестов текущее состояние сравнивается со снимком, и если есть различия, тест не проходит. Этот подход особенно полезен для сложных или динамических структур, где ручное утверждение каждой детали было бы слишком трудоемким. Тестирование снимков более широкое и целостное, чем тестирование утверждений, позволяя отслеживать более сложные изменения с течением времени.

Преимущества

  • Упрощает сложные выводы: Например, тестирование визуального компонента может быть утомительным с традиционными утверждениями. Снимки захватывают весь вывод для легкого сравнения.
  • Быстрая обратная связь: Разработчики могут легко заметить непреднамеренные изменения в выводе.
  • Поощряет согласованность: Помогает поддерживать согласованный вывод по мере развития кода.

Недостатки

  • Чрезмерная зависимость: Может возникнуть соблазн принять изменения в снимках, не полностью понимая их, что потенциально скрывает ошибки.
  • Гранулярность: Большие снимки могут быть трудны для интерпретации, когда возникают различия, особенно если незначительные изменения затрагивают большие части вывода.
  • Пригодность: Не идеально для высоко динамичного контента, где выводы часто или непредсказуемо меняются.

Когда использовать​

  • Тестирование снимков идеально для:
    • Тестирования пользовательского интерфейса целых страниц и компонентов.
    • Широких структурных проверок для сложных компонентов пользовательского интерфейса.
    • Регрессионного тестирования для выводов, которые редко меняют структуру.
  • Тестирование утверждений идеально для:
    • Проверки основной логики.
    • Тестирования вычисленных значений.
    • Тонких тестов, требующих точных условий.

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

Aria снимки​

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

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

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

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

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

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

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

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

<h1>title</h1>

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

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

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

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

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

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

<button>Submit</button>
ARIA-снимок
- button

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


Для элементов с 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

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

Строгое сопоставление​

По умолчанию будет сопоставляться шаблон, содержащий подмножество дочерних элементов:

<ul>
<li>Feature A</li>
<li>Feature B</li>
<li>Feature C</li>
</ul>
ARIA-снимок (частичное совпадение)
- list:
- listitem: Feature B

Свойство /children управляет сопоставлением дочерних узлов того узла, в котором оно указано:

  • contain (по умолчанию): Совпадение, если все указанные дочерние узлы присутствуют в заданном порядке.
  • equal: Совпадение, если непосредственные дочерние узлы в точности соответствуют указанному списку с учётом порядка.
  • deep-equal: Совпадение, если дочерние узлы и все их потомки в точности соответствуют указанному списку с учётом порядка.

Если ожидаемые дочерние узлы не указаны, contain допускает любые дочерние узлы, тогда как equal и deep-equal требуют их отсутствия. Добавьте /children: contain во вложенный узел, чтобы переопределить унаследованный режим сопоставления deep-equal и разрешить в нём дополнительные дочерние узлы.

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

Следующая проверка снимка завершится неудачей, поскольку Feature C отсутствует в шаблоне:

aria snapshot
- list:
- /children: equal
- listitem: Feature A
- listitem: Feature B

Глобальная настройка режима children​

Вместо добавления свойства /children в каждый снимок вы можете задать режим сопоставления дочерних элементов по умолчанию для всех вызовов toMatchAriaSnapshot в файле конфигурации:

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
expect: {
toMatchAriaSnapshot: {
children: 'equal',
},
},
});

Отдельные снимки по-прежнему могут переопределять глобальную настройку, явно указывая свойство /children в шаблоне.

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

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

<h1>Issues 12</h1>
ARIA-снимок
- heading /Issues \d+/

Генерация снимков​

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

Генерация снимков с помощью генератора кода Playwright​

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

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

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

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

При запуске без этого флага используется режим default: отсутствующие снимки создаются, но тесты, которые их создают, завершаются с ошибкой, чтобы запуск с новыми снимками не прошёл незаметно. Используйте missing, чтобы создавать отсутствующие снимки и при этом сохранять успешный статус этих тестов. При указании -u используется режим changed, в котором обновляются снимки, не совпадающие с текущим результатом. Используйте all, чтобы заново создать все снимки, включая совпадающие, или none, чтобы запретить обновление снимков.

npx playwright test --update-snapshots

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

Пустой шаблон для генерации снимков​

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

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

Это работает без -u, поскольку в режиме по умолчанию создаются недостающие снимки.

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

Для встроенных шаблонов снимков Playwright создаёт файлы патчей, содержащие различия. Эти файлы патчей можно просмотреть и применить. Отдельные снимки .aria.yml записываются непосредственно по настроенному для них пути.

Способ обновления исходного кода можно изменить с помощью флага --update-source-method. Доступно несколько вариантов:

  • "patch" (по умолчанию): Генерирует унифицированный файл diff, который можно применить к исходному коду с помощью git apply.
  • "3way": Генерирует маркеры конфликтов слияния в вашем исходном коде, позволяя вам выбрать, принимать ли изменения.
  • "overwrite": Перезаписывает исходный код новыми значениями снимков.
npx playwright test --update-snapshots --update-source-method=3way

Снимки как отдельные файлы​

Чтобы сохранить ваши снимки в отдельном файле, используйте метод toMatchAriaSnapshot с опцией name, указывая расширение файла .aria.yml.

await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });

По умолчанию снимки из тестового файла example.spec.ts размещаются в каталоге example.spec.ts-snapshots. Поскольку снимки должны быть одинаковыми для всех браузеров, сохраняется только один снимок, даже если тестирование проводится с несколькими браузерами. Если вы хотите, вы можете настроить шаблон пути снимка с помощью следующей конфигурации:

export default defineConfig({
expect: {
toMatchAriaSnapshot: {
pathTemplate: '__snapshots__/{testFilePath}/{arg}{ext}',
},
},
});

Использование page.ariaSnapshot() и locator.ariaSnapshot()​

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

Пример:

const snapshot = await page.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

Ссылки отображают свой текст или составное содержимое из псевдоэлементов. Адрес назначения ссылки можно сопоставить с помощью свойства /url.

<a href="#more-info">Read more about Accessibility</a>
ARIA-снимок
- link "Read more about Accessibility":
- /url: "#more-info"

Значение /url также может быть регулярным выражением:

<a href="https://www.youtube.com/channel/UC46Zj8pDH5tDosqm1gd7WTg">YouTube channel</a>
aria snapshot
- link:
- /url: /https://www.youtube.com/channel/.*/

Текстовые поля​

Элементы ввода типа 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> с содержимым summary.

<details>
<summary>Summary</summary>
<p>Detail content here</p>
</details>
ARIA-снимок
- group: Summary

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

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

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

<input type="checkbox" checked>
снимок ARIA
- checkbox [checked]

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

<button aria-pressed="true">Toggle</button>
ARIA-снимок
- button "Toggle" [pressed=true]

Поле ввода с атрибутом aria-invalid​

Значение aria-invalid отображается напрямую. Значение true отображается как [invalid], а grammar и spelling отображаются как [invalid=grammar] и [invalid=spelling]. Значение false опускается.

<input type="text" aria-label="Email" aria-invalid="true" value="not-an-email">
aria snapshot
- textbox "Email" [invalid]: not-an-email
<input type="text" aria-label="Bio" aria-invalid="spelling">
aria snapshot
- textbox "Bio" [invalid=spelling]