Playwright

どのようなものか

Playwrightは、Microsoftによるウェブブラウザー自動操作用のオープン
ソースのフレームワークです。Chromium、Firefox、WebKitを、一つのプロ
グラミングインターフェースで扱います。その上に構築したテストランナー
がPlaywright
Testで、npmでは`@playwright/test`として公開されています。大半の人が
Playwrightという名前で指すのは、このランナーです。同じプロジェクト
は、テスト以外のスクリプト用のライブラリー、コマンドラインツール、AI
エージェント向けのMCPサーバー、Visual
Studio Codeの拡張機能も、すべてApache License 2.0で提供しています。

JavaScriptとTypeScript以外でも、同じブラウザー操作が使えます。Python
ではプロジェクトがpytestプラグインを勧め、JavaではJUnitなど任意のテ
ストフレームワークを使えます。.NET向けには、MSTest、NUnit、xUnit用の
基底クラスがあります。

`npx playwright
install`は、三つのエンジンについて専用のビルドをダウンロードします。
リリースごとにエンジンの版が進むため、アップグレード後には、コマンド
を再実行する必要があるかもしれません。すでにマシンへ入っているGoogle
ChromeやMicrosoft
Edgeも操作できます。既定では、ウィンドウを表示しないヘッドレスモード
でテストします。インストールガイドの例は、設定したブラウザープロジェ
クトを使い、三つのエンジンで並行してテストを実行します。これらのプロ
ジェクトがない場合、テストランナーの既定ブラウザーはChromiumです。各
テストには、新しいブラウザープロファイルに相当する、新しいブラウザー
コンテキストを用意します。そのため、あるテストのCookieやストレージ
は、次のテストへ引き継がれません。

テストは、人が行う手順のように読めます。

```js
import { test, expect } from "@playwright/test";

test("signing in opens the inbox", async ({ page }) => {
    await page.goto("https://example.com/sign-in");
    await page.getByLabel("Email").fill("reader@example.com");
    await page.getByRole("button", { name: "Sign in" }).click();
    await expect(page.getByRole("heading", { name: "Inbox" })).toBeVisible();
});
```

中心となる仕組みは二つあります。Playwrightは操作前に、その操作が可能
か検査し、すべての条件を満たすまで待ちます。クリックなら、ロケーター
が指す要素は、厳密に一つでなければなりません。その要素は、見えてい
て、安定している必要があります。安定とは、連続する少なくとも二つのア
ニメーションフレームで、境界ボックスが変わらないことです。さらに、別
の要素の下に隠れずクリックを受け取れ、有効な状態である必要がありま
す。制限時間内に条件を満たさなければ、操作は`TimeoutError`で終わりま
す。`await
expect(locator)`と書くアサーションも、条件を満たすか、既定で五秒のア
サーションの待機時間を超えるまで、要素を繰り返し取得します。

なぜ重要なのか

Playwrightを使うときは、どの動作を実ブラウザーで検査すべきか、そして
ビルド失敗の報告を信頼できるように、どう検査を作るかを決めます。ペー
ジが組み上がってからしか現れない欠陥があります。本来見せるはずのボタ
ンを隠すダイアログ、ある画面幅で入力欄を隠すレイアウト、あるエンジン
では動き、別のエンジンでは例外を出すスクリプトです。コードの一部分を
単独で動かすテストには、これらは見えません。

テストとページの処理が競合すると、ブラウザーテストの結果は不安定にな
ります。ページはデータを取得し、アニメーションを動かし、再描画しま
す。該当行が実行された途端にクリックするテストは、時には早過ぎます。
従来は固定時間だけ待つ方法が一般的でしたが、遅いマシンでは短過ぎ、速
いマシンでは時間を無駄にします。自動待機と再試行するアサーションは、
その待ち時間を、テストが実際に必要とする条件へ置き換えます。アサー
ションのガイドは、ウェブページは非同期に情報を表示するので、一度しか
検査しないアサーションは、不安定なテストにつながると明記しています。

次に決めるのは、テストが要素を探す方法です。ロケーターのガイドは、ま
ずユーザーに分かる属性を使い、特にロールによる検索を勧めます。アクセ
シブルな名前を指定した`getByRole`は、「ユーザーと支援技術がページを
どう認識するか」に最も近いからです。これには、副次的な利点もありま
す。「Sign
in」という名前のボタンをクリックするテストは、そのボタンが名前を失う
と失敗します。スクリーンリーダーのユーザーも、同じ欠陥に直面します。
一方で、ロールによる検索は「アクセシビリティー監査や適合性テストを置
き換えない」と、ガイドは説明しています。テストIDは代替策です。ガイド
はこれを最も変更に強い方法としつつ、「ユーザー向けではない」とも述べ
ています。すべてをIDで見つけるテストでは、訪問者の体験について確認で
きることが少なくなります。DOMは頻繁に変わるため、CSSやXPathのセレク
ターは推奨されていません。

代償は時間です。ブラウザーを起動してページを読み込むため、ブラウザー
テストは、プロジェクト内で最も遅い種類のテストになります。ビルドサー
バーで失敗したときは、トレースビューアーから調べられます。文書にある
設定例では、失敗したテストの最初の再試行でトレースを記録し、再試行回
数をCIでは二回、ローカルでは零回に設定しています。テストランナーの組
み込みの既定値では、トレースの記録も再試行も行いません。トレースで
は、各操作を順にたどり、操作の前後のページ、ネットワーク要求、コン
ソールを確認できます。

実際の活用例

あるプラットフォームでは、業務ロジックをデータベース内に置いており、
四つの層にまたがるテスト一式を構築しました。記録された課題は、「すべ
てを外側からブラウザー経由で検査するのではなく」、各層の動作を、実際
にその動作が存在する場所で検査することでした。Go
APIには981個のテスト関数があります。データベースには494個の振る舞い
を検証するテストファイルがあり、ストアド関数を、その上の三層のアプリ
ケーション経由ではなく、データベース内で検査します。フロントエンドに
は、VitestとPlaywrightを合わせて543件のテスト仕様があり、その中に48
個のエンドツーエンド用ファイルと30件のブラウザーテスト仕様を含みま
す。このページの件数は、二つのツールを合わせたものです。全体を612行
のワークフローで10ジョブとして実行します。ページは代償も明記していま
す。このテスト一式は遅く、変更のたびに負担がかかり、この規模では、テ
ストそのものにも保守が必要です。

このサイトのブラウザー検査は、別のライブラリーPuppeteerで動かしてお
り、クレジットページにも同じ利点と負担が示されています。検査するの
は、実測コントラスト、フォーカス順、操作対象のサイズ、表示領域からの
はみ出し、印刷時の改ページなど、バリデーターでは確認できないことで
す。品質ゲートは、表示領域からのはみ出し以外を、毎回のプッシュ前にす
べて実行します。はみ出し検査は、ピクセル単位の視覚的回帰検査と同様、
人が必要に応じて実行します。

問題が起きるところ

Playwrightの問題の多くは、名前から期待するほどのことを、テストが検査
していないために起こります。

条件の代わりに、固定時間だけ待ちます。
二秒待ってからページを読んだり、一度だけ値を読んで一般的なアサーショ
ンで比較したりします。混雑したビルドサーバーでは、二秒では足りないこ
とがあります。`toHaveText`のようなウェブ向けのアサーションで、訪問者
に見えるはずの状態を検査し、再試行に任せます。

マークアップで要素を探します。
三重に入れ子になった`div`や、装飾用クラスをたどるセレクターは、ペー
ジが動いていても、次のデザイン変更で壊れます。ロールとアクセシブルな
名前、またはラベルやテキストで要素を探します。ユーザーが認識できるも
のでは何も識別できないときにだけ、テストIDを追加します。

ロールによる検索の成功を、アクセシビリティー検査と見なします。
`getByRole`が示すのは、指定したロールと名前を持つ要素が一つあること
です。コントラスト、フォーカス順、ページの残りの部分については何も分
かりません。そのためには、Playwright自身のガイドが
`@axe-core/playwright`経由で行うように、axeなどのルールエンジンをテ
ストから実行します。検査対象は「呼び出したときの、ページの現在の状
態」なので、先にメニューやダイアログを開きます。

クリックを強制します。
`force`は、操作可能性の検査のうち、必須でないものを無効にします。ク
リックなら、対象が本当にイベントを受け取るかを確認しなくなります。こ
の指定が必要なテストは、ボタンを覆うバナーなど、訪問者も出会う問題を
回避していることがよくあります。元のエラーを発見事項として扱い、訪問
者と同じ方法でバナーを閉じるか、重なりを修正します。

不安定なテストを、成功するまで再試行します。
再試行を有効にした場合、初回に失敗して再試行で成功したテストは、失敗
ではなく不安定と分類されます。毎週のように不安定なら、ページの処理と
競合しているか、本物の間欠的な欠陥を検出しています。最初の再試行で記
録したトレースから調べ始めます。

すべてをブラウザー経由で検査します。
価格や権限の規則を、三つの画面をクリックしてたどって検査すると、遅く
なり、規則と関係ない理由で失敗します。規則は、それが実装されている場
所で検査します。ブラウザーテストは、操作の流れ、レイアウト、エンジン
間の違いなど、ブラウザーでしか分からないことに使います。

参考資料

  * インストール — Playwright Testの導入、サンプルテストの実行、HTML
レポート、UI Modeです。

  * ロケーター — ロールやラベルからテストIDまで、要素を探すときの推
奨順序です。

  * 自動待機 — 各操作前の操作可能性の検査と、`force`で無効になるもの
です。

  * アサーション — 再試行するものとしないもの、既定の待機時間、失敗
してもテストを続けるソフトアサーション、ポーリングです。

  * トレースビューアー — 再試行時のトレース記録と、失敗したテストを
操作ごとにたどる方法です。

  * ブラウザー — エンジンのインストール、製品版ChromeとEdgeの実行、
二つのヘッドレスモードです。

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/playwright/	engineer.company	70
