メインコンテンツにスキップ

スナップショットテスト

概要​

Playwrightのスナップショットテストを使用すると、ページのアクセシビリティツリーを事前定義されたスナップショットテンプレートと比較してアサートできます。

await page.goto('https://playwright.dokyumento.jp/');
await expect(page.getByRole('banner')).toMatchAriaSnapshot(`
  - banner:
    - heading /Playwright enables reliable end-to-end/ [level=1]
    - link "Get started"
    - link "Star microsoft/playwright on GitHub"
    - link /[\\d]+k\\+ stargazers on GitHub/
`);

アサーションテストとスナップショットテスト​

スナップショットテストとアサーションテストは、テスト自動化において異なる目的を果たします。

アサーションテスト​

アサーションテストは、要素やコンポーネントに関する特定の値や条件をアサートする、的を絞ったアプローチです。たとえば、Playwrightでは、expect(locator).toHaveText()は、要素に期待されるテキストが含まれていることを検証し、expect(locator).toHaveValue()は、入力フィールドに期待される値があることを確認します。アサーションテストは具体的で、一般的に要素またはプロパティの現在の状態を、期待される事前定義された状態と比較してチェックします。これらは、予測可能で単一値のチェックには適していますが、より広範な構造やバリエーションをテストする際にはスコープが限られます。

利点

  • 明瞭性: テストの意図が明確で理解しやすい。
  • 特異性: テストは機能の特定の側面に焦点を当て、無関係な変更に対してより堅牢にします。
  • デバッグ: 失敗は的を絞ったフィードバックを提供し、問題のある側面を直接指摘します。

欠点

  • 複雑な出力に対する冗長性: 複雑なデータ構造や大規模な出力に対するアサーションの記述は、煩わしくエラーが発生しやすい場合があります。
  • メンテナンスオーバーヘッド: コードが進化するにつれて、アサーションを手動で更新するのに時間がかかる場合があります。

スナップショットテスト​

スナップショットテストは、特定の時点での要素、コンポーネント、またはデータの全体の状態の「スナップショット」または表現をキャプチャし、それを将来の比較のために保存します。テストを再実行すると、現在の状態がスナップショットと比較され、違いがある場合はテストが失敗します。このアプローチは、複雑または動的な構造に対して特に役立ち、手動で各詳細をアサートするには時間がかかりすぎます。スナップショットテストはアサーションテストよりも広範で全体的であり、時間の経過とともに発生するより複雑な変更を追跡できます。

利点

  • 複雑な出力を簡素化: たとえば、UIコンポーネントのレンダリングされた出力をテストすることは、従来のアサーションでは面倒です。スナップショットは、比較しやすいように出力全体をキャプチャします。
  • 迅速なフィードバックループ: 開発者は、意図しない出力の変更を簡単に発見できます。
  • 一貫性を促進: コードが進化するにつれて、出力の一貫性を維持するのに役立ちます。

欠点

  • 過度の依存: 変更を完全に理解せずにスナップショットへの変更を受け入れる誘惑に駆られ、バグを隠してしまう可能性があります。
  • 粒度: 違いが発生した場合、特に軽微な変更が出力のかなりの部分に影響を与える場合、大きなスナップショットを解釈するのが難しい場合があります。
  • 適合性: 出力が頻繁または予測不可能に変化する非常に動的なコンテンツには理想的ではありません。

使用するタイミング​

  • スナップショットテストは次の場合に理想的です。
    • ページ全体およびコンポーネントのUIテスト。
    • 複雑なUIコンポーネントの広範な構造チェック。
    • 構造がほとんど変化しない出力の回帰テスト。
  • アサーションテストは次の場合に理想的です。
    • コアロジックの検証。
    • 計算値のテスト。
    • 正確な条件を必要とするきめ細かいテスト。

広範な構造チェックにはスナップショットテストを、特定の機能にはアサーションテストを組み合わせることで、バランスの取れたテスト戦略を実現できます。

Aria スナップショット​

Playwrightでは、ARIAスナップショットはページのアクセシビリティツリーのYAML表現を提供します。これらのスナップショットは保存され、後で比較して、ページ構造が一貫しているか、定義された期待を満たしているかを確認できます。

YAML形式は、ページのアクセス可能な要素の階層構造を記述し、ロール、属性、値、テキストコンテンツを詳細に示します。構造はツリーのような構文に従い、各ノードはアクセス可能な要素を表し、インデントはネストされた要素を示します。

ツリー内の各アクセス可能な要素はYAMLノードとして表されます。

- role "name" [attribute=value]
  • role: 要素のARIAまたはHTMLロールを指定します (例: heading, list, listitem, button)。
  • "name": 要素のアクセス可能な名前。引用符で囲まれた文字列は厳密な値を示し、/patterns/は正規表現に使用されます。
  • [attribute=value]: 角括弧で囲まれた属性と値は、checked、disabled、expanded、level、pressed、selectedなどの特定のARIA属性を表します。

これらの値はARIA属性から派生するか、HTMLセマンティクスに基づいて計算されます。ページのアクセシビリティツリー構造を調べるには、Chrome DevToolsのアクセシビリティタブを使用してください。

スナップショットマッチング​

Playwrightのexpect(locator).toMatchAriaSnapshot()アサーションメソッドは、ロケータスコープのアクセス可能な構造を事前定義されたARIAスナップショットテンプレートと比較し、ページの現在の状態をテスト要件に対して検証するのに役立ちます。

次のDOMの場合

<h1>title</h1>

次のスナップショットテンプレートを使用して一致させることができます。

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

一致する場合、スナップショットテンプレートはページの現在のアクセシビリティツリーと比較されます。

  • ツリー構造がテンプレートと一致すればテストは合格し、一致しない場合はテストが失敗し、期待されるアクセシビリティ状態と実際の状態の不一致を示します。
  • 比較は大文字と小文字を区別し、空白を畳み込むため、インデントと改行は無視されます。
  • 比較は順序を区別するため、スナップショットテンプレート内の要素の順序はページのアクセシビリティツリー内の順序と一致する必要があります。

部分一致​

属性やアクセス可能な名前を省略することでノードの部分一致を実行でき、厳密な一致を必要とせずにアクセシビリティツリーの特定の部分を検証できます。この柔軟性は、動的または関連性のない属性に役立ちます。

<button>Submit</button>

ARIAスナップショット

- button

この例では、ボタンロールは一致しますが、アクセス可能な名前（"Submit"）は指定されていないため、ボタンのラベルに関係なくテストは合格します。

checkedやdisabledなどのARIA属性を持つ要素の場合、これらの属性を省略することで部分一致が可能になり、ロールと階層のみに焦点を当てることができます。

<input type="checkbox" checked>

部分一致のARIAスナップショット

- checkbox

この部分一致では、checked属性は無視されるため、チェックボックスの状態に関係なくテストは合格します。

同様に、特定のリスト項目やネストされた要素を省略することで、リストまたはグループ内の子を部分的に一致させることができます。

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

部分一致のARIAスナップショット

- list
  - listitem: Feature B

部分一致により、特定のコンテンツや属性を強制することなく、重要なページ構造を検証する柔軟なスナップショットテストを作成できます。

厳密なマッチング​

デフォルトでは、子のサブセットを含むテンプレートが一致します。

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

部分一致のARIAスナップショット

- list
  - listitem: Feature B

/childrenプロパティを使用して、子要素の照合方法を制御できます。

  • contain (デフォルト): 指定されたすべての子が順番に存在する場合に一致します。
  • equal: 子が指定されたリストと順番に正確に一致する場合に一致します。
  • deep-equal: ネストされた子を含め、子が指定されたリストと順番に正確に一致する場合に一致します。
<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

機能Cがテンプレートにないため、ARIAスナップショットは失敗します。

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

正規表現によるマッチング​

正規表現は、動的または可変テキストを持つ要素に対して柔軟なマッチングを可能にします。アクセス可能な名前とテキストは正規表現パターンをサポートできます。

<h1>Issues 12</h1>

正規表現によるARIAスナップショット

- heading /Issues \d+/

スナップショットの生成​

PlaywrightでARIAスナップショットを作成することは、アプリケーションの構造を確保し、維持するのに役立ちます。テスト設定とワークフローに応じて、さまざまな方法でスナップショットを生成できます。

Playwrightコードジェネレーターでのスナップショット生成​

Playwrightのコードジェネレーターを使用している場合、ARIAスナップショットの生成はインタラクティブなインターフェースで効率化されます。

  • 「スナップショットをアサート」アクション: コードジェネレーターでは、「スナップショットをアサート」アクションを使用して、選択した要素のスナップショットアサーションを自動的に作成できます。これは、記録されたテストフローの一部としてARIAスナップショットをキャプチャする迅速な方法です。
  • 「Ariaスナップショット」タブ: コードジェネレーターインターフェース内の「Ariaスナップショット」タブは、選択したロケーターのAriaスナップショットを視覚的に表現し、要素の役割、属性、およびアクセス可能な名前を探索、検査、検証して、スナップショットの作成とレビューを支援します。

@playwright/testと--update-snapshotsフラグによるスナップショットの更新​

Playwrightテストランナー（@playwright/test）を使用している場合、--update-snapshotsフラグ（略して-u）を使用してスナップショットを自動的に更新できます。

--update-snapshotsフラグを付けてテストを実行すると、一致しなかったスナップショットが更新されます。一致するスナップショットは更新されません。

npx playwright test --update-snapshots

スナップショットの更新は、アプリケーション構造の変更により新しいスナップショットがベースラインとして必要になる場合に役立ちます。Playwrightは、スナップショットを撮る前にページが落ち着いていることを確認するために、テストランナー構成で指定された最大期待タイムアウトまで待機することに注意してください。スナップショットの生成中にテストがタイムアウトになった場合は、--timeoutを調整する必要があるかもしれません。

スナップショット生成のための空のテンプレート​

アサーションでテンプレートとして空の文字列を渡すと、スナップショットがオンザフライで生成されます。

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

Playwrightは、スナップショットを撮る前にページが落ち着いていることを確認するために、テストランナー構成で指定された最大期待タイムアウトまで待機することに注意してください。スナップショットの生成中にテストがタイムアウトになった場合は、--timeoutを調整する必要があるかもしれません。

スナップショットパッチファイル​

スナップショットを更新すると、Playwrightは差分をキャプチャするパッチファイルを作成します。これらのパッチファイルは、レビュー、適用、ソース管理へのコミットが可能で、チームは時間の経過に伴う構造変更を追跡し、更新がアプリケーション要件と一致していることを確認できます。

ソースコードの更新方法は、--update-source-methodフラグを使用して変更できます。いくつかのオプションがあります。

  • "patch" (デフォルト): git applyを使用してソースコードに適用できる統合差分ファイルを生成します。
  • "3way": ソースコードにマージ競合マーカーを生成し、変更を受け入れるかどうかを選択できます。
  • "overwrite": 新しいスナップショット値でソースコードを上書きします。
npx playwright test --update-snapshots --update-source-method=3way

別ファイルとしてのスナップショット​

スナップショットを別のファイルに保存するには、.aria.ymlファイル拡張子を指定して、nameオプションを付けてtoMatchAriaSnapshotメソッドを使用します。

await expect(page.getByRole('main')).toMatchAriaSnapshot({ name: 'main.aria.yml' });

デフォルトでは、テストファイルexample.spec.tsからのスナップショットはexample.spec.ts-snapshotsディレクトリに配置されます。スナップショットはブラウザ間で同じであるべきなので、複数のブラウザでテストする場合でも1つのスナップショットのみが保存されます。必要に応じて、次の構成を使用してスナップショットパステンプレートをカスタマイズできます。

export default defineConfig({
  expect: {
    toMatchAriaSnapshot: {
      pathTemplate: '__snapshots__/{testFilePath}/{arg}{ext}',
    },
  },
});

Locator.ariaSnapshotメソッドの使用​

locator.ariaSnapshot()メソッドを使用すると、ロケーターのスコープ内にあるアクセス可能な要素のYAML表現をプログラムで作成できます。これは、テスト実行中にスナップショットを動的に生成する場合に特に役立ちます。

例:

const snapshot = await page.locator('body').ariaSnapshot();
console.log(snapshot);

このコマンドは、指定されたロケーターのスコープ内のariaスナップショットをYAML形式で出力し、必要に応じて検証または保存できます。

アクセシビリティツリーの例​

レベル属性を持つ見出し​

見出しには、見出しレベルを示すlevel属性を含めることができます。

<h1>Title</h1>
<h2>Subtitle</h2>

ARIAスナップショット

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

テキストノード​

独立したテキスト要素または説明的なテキスト要素はテキストノードとして表示されます。

<div>Sample accessible name</div>

ARIAスナップショット

- text: Sample accessible name

インラインの複数行テキスト​

段落などの複数行テキストは、ariaスナップショットで正規化されます。

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

ARIAスナップショット

- paragraph: Line 1 Line 2

リンクは、擬似要素からのテキストまたは合成されたコンテンツを表示します。

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

ARIAスナップショット

- link "Read more about Accessibility"

テキストボックス​

タイプtextの入力要素は、value属性の内容を表示します。

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

ARIAスナップショット

- textbox: Enter your name

項目を含むリスト​

順序付きリストと順序なしリストには、そのリスト項目が含まれます。

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

ARIAスナップショット

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

グループ化された要素​

グループは、サマリーコンテンツを持つ<details>要素などのネストされた要素をキャプチャします。

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

ARIAスナップショット

- group: Summary

属性と状態​

checked、disabled、expanded、level、pressed、selectedなどのよく使用されるARIA属性は、コントロールの状態を表します。

checked属性を持つチェックボックス​

<input type="checkbox" checked>

ARIAスナップショット

- checkbox [checked]

pressed属性を持つボタン​

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

ARIAスナップショット

- button "Toggle" [pressed=true]