Playwright テスト構造とフック

この章では、Playwright テストの編成方法について説明します。テストのグループ化、実行制御、ライフサイクルフックの使い方などを含みます。


test.describe() テストのグループ化

test.describe()関連するテストをまとめて論理的なグループを形成するために使用します。

例

// ファイルパス:tests/describe-demo.spec.ts
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.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倍に増やします。

例

// 遅いテストとしてマーク、タイムアウト時間が3倍になります
test.slow('大量データテスト', async ({ page }) => {
  // このテストのデフォルトタイムアウトは90秒になります(30秒 × 3)
  // 大量のデータ読み込みや複雑な計算が必要なシーンに適しています
});

テストフック(Hooks)

フック関数を使用すると、テストのさまざまな段階で準備とクリーンアップを実行できます。

test.beforeEach() と test.afterEach()

beforeEach各テストの前に実行され、afterEach各テストの後に実行されます。

例

// ファイルパス:tests/hooks-demo.spec.ts
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.describe('ユーザー管理', () => {
  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"。

その他の拡張