PlaywrightのariaSnapshotJSONとは?従来のARIA Snapshotとの違い
Playwrightには、Webページのアクセシビリティ情報を取得できる「ARIA Snapshot」という機能があります。
従来の ariaSnapshot() は、アクセシビリティツリーの情報をYAML形式の文字列として取得するAPIです。
これに対して、Playwright 1.63で追加された ariaSnapshotJSON() は、同じツリー構造をJSON形式の値として取得できます。
JSON形式で取得できるため、JavaScriptやTypeScriptからアクセシビリティ情報をプログラムで処理したい場合に利用できます。
この記事では、Playwrightの ariaSnapshotJSON() の概要や、従来の ariaSnapshot() との違い、取得できる情報やオプションについて紹介します。
PlaywrightのariaSnapshotJSONとは?
ariaSnapshotJSON() は、Webページまたは指定した要素のARIA SnapshotをJSON形式で取得するAPIです。
Playwright 1.63で追加されました。
従来の ariaSnapshot() では、取得した情報はYAML形式の文字列として返されます。
一方、ariaSnapshotJSON() では、JSON値として取得できます。
Locatorを利用する場合は、次のように呼び出します。
const snapshot = await page.getByRole('list').ariaSnapshotJSON();
Page全体のスナップショットを取得する場合は、次のように記述します。
const snapshot = await page.ariaSnapshotJSON();
Locatorを利用した場合は指定した要素を対象とし、Pageを利用した場合はページ全体を対象とします。
取得した値は、JavaScriptの配列やオブジェクトとして扱えるため、プログラムから情報を参照したり加工したりできます。
ariaSnapshot()との違い
ariaSnapshot() と ariaSnapshotJSON() の主な違いは、取得結果の形式です。
| 比較項目 | ariaSnapshot() | ariaSnapshotJSON() |
|---|---|---|
| 取得形式 | YAML形式の文字列 | JSON形式の値 |
| 戻り値 | Promise<string> | Promise<Serializable> |
| 主な用途 | スナップショットの確認・比較 | JSONとしての情報取得 |
| AI向けモード | 対応 | 対応 |
追加されたバージョンには注意が必要です。
| API | 追加されたバージョン |
|---|---|
| Locator.ariaSnapshot() | v1.49 |
| Page.ariaSnapshot() | v1.59 |
| Locator.ariaSnapshotJSON() | v1.63 |
| Page.ariaSnapshotJSON() | v1.63 |
どちらのAPIも、基本的には同じアクセシビリティツリーを取得します。
JSON形式にしただけで、別の種類のアクセシビリティ情報が追加されるわけではありません。
YAML形式のスナップショットをそのまま確認したい場合は ariaSnapshot()、JSON形式でプログラムから処理したい場合は ariaSnapshotJSON() が選択肢になります。
ariaSnapshotJSONで取得できる情報
ariaSnapshotJSON() では、アクセシビリティツリーを構成するノードがJSON形式で返されます。
Locator版の戻り値はノードのリストで、各ノードはオブジェクトとして表現されます。
主なプロパティは次のとおりです。
| プロパティ | 内容 |
|---|---|
| role | 要素のARIAロール |
| name | アクセシブルネーム |
| text | テキスト情報 |
| children | 子ノードやテキスト断片 |
| checked | チェック状態 |
| disabled | 無効状態 |
| expanded | 展開状態 |
| active | アクティブ状態 |
| invalid | 入力値などの妥当性に関する状態 |
| level | 階層レベル |
| pressed | 押下状態 |
| selected | 選択状態 |
| url | リンクのURLなどの追加情報 |
| placeholder | 入力欄のプレースホルダーなどの追加情報 |
| ref | AI向けスナップショットの要素参照 |
| cursor | AI向けスナップショットでクリック可能な要素を示す情報 |
| box | 要素の位置やサイズ |
すべてのプロパティが、すべてのノードに含まれるわけではありません。
要素の種類や取得モード、指定したオプションによって含まれる情報は異なります。
例えば、ref はAI向けモードで利用される要素参照です。また、box は boxes オプションを有効にした場合に含まれます。
ariaSnapshotJSONのオプション
ariaSnapshotJSON() では、取得するスナップショットを調整するためのオプションを指定できます。
主なオプションは次のとおりです。
| オプション | 内容 |
|---|---|
| mode | スナップショットの取得モード |
| depth | 取得する階層の深さ |
| boxes | 要素の位置・サイズ情報を含めるか |
| timeout | 処理のタイムアウト |
| signal | AbortSignalによる処理のキャンセル |
mode
mode には、default と ai を指定できます。
default は通常のスナップショットを取得するモードです。
ai はAIでの利用に適したスナップショットを取得するモードです。
AI向けモードでは、次のような特徴があります。
- 要素参照を表す
[ref=e2]などの情報が含まれる - iframe内のスナップショットも取得対象になる
- 子要素の表示内容と重複する名前などが省略される場合がある
Locator版のAI向けモードでは、対象Locatorに一致する要素がない場合、待機せずにエラーになります。
通常のスナップショットを取得したい場合は、default を利用します。
depth
depth は、スナップショットに含める階層の深さを制限するオプションです。
例えば、複雑なページのアクセシビリティツリーを取得するときに、必要な階層までに制限できます。
取得する情報の範囲を調整したい場合に利用できます。
boxes
boxes を true にすると、各要素の位置やサイズを表す情報を含められます。
取得される box には、次の情報が含まれます。
- x:X座標
- y:Y座標
- width:幅
- height:高さ
座標はビューポートを基準としたCSSピクセルです。位置情報は Element.getBoundingClientRect() による値に対応します。
この情報は、画面上の要素の位置やサイズを把握したい場合などに利用できます。
既定値は false です。
timeout
timeout は、処理の最大待機時間をミリ秒単位で指定するオプションです。
既定値は0で、タイムアウトは無効です。
ただし、設定ファイルの actionTimeout や page.setDefaultTimeout()、browserContext.setDefaultTimeout() によって既定のタイムアウトを変更できます。
タイムアウトの動作を確認する場合は、これらの設定も考慮する必要があります。
signal
signal には AbortSignal を指定できます。
処理をキャンセルしたい場合に利用できます。
AbortSignalによって処理が中断された場合、操作はエラーになります。
なお、signal オプションはv1.62で追加されています。
ariaSnapshotJSONとVisual Regression Testingの違い
Playwrightでは、画面の見た目の変更を確認するVisual Regression Testingを利用できます。
また、ARIA Snapshotを使ってアクセシビリティツリーの変更を確認することもできます。
それぞれの違いは次のとおりです。
| 比較項目 | Visual Regression Testing | ARIA Snapshot |
|---|---|---|
| 比較対象 | 画面の画像 | アクセシビリティツリー |
| 確認できる内容 | 色、配置、サイズ、見た目 | ロール、名前、テキスト、状態 |
| 主な用途 | UIの見た目の変更確認 | アクセシビリティ構造の変更確認 |
例えば、ボタンの位置や色が変わった場合はVisual Regression Testingが適しています。
一方、ボタンのアクセシブルネームやロールが変更された場合はARIA Snapshotで確認できます。
Playwrightには toMatchAriaSnapshot() というアサーションAPIもあります。期待するARIA Snapshotとの比較に利用できます。
ただし、ariaSnapshotJSON() 自体が自動的に差分を検出する機能ではありません。
また、ARIA Snapshotだけで色のコントラストやキーボード操作など、すべてのアクセシビリティ上の問題を検出できるわけではありません。
まとめ
Playwright 1.63で追加された ariaSnapshotJSON() は、アクセシビリティツリーをJSON形式で取得できるAPIです。
従来の ariaSnapshot() はYAML形式の文字列を返しますが、ariaSnapshotJSON() ではJSON値として取得できます。
主なポイントは次のとおりです。
- Playwright 1.63で追加されたAPI
- アクセシビリティツリーをJSON形式で取得できる
- LocatorとPageの両方で利用できる
mode、depth、boxesなどのオプションに対応- AI向けモードでは要素参照などの情報も取得できる
- 取得したJSONをプログラムから処理しやすい
- API自体に自動的な差分検出機能はない
従来のYAML形式のスナップショットを利用するか、JSON形式でプログラムから扱うかによって、用途に応じて使い分けられます。
