Playwright

Playwrightとは

Playwright は、実際のブラウザを起動して画面を操作する E2E テストの枠組みです。[[自動テスト]] のうち、最も外側 — 利用者と同じ経路でアプリ全体を通す層 — を担当します。

import { expect, test } from '@playwright/test'

test('記事を検索して開ける', async ({ page }) => {
  await page.goto('/')
  await page.getByRole('searchbox', { name: '検索' }).fill('tokio')
  await page.getByRole('link', { name: /tokio/ }).click()
  await expect(page.getByRole('heading', { level: 1 })).toContainText('tokio')
})

Chromium・Firefox・WebKit の3エンジンを同じコードで動かせます。同じ操作でも WebKit だけ落ちるといった差はここで初めて表面化します。

自動待機 — E2Eが不安定になる原因を潰す

E2E テストが信頼されなくなる最大の原因は、待ち時間の書き方です。sleep(1000) のような固定待機は、遅い環境では足りず、速い環境では無駄になります。

Playwright の操作は条件が揃うまで自動で待ちます。クリックなら「要素が存在し、表示され、他の要素に覆われておらず、操作を受け付ける」まで待ってから実行します。

よくある失敗Playwright の扱い
要素がまだ描画されていない出現するまで待つ
アニメーション中でクリックがずれる静止するまで待つ
モーダルの裏のボタンを押してしまう覆われている間は待ち、時間切れなら失敗させる

それでも固定待機を書きたくなったら、待っている条件を言語化できていないサインです。 その条件を expect(...).toBeVisible() などの形で書くほうが、速くて安定します。

ロケータの選び方

要素の指定には CSS セレクタも使えますが、利用者から見える手がかりで指定するのが原則です。

page.getByRole('button', { name: '保存' })   // 役割 + アクセシブル名
page.getByLabel('メールアドレス')             // ラベル
page.getByText('保存しました')                // 表示テキスト

クラス名やDOM構造で指定すると、見た目の変更だけでテストが壊れます。役割とラベルで指定すれば、[[Webアクセシビリティ]] が整っているほどテストも安定するという関係になります。逆に「役割で引けない」ことが分かったら、それはマークアップ側の改善点です。

単体テストとの棲み分け

E2E は遅く、落ちたときの原因特定も難しい層です。何でもE2Eで書くとCIが長くなり、信頼が下がります。

  • 単体テスト — 関数・部品の入出力。数千件を数秒で回せる
  • 結合テスト — 画面と状態の連携。実ブラウザは使わない
  • E2E — 利用者の主要経路だけ。ログイン、購入、検索から閲覧まで

[[テストダブル(モック・スタブ)]] を多用するのは内側の層の役目です。E2E で外部依存を差し替えすぎると「本物を通す」という目的が薄れます。

実務での注意点

  • [[CI/CD]] ではブラウザの導入が要る — 実行環境にエンジンを入れる手順を忘れると、ローカルでは通るのにCIで落ちます
  • 失敗時の証拠を残す — スクリーンショット・動画・トレースを保存する設定にしておくと、CIでしか再現しない失敗を追えます
  • 並列実行と共有状態 — テストを並列に走らせると、共通のデータを取り合って落ちます。テストごとに保存データを初期化する仕組みを用意します
  • タイムアウト境界の失敗を環境要因と即断しない — CPUが逼迫していると境界付近のテストが落ちます。単独で再実行し、変更前のコードでも再現するかを見て切り分けます

関連技術とのつながり

  • [[自動テスト]] — テスト層の全体像。Playwright は最も外側を担当する
  • [[テストダブル(モック・スタブ)]] — 内側の層で使う道具。E2E では使いどころを絞る
  • [[テスト駆動開発]] — 先にテストを書く進め方。E2E は主要経路の受け入れ条件として書ける
  • [[CI/CD]] — ブラウザの導入と失敗時の証拠保存が要る実行環境
  • [[Webアクセシビリティ]] — 役割とラベルで引ける画面ほどテストも安定する
  • [[フレーキーテスト]] — 自動待機でも消えない揺れの原因と、所要時間の実測による切り分け
Q: Playwrightの自動待機が解決する問題はどれ?
- [ ] テストの実行順序を並べ替える
- [x] 固定の待ち時間に頼らず、操作できる状態になるまで待つ
- [ ] ブラウザの起動を不要にする
解説: 要素が表示され操作を受け付ける状態になるまで待ってから実行するため、環境の速さに左右されにくくなります。

Q: ロケータの指定方法として推奨されるのはどれ?
- [ ] CSSのクラス名で指定する
- [x] 役割(role)とアクセシブル名で指定する
- [ ] DOMの階層を辿って指定する
解説: 見た目の変更で壊れにくく、アクセシビリティが整っているほど安定します。

Q: E2Eテストの対象として適切な範囲はどれ?
- [ ] すべての関数の入出力を網羅する
- [x] ログインや検索から閲覧までの主要経路に絞る
- [ ] 画面上のすべてのボタンの見た目
解説: E2Eは遅く原因特定も難しいため、内側の層で守れるものは単体テストに任せます。