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

Обзор​

С помощью тестирования снимков в 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/
`);

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

Тестирование снимков и тестирование с проверками решают разные задачи в автоматизации тестирования:

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

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

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

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

Недостатки

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

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

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

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

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

Недостатки

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

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

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

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

Снимки ARIA​

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

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

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

- role "name" [attribute=value]

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

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

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

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

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

<h1>title</h1>

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

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

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

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

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

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

<button>Submit</button>

- button

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

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

<input type="checkbox" checked>

- checkbox

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

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

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

- list
  - listitem: Feature B

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

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

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

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

- list
  - listitem: Feature B

Свойство /children позволяет управлять способом сопоставления дочерних элементов:

• contain (по умолчанию): сопоставление успешно, если все указанные дочерние элементы присутствуют в заданном порядке
• equal: сопоставление успешно, если дочерние элементы точно соответствуют указанному списку и его порядку
• deep-equal: сопоставление успешно, если дочерние элементы точно соответствуют указанному списку и его порядку, включая вложенные элементы

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

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

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

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

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

import { defineConfig } from '@playwright/test';

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

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

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

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

<h1>Issues 12</h1>

- 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.

При запуске тестов с флагом --update-snapshots обновляются снимки, которые не прошли сопоставление. Совпавшие снимки не обновляются.

npx playwright test --update-snapshots

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

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

Если передать в проверку пустую строку в качестве шаблона, снимок будет создан на лету:

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

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

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

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

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

• "patch" (по умолчанию): создаёт файл унифицированного различия, который можно применить к исходному коду с помощью 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>

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

Текстовые узлы​

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

<div>Sample accessible name</div>

- text: Sample accessible name

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

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

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

- paragraph: Line 1 Line 2

Ссылки​

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

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

- link "Read more about Accessibility":
    - /url: "#more-info"

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

<a href="https://www.youtube.com/channel/UC46Zj8pDH5tDosqm1gd7WTg">YouTube channel</a>

- link:
  - /url: /https://www.youtube.com/channel/.*/

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

Для элементов ввода типа text отображается содержимое их атрибута value.

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

- textbox: Enter your name

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

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

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

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

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

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

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

- group: Summary

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

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

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

<input type="checkbox" checked>

- checkbox [checked]

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

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

- 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">

- textbox "Email" [invalid]: not-an-email

<input type="text" aria-label="Bio" aria-invalid="spelling">

- textbox "Bio" [invalid=spelling]