PlaywrightのARIAスナップショットで画面構造を比べる方法
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つあり、その下に見出し、お知らせの件数、入力欄、チェックボックス、ボタンが並びます。
<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() で文字列として取り出せます。
test('ページの ARIA スナップショットを表示する', async ({ page }) => {
await page.goto('/');
console.log(await page.locator('body').ariaSnapshot());
});
出力は次のとおりです。
- 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 が今のページからテンプレートを作ります。
// 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)を付けて実行しました。
npx playwright test tests/login.spec.ts --update-snapshots
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 で取り込む形です。中身は次のとおりでした。
@@ -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つのページを順に比べています。
for (const path of ['/styled', '/renamed', '/level', '/extra']) {
test(`${path} を元の構造と比べる`, async ({ page }) => {
await page.goto(path);
await expect(page.locator('body')).toMatchAriaSnapshot(LOGIN);
});
}
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 の差分です。
- Expected - 1
+ Received + 1
@@ -14,6 +14,6 @@
- textbox "メールアドレス"
- text: パスワード
- textbox "パスワード"
- checkbox "ログイン状態を保持する" [checked]
- text: ログイン状態を保持する
- - button "ログイン"
+ - button "サインイン"
見出しを <h2> に変えた /level では、[level=1] が [level=2] に変わった1行だけが差分に出ました。
- - heading "ログイン" [level=1]
+ - heading "ログイン" [level=2]
メニューのリンクを足した /extra が通ったのは、比べ方の既定が「テンプレートに書いた子要素が、その順番でそろっていれば通る」だからです。公式ドキュメントでは、この既定を contain と呼んでいます。テンプレートにない要素が増えても、失敗しません。
必要なところだけを比べる
画面全体を毎回比べると、関係のない変更でもテストが失敗します。テンプレートは、確かめたい部分だけに絞って書けます。以下のテストでは、ロケーターを body ではなく main や nav にして、比べる範囲を狭めています。
変わる数字は正規表現にする
お知らせの件数のように、表示のたびに変わる文字は、/…/ で囲んで正規表現にできます。件数が3件の元のページと、12件にした /count の両方で、次のテンプレートが通りました。
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] も省けば、チェックの有無は比べません。
test('ボタンの文言は問わない', async ({ page }) => {
await page.goto('/renamed');
await expect(page.getByRole('main')).toMatchAriaSnapshot(`
- heading "ログイン" [level=1]
- checkbox "ログイン状態を保持する"
- button
`);
});
要素が増えたことも失敗にする
メニューの項目が勝手に増えていないことまで確かめたいときは、/children: equal を書きます。子要素がテンプレートとちょうど同じでないと失敗します。
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);
});
}
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 で終わるファイル名を渡します。
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.」というエラーで失敗し、ファイルが作られました。中身は次のとおりです。
- main:
- heading "ログイン" [level=1]
- paragraph: 未読のお知らせが 3 件あります
- text: メールアドレス
- textbox "メールアドレス"
- text: パスワード
- textbox "パスワード"
- checkbox "ログイン状態を保持する" [checked]
- text: ログイン状態を保持する
- button "ログイン"
2回目の実行では、このファイルと比べて通りました。保存先は、テストファイルの隣の tests/file.spec.ts-snapshots/ です。この場所は、設定の snapshotPathTemplate などで変えられます。
画面全体を body で比べるテストは、まず空のテンプレートから作り、パッチを読んでから取り込みます。そのうえで、変わってよい部分は正規表現にするか省き、増えては困る部分にだけ /children: equal を書くと、見た目の手直しでは壊れず、構造の変化だけを拾うテストになります。





