Playwright 設定の詳細

この章では詳しく説明しますplaywright.config.tsの各設定について、プロジェクトの要件に応じてテストの動作を柔軟に調整できるようにします。


設定ファイルの概要

playwright.config.tsこれは Playwright の中央設定ファイルであり、すべてのテスト実行パラメータがここで定義されます。

例

// ファイルパス: playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // ===== 基本設定 =====
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  timeout: 30000,

  // ===== グローバル共通設定 =====
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  // ===== マルチブラウザープロジェクト =====
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
  ],

  // ===== Web サーバー =====
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

基本設定項目

設定項目型デフォルト値説明
testDirstringtestsテストファイルが配置されているディレクトリ
fullyParallelbooleanfalseすべてのテスト(同一ファイル内のテストを含む)を完全並列実行するかどうか
workersnumberCPUコア数/2並列実行するワーカー数
retriesnumber0失敗したテストの再試行回数
timeoutnumber30000各テストの合計タイムアウト(ミリ秒)
reporterstring/arraylistテストレポーターの種類
forbidOnlybooleanfalseCI上で test.only() が検出された場合に失敗とする
testMatchstring/RegExp*.spec.(ts\|js)テストファイルのマッチパターン
testIgnorestring/RegExp-無視するテストファイルのパターン

設定例

例

export default defineConfig({
  // e2e ディレクトリ内でテストを探す
  testDir: './e2e',

  // すべてのテストを完全並列実行
  fullyParallel: true,

  // ワーカー数を自動割り当て
  workers: undefined,

  // 失敗時は再試行なし(ローカル)/ 2回再試行(CI)
  retries: process.env.CI ? 2 : 0,

  // コマンドラインとHTMLレポートを併用
  reporter: [
    ['list'],
    ['html', { open: 'never' }],
  ],
});

use 共通設定

useの設定はすべてのテストとプロジェクトに適用されます:

設定項目型説明
baseURLstringベースURL。テスト内で相対パスを使用可能(例:await page.goto('/login'))
viewport{width, height}ブラウザのビューポートサイズ。デフォルトは{ width: 1280, height: 720 }
localestringブラウザの言語。例:'zh-CN'、'en-US'
timezonestringタイムゾーン。例:'Asia/Shanghai'
colorSchemestringカラースキーム:'light'|'dark'|'no-preference'
geolocation{latitude, longitude}地理位置情報のモック
permissionsstring[]付与するブラウザ権限(例:['geolocation'])
userAgentstringカスタムUser-Agent文字列
tracestringTrace収集ポリシー:'on'|'off'|'on-first-retry'
screenshotstringスクリーンショットポリシー:'on'|'off'|'only-on-failure'
videostringビデオ録画ポリシー:'on'|'off'|'retain-on-failure'
storageStatestring認証状態ファイルのパス
testIdAttributestringカスタムtestId属性名。デフォルトは'data-testid'
actionTimeoutnumber各操作(click、fill)のタイムアウト時間
navigationTimeoutnumberナビゲーションごとのタイムアウト時間

webServer 設定

webServerこの設定により、Playwright はテスト実行前に開発サーバーを自動起動します:

例

export default defineConfig({
  webServer: {
    // 起動コマンド
    command: 'npm run dev',

    // このURLにアクセス可能になるのを待ってからテストを実行
    url: 'http://localhost:5173',

    // 待機タイムアウト時間(ミリ秒)
    timeout: 120000,

    // 実行中のサーバーを再利用するかどうか(ローカルでは再利用可、CIでは再起動)
    reuseExistingServer: !process.env.CI,
  },
});

globalSetup / globalTeardown グローバルフック

すべてのテストの実行前/後に1回実行され、データベースの初期化などの操作に適しています。

例

export default defineConfig({
  globalSetup: './global-setup.ts',
  globalTeardown: './global-teardown.ts',
});

例

// ファイルパス: global-setup.ts
import { FullConfig } from '@playwright/test';

async function globalSetup(config: FullConfig) {
  // すべてのテスト実行前に実行
  console.log('グローバル設定を開始...');
  // 例:テスト用データベースの初期化、テストユーザーの作成など
}

export default globalSetup;
その他の拡張