Playwright テスト構造とフック
この章では、Playwright テストの編成方法について説明します。テストのグループ化、実行制御、ライフサイクルフックの使い方などを含みます。
test.describe() テストのグループ化
test.describe()関連するテストをまとめて論理的なグループを形成するために使用します。
例
import { test, expect } from '@playwright/test';
// 第一レベルのグループ
test.describe('サンプル ホームページテスト', () => {
test('ページタイトルが正しい', async ({ page }) => {
await page.goto('https://www.example.com/');
await expect(page).toHaveTitle(/サンプル/);
});
test('ナビゲーションバーが存在する', async ({ page }) => {
await page.goto('https://www.example.com/');
// ナビゲーション要素の存在を検証
await expect(page.locator('nav')).toBeVisible();
});
});
// 複数の describe ブロックを定義できます
test.describe('検索機能テスト', () => {
test('検索ボックスが表示される', async ({ page }) => {
await page.goto('https://www.example.com/');
await expect(
page.getByPlaceholder('検索')
).toBeVisible();
});
});
テストレポートはdescribeグループごとに表示され、結果を確認しやすくなります。
ネストされた describe
test.describe()ネストでき、ツリー構造を形成できます:
例
test.describe('ログイン機能', () => {
test('正しいアカウントとパスワードでログイン', async ({ page }) => { /* ... */ });
test('誤ったパスワードでログイン失敗', async ({ page }) => { /* ... */ });
});
test.describe('登録機能', () => {
test('正しい情報を入力して登録', async ({ page }) => { /* ... */ });
test('既存のメールアドレスで登録失敗', async ({ page }) => { /* ... */ });
});
});
test.skip() テストをスキップ
test.skip()特定のテストをスキップするために使用します。スキップされたテストは実行されません。
例
test.skip('未完了の機能テスト', async ({ page }) => {
// このテストは実行されません
});
// 条件付きスキップ(実行時に判断)
test('特定の条件下でスキップ', async ({ page, browserName }) => {
// Firefox ではスキップ
test.skip(browserName === 'firefox', Firefox はこの機能を一時的にサポートしていません);
// テストロジックは Firefox 以外のブラウザでのみ実行されます
await page.goto('https://www.example.com/');
});
test.fail() 予期される失敗をマーク
test.fail()失敗することがわかっているテストをマークするために使用します。
例
test.fail('既知のバグ:検索機能は未実装', async ({ page }) => {
await page.goto('https://www.example.com/');
// このアサーションは失敗することが予期されます
await expect(page.locator('.search-results')).toBeVisible();
});
// テストが予期せず成功した場合、失敗として報告されます
// これにより「バグが修正されたので test.fail マークを削除できます」と通知されます
test.fail()の役割は逆方向のマーキングです:テスト失敗=期待どおり、テスト成功=異常(マークの削除が必要かもしれません)。
test.only() 現在のテストのみ実行
test.only()開発・デバッグ時に特定のテストのみを実行し、ファイル内の他のテストを無視するために使用します。
例
test.only('このテストをデバッグしています', async ({ page }) => {
// このテストのみが実行されます
await page.goto('https://www.example.com/');
});
test('このテストは無視されます', async ({ page }) => {
// 上に test.only() があるため、これは実行されません
});
test.only()はデバッグツールであり、コードリポジトリにコミットすべきではありません。もしあなたがplaywright.config.tsに設定した場合、forbidOnly: trueCI 上で検出され、onlyビルドを失敗させます。
test.fixme() 修正待ちをマーク
test.fixme()とtest.skip()似ていますが、意味的には「このテストは修正が必要です」と示します。
例
test.fixme('API 変更によりログインフローを更新する必要があります', async ({ page }) => {
// このテストは一時的に実行されません
});
test.slow() 遅いテストをマーク
test.slow()テストのタイムアウト時間を3倍に増やします。
例
test.slow('大量データテスト', async ({ page }) => {
// このテストのデフォルトタイムアウトは90秒になります(30秒 × 3)
// 大量のデータ読み込みや複雑な計算が必要なシーンに適しています
});
テストフック(Hooks)
フック関数を使用すると、テストのさまざまな段階で準備とクリーンアップを実行できます。
test.beforeEach() と test.afterEach()
beforeEach各テストの前に実行され、afterEach各テストの後に実行されます。
例
import { test, expect } from '@playwright/test';
test.beforeEach(async ({ page }) => {
// 各テストの前に同じページへナビゲート
await page.goto('https://www.example.com/');
});
test.afterEach(async ({ page }) => {
// 各テストの後にクリーンアップを実行(作成したデータの削除など)
// Playwright はブラウザの context を自動的にクリーンアップします。
// ここでのクリーンアップは主にサーバー側の状態を指します
console.log('テスト完了、クリーンアップを開始...');
});
test('最初のテスト', async ({ page }) => {
// page はすでに サンプル ホームページにあります
await expect(page).toHaveTitle(/サンプル/);
});
test('2番目のテスト', async ({ page }) => {
// page も同様に サンプル ホームページにあります
// これはまったく新しい context であり、前のテストの Cookie/Storage は残りません
await expect(page.locator('nav')).toBeVisible();
});
test.beforeAll() と test.afterAll()
beforeAllに現在のスコープではすべてのテストの前に一度実行され、afterAllすべてのテストの後に一度実行されます。
例
test.beforeAll(async ({ browser }) => {
// すべてのテストの前にテストユーザーを作成(一度だけ実行)
// 注意:beforeAll は page fixture を使用できません
});
test.afterAll(async ({ browser }) => {
// すべてのテストの後にテストユーザーを削除(一度だけ実行)
});
test('ユーザー一覧を表示', async ({ page }) => { /* ... */ });
test('ユーザー情報を編集', async ({ page }) => { /* ... */ });
});
beforeAllとafterAllにアクセスできませんpagefixture。page はテストごとに独立しているためです。ページを操作する必要がある場合は、beforeEach。
フックのスコープと実行順序
フックのスコープは、それらが配置されている場所によって決まります:
例
test.beforeEach(async () => {
console.log('ファイルレベルの beforeEach');
});
test.describe('グループ A', () => {
// グループレベルのフック —— グループ A にのみ作用
test.beforeEach(async () => {
console.log('グループ A の beforeEach');
});
test('テスト A1', async () => { /* ... */ });
test('テスト A2', async () => { /* ... */ });
});
test.describe('グループ B', () => {
// グループ B には独自のフックがなく、ファイルレベルのフックのみが有効
test('テスト B1', async () => { /* ... */ });
});
実行順序:外側のフックが先に実行され、内側のフックが後に実行されます。
A1 と A2 の場合:最初に出力されるのは"文件级 beforeEach"で、次に出力されるのは"分组 A 的 beforeEach"。
B1 の場合:出力されるのはのみ"文件级 beforeEach"。