Playwright プロジェクト構造

Playwright プロジェクトの初期化に成功すると、プロジェクトディレクトリに一連のファイルとフォルダーが生成されます。この章では、各部分の用途を詳しく解説します。

初期化されたプロジェクト構造の一覧

実行npm init playwright@latestすると、プロジェクトディレクトリに以下の構造が生成されます：

your-project/
├── playwright.config.ts      # Playwright 配置文件
├── package.json              # 项目依赖与脚本
├── package-lock.json         # 依赖锁定文件
├── tests/                    # 测试文件目录
│   └── example.spec.ts       # 示例测试文件
├── tests-examples/           # 更多示例测试（可选）
│   └── demo-todo-app.spec.ts
├── .github/                  # GitHub Actions 配置（可选）
│   └── workflows/
│       └── playwright.yml
└── node_modules/             # npm 依赖包

playwright.config.ts —— 設定ファイル

これは Playwright の中核となる設定ファイルであり、テスト実行のすべての側面を制御します。

例

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

export default defineConfig({
// テストファイルディレクトリ、この設定ファイルからの相対パス
testDir: './tests',

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

// ソースコードに test.only が残っている場合、CI ではビルドが失敗する
forbidOnly: !!process.env.CI,

// CI 環境では失敗後に2回再試行し、ローカルでは再試行しない
retries: process.env.CI ? 2 : 0,

// CI 環境ではシングルスレッドを使用し、ローカルではデフォルトのマルチスレッドを使用
workers: process.env.CI ? 1 : undefined,

// HTML レポーターを使用
reporter: 'html',

// すべてのテストで共有される設定
use: {
// ベース URL。テストでは相対パスを使用できる
baseURL: 'http://localhost:3000',

// 失敗再試行時にトレースを収集
trace: 'on-first-retry',
},

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

// テスト開始前にローカル開発サーバーを起動（オプション）
// webServer: {
// command: 'npm run start',
// url: 'http://localhost:3000',
// reuseExistingServer: !process.env.CI,
// },
});

playwright.config.tsは Playwright の動作を制御する中核となるエントリーポイントです。第15章で各設定項目について詳しく説明します。

package.json —— 依存関係とスクリプト

初期化後、package.jsonに Playwright 関連の内容が追加されます：

例

{
"devDependencies": {
"@playwright/test": "^1.52.0" // Playwright Test を開発依存関係として
},
"scripts": {
"test": "playwright test" // npm test を直接実行できる
}
}

カスタムスクリプトを追加することもできます：

例

{
"scripts": {
"test": "playwright test",
"test:ui": "playwright test --ui",
"test:headed": "playwright test --headed",
"test:chromium": "playwright test --project=chromium",
"test:debug": "playwright test --debug",
"codegen": "playwright codegen"
}
}

tests/ ディレクトリ —— テストファイル

tests/ディレクトリはデフォルトのテストファイルの保存場所です（testDir設定で指定されます）。

初期化されたサンプルテストファイルの内容は以下の通りです：

例

// ファイルパス: tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
// Playwright 公式サイトに移動
await page.goto('https://playwright.dev/');

// ページタイトルに "Playwright" が含まれることを検証
await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
// Playwright 公式サイトに移動
await page.goto('https://playwright.dev/');

// "Get started" リンクをクリック
await page.getByRole('link', { name: 'Get started' }).click();

// ページに "Installation" 見出しが表示されることを検証
await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

テストファイルの命名の推奨：.spec.ts（TypeScript）または.spec.js（JavaScript）接尾辞を使用します。

tests-examples/ ディレクトリ —— その他の例

初期化時にサンプルテストを含めることを選択した場合、tests-examples/ディレクトリには、より完全なテストサンプルがあります：

demo-todo-app.spec.ts実際の Todo アプリケーションの完全なテストシナリオを示しています。タスクの追加、完了状態の切り替え、フィルター機能などを含みます。

これは良い学習リファレンスです。実行して効果を確認できます：

npx playwright test tests-examples/

.github/workflows/ —— CI 設定

初期化時に GitHub Actions の追加を選択した場合、.github/workflows/playwright.ymlファイルが自動生成されます。

このワークフローは、コードをプッシュするたび、または PR を作成するたびに Playwright テストを自動的に実行します。

ブラウザの保存場所

Playwright がインストールするブラウザのバイナリファイルはプロジェクトディレクトリ内にはなく、オペレーティングシステムのキャッシュディレクトリに保存されます：

オペレーティングシステム	ブラウザの保存パス
macOS	~/Library/Caches/ms-playwright/
Windows	%USERPROFILE%\AppData\Local\ms-playwright\
Linux	~/.cache/ms-playwright/

カスタムの保存パスを設定することもできます：

# 设置浏览器安装路径
export PLAYWRIGHT_BROWSERS_PATH=/your/custom/path
npx playwright install

node_modules/ —— 依存パッケージ

Playwright の中核となる依存関係は@playwright/testにインストールされnode_modules/ます。

依存関係の内部には Playwright の完全なランタイムが含まれており、ブラウザと通信するプロトコルレイヤーも含まれます。

npm でインストールされる Node.js パッケージに加えて、Playwright はブラウザのバイナリファイル（システムキャッシュに保存）にも依存しており、両方が必要です。

その他の拡張

Playwright上級

リファレンスマニュアル