PlaywrightのARIAスナップショットで画面構造を比べる方法

​​Playwright​E2Eテスト,TypeScript,アクセシビリティ

Playwright の toMatchAriaSnapshot() を使うと、ページの見出し、入力欄、ボタン、リンクといった構造を、YAML で書いたテンプレートとまとめて比べられます。CSS を変えただけでは失敗せず、ボタンの文言や見出しのレベルが変わったときに失敗するので、デザインの手直しのたびに壊れない回帰テスト(リグレッションテスト)に使えます。比べているのはアクセシビリティツリーなので、スクリーンリーダーに伝わる内容が変わっていないかの確認にもなります。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。テストは TypeScript で書き、ブラウザは Chromium(ヘッドレス)だけで動かしました。テスト用のページは Node.js の http モジュールで 127.0.0.1 から返しています。失敗するテストを早く終わらせるため、設定で expect の待ち時間を2秒にしました。codegen(操作を記録してテストを作る機能)でのスナップショット作成、Firefox と WebKit は試していません。

テストに使うページ

次のようなログイン画面を用意しました。上にメニューのリンクが2つあり、その下に見出し、お知らせの件数、入力欄、チェックボックス、ボタンが並びます。

html
<header>
  <nav aria-label="メイン">
    <ul>
      <li><a href="/">ホーム</a></li>
      <li><a href="/help">ヘルプ</a></li>
    </ul>
  </nav>
</header>
<main>
  <h1>ログイン</h1>
  <p>未読のお知らせが 3 件あります</p>
  <form>
    <label>メールアドレス <input type="email" name="email"></label>
    <label>パスワード <input type="password" name="password"></label>
    <label><input type="checkbox" name="remember" checked> ログイン状態を保持する</label>
    <button type="submit">ログイン</button>
  </form>
</main>

このページの構造がどう見えるかは、locator.ariaSnapshot() で文字列として取り出せます。

ts
test('ページの ARIA スナップショットを表示する', async ({ page }) => {
  await page.goto('/');
  console.log(await page.locator('body').ariaSnapshot());
});

出力は次のとおりです。

yaml
- banner:
  - navigation "メイン":
    - list:
      - listitem:
        - link "ホーム":
          - /url: /
      - listitem:
        - link "ヘルプ":
          - /url: /help
- main:
  - heading "ログイン" [level=1]
  - paragraph: 未読のお知らせが 3 件あります
  - text: メールアドレス
  - textbox "メールアドレス"
  - text: パスワード
  - textbox "パスワード"
  - checkbox "ログイン状態を保持する" [checked]
  - text: ログイン状態を保持する
  - button "ログイン"

1行が1つの要素で、- 役割 "名前" [属性] の形になっています。- /url: / の行は要素ではなく、すぐ上のリンクの行き先です。<header> は banner、<h1> は heading と [level=1] のように、HTML のタグではなく役割(role)で表されます。<label> で囲んだ入力欄には、ラベルの文字が名前として付いています。逆に、クラス名や色、<div> の入れ子は出てきません。

空のテンプレートからスナップショットを作る

テンプレートを手で書く必要はありません。toMatchAriaSnapshot('') のように空の文字列を渡して実行すると、Playwright が今のページからテンプレートを作ります。

ts
// tests/login.spec.ts
import { test, expect } from '@playwright/test';

test('ログイン画面の構造', async ({ page }) => {
  await page.goto('/');
  await expect(page.locator('body')).toMatchAriaSnapshot('');
});

--update-snapshots(短く書くと -u)を付けて実行しました。

bash
npx playwright test tests/login.spec.ts --update-snapshots
text
Running 1 test using 1 worker

  ✓  1 tests/login.spec.ts:3:1 › ログイン画面の構造 (2.1s)

New baselines created for:

  tests/login.spec.ts

  git apply test-results/rebaselines.patch

  1 passed (2.9s)

テストファイルはこの時点では書き換わらず、test-results/rebaselines.patch に差分が書き出されます。既定ではパッチを作り、git apply で取り込む形です。中身は次のとおりでした。

diff
@@ -2,5 +2,25 @@
 
 test('ログイン画面の構造', async ({ page }) => {
   await page.goto('/');
-  await expect(page.locator('body')).toMatchAriaSnapshot('');
+  await expect(page.locator('body')).toMatchAriaSnapshot(`
+    - banner:
+      - navigation "メイン":
+        - list:
+          - listitem:
+            - link "ホーム":
+              - /url: /
+          - listitem:
+            - link "ヘルプ":
+              - /url: /help
+    - main:
+      - heading "ログイン" [level=1]
+      - paragraph: 未読のお知らせが 3 件あります
+      - text: メールアドレス
+      - textbox "メールアドレス"
+      - text: パスワード
+      - textbox "パスワード"
+      - checkbox "ログイン状態を保持する" [checked]
+      - text: ログイン状態を保持する
+      - button "ログイン"
+  `);
 });

git apply test-results/rebaselines.patch で取り込んでから同じテストを実行すると、137ミリ秒で通りました。テンプレートを作る実行のほうは、2.1秒かかっています。公式ドキュメントによると、ページが落ち着くのを待つため、expect の待ち時間の上限まで待ってからスナップショットを取ります。この検証では上限を2秒にしていたので、その2秒と合います。

--update-snapshots を付けずに実行した場合も、「New baselines created for:」と git apply test-results/rebaselines.patch の案内が出ました。ただし、テストは「A snapshot is not provided, generating new baseline.」というエラーで失敗扱いになります。

注意

パッチは中身を読んでから取り込みます。テンプレートは今の画面をそのまま写したものなので、画面に不具合があれば、それも正しい状態として記録されます。

見た目を変えても通り、文言や見出しのレベルを変えると失敗する

作ったテンプレートを、元のページから一部だけ変えた4つのページと比べました。

  • /styled:クラス、色、<div> の入れ子だけを変えた
  • /renamed:ボタンの文言を「ログイン」から「サインイン」に変えた
  • /level:見出しを <h1> から <h2> に変えた
  • /extra:メニューに「料金」のリンクを足した

/styled は、見た目がかなり変わっています。

上に飾りのない元のログイン画面、下に水色のメニューと白いカード、ピンクのボタンに変えたログイン画面を並べたスクリーンショット
元のページ(上)と、見た目だけ変えたページ(下)

テストでは、上で作ったテンプレートを LOGIN という定数に入れ、4つのページを順に比べています。

ts
for (const path of ['/styled', '/renamed', '/level', '/extra']) {
  test(`${path} を元の構造と比べる`, async ({ page }) => {
    await page.goto(path);
    await expect(page.locator('body')).toMatchAriaSnapshot(LOGIN);
  });
}
text
Running 4 tests using 1 worker

  ✓  1 tests/compare.spec.ts:27:3 › /styled を元の構造と比べる (133ms)
  ✘  2 tests/compare.spec.ts:27:3 › /renamed を元の構造と比べる (2.1s)
  ✘  3 tests/compare.spec.ts:27:3 › /level を元の構造と比べる (2.1s)
  ✓  4 tests/compare.spec.ts:27:3 › /extra を元の構造と比べる (142ms)

見た目だけを変えた /styled は通りました。失敗した2つは、エラーにテンプレートと実際の構造の差分が出ます。ボタンの文言を変えた /renamed の差分です。

diff
    - Expected  - 1
    + Received  + 1

    @@ -14,6 +14,6 @@
        - textbox "メールアドレス"
        - text: パスワード
        - textbox "パスワード"
        - checkbox "ログイン状態を保持する" [checked]
        - text: ログイン状態を保持する
    -   - button "ログイン"
    +   - button "サインイン"

見出しを <h2> に変えた /level では、[level=1] が [level=2] に変わった1行だけが差分に出ました。

diff
    -   - heading "ログイン" [level=1]
    +   - heading "ログイン" [level=2]

メニューのリンクを足した /extra が通ったのは、比べ方の既定が「テンプレートに書いた子要素が、その順番でそろっていれば通る」だからです。公式ドキュメントでは、この既定を contain と呼んでいます。テンプレートにない要素が増えても、失敗しません。

必要なところだけを比べる

画面全体を毎回比べると、関係のない変更でもテストが失敗します。テンプレートは、確かめたい部分だけに絞って書けます。以下のテストでは、ロケーターを body ではなく main や nav にして、比べる範囲を狭めています。

変わる数字は正規表現にする

お知らせの件数のように、表示のたびに変わる文字は、/…/ で囲んで正規表現にできます。件数が3件の元のページと、12件にした /count の両方で、次のテンプレートが通りました。

ts
test('お知らせの件数は正規表現で比べる', async ({ page }) => {
  for (const path of ['/', '/count']) {
    await page.goto(path);
    await expect(page.getByRole('main')).toMatchAriaSnapshot(`
      - heading "ログイン" [level=1]
      - paragraph: /未読のお知らせが \\d+ 件あります/
    `);
  }
});

JavaScript のテンプレート文字列の中に書いているので、\d は \\d と書きます。

名前や属性を省く

名前や [checked] のような属性を書かなければ、その部分は比べません。次のテンプレートは、ボタンの文言を変えた /renamed でも通りました。公式ドキュメントのとおり、チェックボックスの [checked] も省けば、チェックの有無は比べません。

ts
test('ボタンの文言は問わない', async ({ page }) => {
  await page.goto('/renamed');
  await expect(page.getByRole('main')).toMatchAriaSnapshot(`
    - heading "ログイン" [level=1]
    - checkbox "ログイン状態を保持する"
    - button
  `);
});

要素が増えたことも失敗にする

メニューの項目が勝手に増えていないことまで確かめたいときは、/children: equal を書きます。子要素がテンプレートとちょうど同じでないと失敗します。

ts
const MENU = `
  - list:
    - /children: equal
    - listitem:
      - link "ホーム"
    - listitem:
      - link "ヘルプ"
`;

for (const path of ['/', '/extra']) {
  test(`${path} のメニューの項目が増えていないことを確かめる`, async ({ page }) => {
    await page.goto(path);
    await expect(page.getByRole('navigation', { name: 'メイン' })).toMatchAriaSnapshot(MENU);
  });
}
text
Running 4 tests using 1 worker

  ✓  1 tests/partial.spec.ts:3:1 › お知らせの件数は正規表現で比べる (198ms)
  ✓  2 tests/partial.spec.ts:13:1 › ボタンの文言は問わない (91ms)
  ✓  3 tests/partial.spec.ts:32:3 › / のメニューの項目が増えていないことを確かめる (100ms)
  ✘  4 tests/partial.spec.ts:32:3 › /extra のメニューの項目が増えていないことを確かめる (2.1s)

元のページは通り、「料金」のリンクを足した /extra は失敗しました。前の節では、同じ /extra が既定の比べ方で通っていました。/children: equal を書くと、テンプレートにないリンクが増えたことで失敗します。

スナップショットを別のファイルに置く

テンプレートが長くなるときは、テストのコードとは別の .aria.yml ファイルに置けます。name に .aria.yml で終わるファイル名を渡します。

ts
test('ログインのフォームを別ファイルの内容と比べる', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'login-main.aria.yml' });
});

ファイルがない状態で1回目を実行すると、「A snapshot doesn't exist at tests/file.spec.ts-snapshots/login-main.aria.yml, writing actual.」というエラーで失敗し、ファイルが作られました。中身は次のとおりです。

yaml
- main:
  - heading "ログイン" [level=1]
  - paragraph: 未読のお知らせが 3 件あります
  - text: メールアドレス
  - textbox "メールアドレス"
  - text: パスワード
  - textbox "パスワード"
  - checkbox "ログイン状態を保持する" [checked]
  - text: ログイン状態を保持する
  - button "ログイン"

2回目の実行では、このファイルと比べて通りました。保存先は、テストファイルの隣の tests/file.spec.ts-snapshots/ です。この場所は、設定の snapshotPathTemplate などで変えられます。

ポイント

画面全体を body で比べるテストは、まず空のテンプレートから作り、パッチを読んでから取り込みます。そのうえで、変わってよい部分は正規表現にするか省き、増えては困る部分にだけ /children: equal を書くと、見た目の手直しでは壊れず、構造の変化だけを拾うテストになります。

​Posted by 86