Playwright テスト
この章では、最初の Playwright テストを作成・実行し、テストの基本的な構成と実行の流れを理解します。
サンプルテストを実行する
プロジェクトを初期化したら、自動生成されたサンプルテストを実行して、すべてが正常に動作することを確認します：
# 运行所有测试 npx playwright test
実行後、以下のような出力が表示されます：
Running 6 tests using 4 workers ✓ 1 [chromium] › tests/example.spec.ts:3:1 › has title (2.1s) ✓ 2 [chromium] › tests/example.spec.ts:10:1 › get started link (1.8s) ✓ 3 [firefox] › tests/example.spec.ts:3:1 › has title (1.9s) ✓ 4 [firefox] › tests/example.spec.ts:10:1 › get started link (1.7s) ✓ 5 [webkit] › tests/example.spec.ts:3:1 › has title (2.3s) ✓ 6 [webkit] › tests/example.spec.ts:10:1 › get started link (2.0s) 6 passed (12s)
出力からわかるように、テストは3つのブラウザーでそれぞれ2つずつ、合計6つのテストがすべて成功しています。
最初のテストファイルを作成する
クリアtests/example.spec.tsの内容を空にして、ゼロからテストを書いてみましょう。
例
import { test, expect } from '@playwright/test';
// test(name, callback) はテストを定義します
// name: テスト名。テストレポートに表示されます
// callback の引数 { page } は Playwright が提供する fixture（フィクスチャ）です
test('サンプル のトップページにアクセスしてタイトルを確認する', async ({ page }) => {
// 指定された URL に移動します
await page.goto('https://www.example.com/');
// アサーション: ページタイトルに「サンプル」が含まれる
await expect(page).toHaveTitle(/サンプル/);
});
このテストを実行します：
npx playwright test tests/first-test.spec.ts
期待される出力：
Running 1 test using 1 worker ✓ 1 [chromium] › tests/first-test.spec.ts:4:1 › 访问 サンプル 首页并检查标题 (2.5s) 1 passed (2.5s)
test() 関数の詳細
test()Playwright Test の中心となる関数で、テストケースを定義するために使われます。
基本構文
例
// test(テスト名, テスト関数)
test('テストの説明的な名前', async ({ page }) => {
// テスト内の操作
await page.goto('https://example.com');
// テスト内のアサーション
await expect(page).toHaveTitle(/Example/);
});
引数の説明
| 引数 | 型 | 説明 |
|---|---|---|
| 第1引数（テスト名） | string | テストの説明的な名前で、テストレポートとログに表示されます |
| 第2引数（テスト関数） | async (fixtures) => {} | テストの実際のロジックを含む非同期関数です |
page fixture とは
{ page }テスト関数の引数の中の分割代入、Playwright が提供する fixtures オブジェクトから抽出しますpage。
pageはPage オブジェクト、ブラウザのタブページを表します。
各テストは独立したpageインスタンスを持ちます：
| fixture | 型 | 説明 |
|---|---|---|
page | Page オブジェクト | 独立したブラウザのタブページ。ナビゲーション、操作、アサーションに使用 |
context | BrowserContext オブジェクト | ブラウザのコンテキスト。Cookie、Storage などを管理します |
browser | Browser オブジェクト | ブラウザのインスタンス。直接使用することはあまりありません |
request | APIRequestContext オブジェクト | HTTP リクエストを送信するために使用します（ブラウザを介さない） |
最もよく使われるのはpageで、ほとんどの操作がこれによって行われます。
page.goto() ナビゲーション
page.goto(url)Playwright の最も基本的な操作の1つで、指定した URL に移動するために使います。
例
await page.goto('https://www.example.com/');
// オプション付きのナビゲーション
await page.goto('https://www.example.com/', {
// 'load' イベントが発生するまで待機（デフォルト値）
waitUntil: 'load',
// 操作のタイムアウト時間（ミリ秒）
timeout: 30000,
// リファラー（Referer ヘッダー）
referer: 'https://www.google.com/',
});
waitUntilオプションには3つの選択肢があります：
| 值 | 意味 | 適用シナリオ |
|---|---|---|
'load' | load イベントの発生を待機 | デフォルト値。ほとんどのページに適用 |
'domcontentloaded' | DOMContentLoaded イベントの発生を待機 | ページの基本構造の読み込みが完了すれば十分な場合 |
'networkidle' | ネットワークがアイドル状態（500ms 以内に新しいリクエストがない）になるまで待機 | 非同期データがすべて読み込まれるまで待つ必要がある場合 |
ほとんどの場合、デフォルトの
'load'を使用すれば十分です。Playwright の自動待機メカニズムが後続の要素の可用性の問題を処理するため、'networkidle'。
expect() アサーション
expect()Playwright のアサーションメソッドで、テスト結果が期待通りかどうかを検証するために使います。
例
await expect(page).toHaveTitle(/サンプル/);
// ページ URL のアサーション
await expect(page).toHaveURL('https://www.example.com/');
// 要素の可視性のアサーション
await expect(page.getByText('サンプル')).toBeVisible();
Playwright のアサーションには重要な特性があります：自動再試行。
アサーション条件が一時的に満たされない場合、Playwright は条件が満たされるかタイムアウトするまで再試行し続けます。
これは、あなたが書く必要がないことを意味しますwaitFor 或 sleepページの準備が整うのを待つために。
テストの async/await パターン
Playwright のすべての操作は非同期なので、テスト関数はasync。
すべてのブラウザ操作（goto、click、fillなど）とアサーション（expect）はすべてawaitキーワードを使用する必要があります。
例
test('正しい例', async ({ page }) => {
await page.goto('https://www.example.com/');
await expect(page).toHaveTitle(/サンプル/);
});
// 誤った書き方（await がない）
test('誤った例', async ({ page }) => {
page.goto('https://www.example.com/'); // await がない！
expect(page).toHaveTitle(/サンプル/); // await がない！
});
もし書き忘れた場合、
await、テストが不適切なタイミングでアサーションされ、テストが不安定になったり、誤って成功したりする可能性があります。Playwright API を呼び出すたびに必ずawait。
テスト出力を理解する
アサーションが失敗するテストをもう一つ見て、テスト出力を理解しましょう：
例
import { test, expect } from '@playwright/test';
test('意図的に失敗させるテスト', async ({ page }) => {
await page.goto('https://www.example.com/');
// タイトルに存在しない文字列が含まれるとアサーションし、失敗することを期待
await expect(page).toHaveTitle(/存在しない文字/);
});
実行後、出力はおおよそ以下のようになります：
Running 1 test using 1 worker
✘ 1 [chromium] › tests/fail-demo.spec.ts:4:1 › 一个故意失败的测试 (5.2s)
1 failed
tests/fail-demo.spec.ts:4:1 › 一个故意失败的测试
同時に HTML レポートが自動的に開き、詳細な失敗情報とエラースクリーンショットが表示されます。
その他の拡張