スポンサーリンク

PlaywrightのariaSnapshotJSONとは?従来のARIA Snapshotとの違い

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入力欄のプレースホルダーなどの追加情報
refAI向けスナップショットの要素参照
cursorAI向けスナップショットでクリック可能な要素を示す情報
box要素の位置やサイズ

すべてのプロパティが、すべてのノードに含まれるわけではありません。

要素の種類や取得モード、指定したオプションによって含まれる情報は異なります。

例えば、ref はAI向けモードで利用される要素参照です。また、box は boxes オプションを有効にした場合に含まれます。

ariaSnapshotJSONのオプション

ariaSnapshotJSON() では、取得するスナップショットを調整するためのオプションを指定できます。

主なオプションは次のとおりです。

オプション内容
modeスナップショットの取得モード
depth取得する階層の深さ
boxes要素の位置・サイズ情報を含めるか
timeout処理のタイムアウト
signalAbortSignalによる処理のキャンセル

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 TestingARIA 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形式でプログラムから扱うかによって、用途に応じて使い分けられます。

参考資料