e2e-bootstrap

name	e2e-bootstrap
description	E2E環境構築用。新規セットアップ・Playwright導入・既存プロジェクトの4層アーキテクチャ変換時に使用。Definition of Done・最小骨格・Fixture/constants雛形・コーディング規約・Playwrightデフォルトからの変換手順を含む。

E2E Bootstrap Skill

テスト追加が目的なら /e2e-test-create を使うこと。

§1. Definition of Done

• npm test が実行できる（smokeが1本通る）
• npx tsc --noEmit が通る（型エラー・未使用importがゼロ）
• npm run gate が exit 0（機械ゲート — 正本は scripts/gate.sh）
• Playwrightとブラウザ依存が揃っている
• 4層アーキテクチャの最小ディレクトリが存在する
• 認証情報は.env/CI環境変数で管理
• Fixtureファイル（app.fixture.ts）が存在しtest/expectをexport

---

§2. 4層の最小骨格

src/
├── tests/           # Layer 3: シナリオ
├── actions/         # Layer 2: ユーザ操作の流れ
├── pages/           # Layer 1: 画面要素と操作（Locatorはここ）
├── fixtures/        # Fixture定義
│   └── app.fixture.ts
├── utils/           # uniqueId.ts / formatDate.ts 等（§4 参照）
└── config/          # Layer 4: 環境差分・設定
    ├── env.ts
    └── constants.ts

---

§3. 最小Fixture

正本 = fixture-template.md（同ディレクトリ）— Fixture の新規作成・4層変換・新規 Action の登録時に必ず読む。 収録: base.extend の全体構造（worker スコープ stepCounter 含む完全形）。

§4. 最小constants.ts

export const TIMEOUTS = {
  // 数値定数は宣言行コメント必須（gate が機械検出。1 キー 1 行 + 行末コメントで書く）
  SHORT: 3000,   // 短い出現確認・安定化の上限（optional 要素のプローブ等、不在を早く諦める）
  MEDIUM: 10000, // 中程度の要素出現待ちの上限
  LONG: 30000,   // 長い遷移の上限（cross-origin リダイレクト完了・初回ページロード等）
  DEFAULT: 10000, // 要素出現・URL 遷移待ちの標準上限
  AUTH_STABILIZATION: 2000, // 外部認証リダイレクト後のセッション確立待ち
  MODAL_ANIMATION: 1000, // モーダルの open/close アニメーション
  SPA_RENDERING: 2000, // SPA の再描画・状態反映待ち
  REDIRECT: 3000, // ページ遷移後の URL 確定・初期化待ち
} as const;

export const SELECTORS = {
  MODAL: '[role="dialog"]',          // 単一モーダルにスコープする宇宙定数（.last() なし）
  SUBMIT_BUTTON: 'button[type="submit"]',
} as const;

export const URL_PATTERNS = {
  LOGIN: '**/login**',
  DASHBOARD: '**/dashboard**',
  LOGIN_PATH: '/login',
  // 例: AUTH_LOGIN: '**/auth.example.com/**',
} as const;

拡張例（プロジェクト固有の要素が増えたら追加）:

// TIMEOUTS 拡張例
ELEMENT_VISIBLE: 5000, // 特定要素の出現待ち（用途を書く — 宣言行コメントは gate が機械検出）

// SELECTORS 拡張例（複数画面で共通のセレクタのみ）
AGREEMENT_CHECKBOX: 'input[type="checkbox"]:near(:text("同意する"))',
AUTH_EMAIL_INPUT: 'input[name="username"]',
AUTH_PASSWORD_INPUT: 'input[name="password"]',

あわせて作る: src/utils/uniqueId.ts（一意テストデータ名）

テストデータ名の一意性確保に必須（Date.now() 単独は並列ワーカー衝突 — 判定基準は prohibited-patterns.md「一意テストデータ名は uniqueId() で生成する」）。

// src/utils/uniqueId.ts
/**
 * 並列ワーカー間でも衝突しない一意サフィックスを生成する。
 * テストデータ名（リソース名・エントリ名など）の一意性確保に使う。
 *
 * 一意性を `Date.now()` のミリ秒だけに依存すると、`workers > 1` の並列実行で
 * 別プロセスのワーカーが同一ミリ秒に生成して衝突する（テスト環境に同名データが並び
 * `getByText` 等が複数マッチして落ちる）。ms の36進 + ランダム6桁で回避する。
 * 詳細は `.claude/rules/prohibited-patterns.md`「一意テストデータ名は uniqueId() で生成する」参照。
 */
export function uniqueId(): string {
  // slice(2, 8) は Math.random() の値次第で6文字未満になりうるため padEnd で6桁固定にする
  return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}`;
}

---

§5. playwright.config.ts 必須設定

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './src/tests',
  globalSetup: './src/global-setup.ts',    // crashpad_handler 残存クリーンアップ（macOS arm64 + Chromium）
  timeout: 60000,                          // テスト全体のタイムアウト
  expect: {
    timeout: 10000,                        // 各expectのタイムアウト
  },
  reporter: [
    ['json', { outputFile: 'test-results/report.json' }],  // 構造化レポート
    ['html', { open: 'never' }],                            // HTMLレポート
    ['list'],                                                // ターミナル表示
  ],
  use: {
    trace: 'retain-on-failure',              // 失敗時のみtrace保存（常時ONはheaded実行でクラッシュする）
    screenshot: 'on',                      // 全テストでスクリーンショット保存
    video: 'retain-on-failure',            // 失敗時の動画（容量対策）
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        // macOS arm64 + Chromium headed モードで chrome_crashpad_handler が
        // 残存しプロセスがハングする問題の防御的設定。
        
        : {
          : [],
        },
      },
    },
  ],
});

なぜこの設定が必須か:

• timeout + expect.timeout: 無限に待たせない。偽Passの防止
• json reporter: report.jsonにステップ構造が残る。Fail時の追跡に必須
• trace/video retain-on-failure: 失敗時のみ保存。trace常時ONは長時間テストのheaded実行でブラウザクラッシュの原因になる。Pass時の証跡はreport.json + screenshotで代替
• screenshot on: 全テストでスクリーンショット保存。Pass時の「正しく動作した証拠」として機能
• html reporter: 人間がブラウザで結果を確認できる
• projects: ブラウザを明示的に指定
• --disable-crash-reporter: macOS arm64 + Chromium で crash reporter 残存の防御的設定。これだけでは完全に防げないため globalSetup と併用
• globalSetup: テスト開始前に前回の残存 chrome_crashpad_handler をクリーンアップ（対症療法）

globalSetup（crashpad_handler クリーンアップ）

macOS arm64 + Chromium for Testing の headed モードで、テスト完了後に chrome_crashpad_handler が残存しプロセスがハングする問題の対症療法。テスト開始前に前回の残存プロセスをクリーンアップする。

// src/global-setup.ts
import { execSync } from 'child_process';

export default function globalSetup() {
  try {
    execSync("pkill -f 'ms-playwright.*chrome_crashpad_handler' 2>/dev/null", { stdio: 'ignore' });
  } catch {
    // プロセスが存在しない場合は無視
  }
}

playwright.config.ts に globalSetup: './src/global-setup.ts' を追加すること。 ms-playwright でパスを絞り込むため、通常の Chrome / VS Code / 他アプリには影響しない。

---

§6. BaseAction / StepCounter 雛形

全ActionはBaseActionを継承する。step()ヘルパーはコンソール（ユーザーストーリー粒度）とtest.step()（HTMLレポート階層表示）を両方出力する。prefix（[Suite / Phase]）は test.info().titlePath から自動導出される。

BaseAction.ts

// actions/BaseAction.ts
import { Page, test } from '@playwright/test';
import { StepCounter } from './StepCounter';

export class BaseAction {
  protected readonly page: Page;
  protected readonly actionName: string;
  protected readonly stepCounter?: StepCounter;

  constructor(page: Page, actionName: string, stepCounter?: StepCounter) {
    this.page = page;
    this.actionName = actionName;
    this.stepCounter = stepCounter;
  }

  /** Action の public メソッド先頭で呼ぶ。メイン番号をインクリメント */
  protected beginAction(): void {
    this.stepCounter?.nextMain();
  }

  /**
   * ステップ記録ヘルパー
   * コンソール: [Suite / Phase] Step N: ActionName - 詳細
   * HTMLレポート: test.step() ネストで Action 内部詳細を階層表示
   *
   * 重要: fn() 実行中のエラーは catch せずそのまま伝播させる。
   *       catch するのはテストコンテキスト判定のみ。偽陽性（flaky pass）を防止する。
   */
  protected async (: , :  <>): <> {
     { prefix, hasTestContext } = .();
     mainNo = .?. ?? ;
    
    
     (. && mainNo === ) {
        (
        
      );
    }
     stepLabel = mainNo >  ?  : ;
    .();

     (hasTestContext) {
       test.(name, fn); 
    }  {
       ();                
    }
  }

  
   (): { : ; :  } {
     {
       info = test.();
       parts = info..(); 
       (parts. === )  { : , :  };
       labels = parts.( .(p));
       { : , :  };
    }  {
       { : , :  };
    }
  }

   (: ):  {
    
     candidates = [title.(), title.()].( i !== -);
     (candidates. === )  title;
     colonIdx = .(...candidates);
     title.(, colonIdx).();
  }
}

StepCounter.ts

// actions/StepCounter.ts
import { test } from '@playwright/test';

/**
 * Action 呼び出し単位のステップ番号管理（describe スコープで継続カウント）
 * - 同一 describe 内では test() を跨いでも番号を継続カウント
 * - 別 describe に入ると番号を 1 にリセット
 */
export class StepCounter {
  private mainNumber = 0;
  private lastDescribeKey: string | null = null;

  /** Action の public メソッド開始時に呼ぶ。describe 境界でリセットしてから +1 */
  nextMain(): number {
    const currentKey = this.getDescribeKey();
    if (currentKey !== this.lastDescribeKey) {
      this.mainNumber = 0;
      this.lastDescribeKey = currentKey;
    }
    this.mainNumber++;
    return this.mainNumber;
  }

  /** 現在のメイン番号（インクリメントせず参照のみ。step() 表示用） */
  get currentMain(): number {
    return this.mainNumber;
  }

  private getDescribeKey(): string | null {
    try {
      const info = test.();
       parts = info.;
      
      
      
       keyParts = parts.(, -);
       keyParts. >  ? keyParts.() : ;
    }  {
       ;
    }
  }
}

prefix の構成:

• test.info().titlePath から自動導出（[file, describe, test] の順）
• describe / test 名の : 前半をラベルとして採用（例: 'Suite-A: フロー名...' → 'Suite-A'）
• : が無ければ名前全体を使用
• ASCII : と全角 ： の両方に対応（先に現れる方で分割）

出力例:

コンソール:
[Suite-A / Phase 1] Step 1: LoginAction - ログインページへ遷移
[Suite-A / Phase 1] Step 1: LoginAction - 認証情報入力
[Suite-A / Phase 1] Step 2: NavigationAction - メインメニューを開く
...
[Suite-A / Phase 2] Step 21: LoginAction - ログインページへ遷移   ← describe 内で連番継続

HTMLレポート（test.step() ネスト — Action 内部詳細はこちらで階層表示）:
  ログインページへ遷移
  認証情報入力
  送信ボタンクリック
  ...

番号の意味: 番号は「同一 describe 内の Action 呼び出し順」。並列 workers では各 worker が独立した StepCounter を持つため、異なる describe の番号同士は比較できない（グローバル順序は読み取れない）。

---

§7. .env.example

TEST_BASE_URL=
TEST_USER_EMAIL=
TEST_USER_PASSWORD=

---

§8. コーディング規約

package.json 必須devDependencies / scripts

{
  "scripts": {
    "gate": "bash scripts/gate.sh"
  },
  "devDependencies": {
    "@playwright/test": "^1.50.0",
    "dotenv": "^16.4.0",
    "typescript": "^5.9.0",
    "@types/node": "^22.0.0"
  }
}

typescript は 5 系を維持する（gate の verify 内固定待機チェックが TypeScript 5 系の JS コンパイラ API を使用。7 系は API 非公開のためチェックがエラー停止する）。

typescript と @types/node がないと npx tsc --noEmit による型チェックが実行できない。 §1 Definition of Done の型チェック要件を満たすために必須。

gate script は必須（機械ゲート）。CI で gate を走らせる場合は、.github/workflows/gate.yml 等にプロジェクトのディレクトリを追加すること。

TypeScript設定（tsconfig.json）

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

コードフォーマット（Prettier）

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100
}

命名規則

種類	規則	例
クラス	PascalCase	LoginPage, LoginAction
メソッド	camelCase	fillEmail(), clickButton()
変数	camelCase	emailInput, userName
定数	UPPER_SNAKE_CASE	MAX_RETRY, DEFAULT_TIMEOUT
インターフェース	PascalCase	TestEnvironment

JSDocコメント規約

/**
 * メソッドの説明
 * @param email - メールアドレス
 * @param password - パスワード
 * @returns ログイン成功の可否
 */
async execute(email: string, password: string): Promise<boolean> {
  // 実装
}

---

§9. Playwrightデフォルト構成から4層への変換手順

Playwrightデフォルト（tests/直下にspecファイル）から変換する場合：

1. src/ 配下に4層ディレクトリ作成（§2参照）
2. config/constants.ts と config/env.ts を作成（§4, §5参照）
3. specファイル内のLocator → pages/ のPage Objectに移動
4. specファイル内のフロー操作 → actions/ のActionに移動
5. Fixture定義を作成（§3参照）し、testのimport元を切り替える
6. specファイルには意図・期待結果のみ残す（Locator・ロジック禁止）
7. ハードコード値 → constants.ts に移動
8. 認証情報 → env.ts + .env に移動
9. npx playwright test で全テスト通過を確認

変換時の注意:

• 一度に全部変換しない。1テストずつ移行して確認
• 既存のテストが通る状態を常に維持する
• 新規Actionを作ったらFixtureに登録を忘れない

---

§10. プロジェクト固有設定チェックリスト

新プロジェクトに導入する際、以下を確認してCLAUDE.mdに記入する：

• 対象プロダクト名
• UIライブラリ（Ant Design / MUI / 独自 / なし）
• 認証方式（外部認証 / 独自ログイン / SSO / なし）
• HTML意味層の状況（data-testid有無 / aria-label整備状況）
• SPA or MPA
• CI/CD環境（CircleCI / GitHub Actions等）
• Rules 総量 baseline の凍結（人間が実行）: npm run gate が提示する実測値で .claude/rules-baseline を作成する。AI エージェントはこのファイルを作成・変更しない（実測値を人間に伝えて設定を依頼するまでが担当範囲。凍結・引き上げは「この量を正とする」人間の意思決定 — 正本: scripts/gate.sh チェック 21 の★コメント）

---

§11. トラブルシューティング

macOS + Chromium headed モードでテスト失敗後にターミナルがハングする

症状: npx playwright test --headed で失敗した後、ターミナルがコマンドを受け付けない。Ctrl+C も効かないことがある。

原因: chrome_crashpad_handler プロセスが残存し、親プロセスが解放されない。globalSetup（§5）は次回テスト実行前に残存をクリーンアップする予防策であって、現在のハング状態は解消しない。

対処: 別ターミナルタブから次のコマンドで Playwright の Chromium プロセスのみを kill する。

pkill -f 'ms-playwright'

ms-playwright でパスを絞り込むため、通常の Chrome / VS Code / 他アプリには影響しない。kill 後、ハングしていたターミナルが解放される。