writing-codeceptjs-tests

CodeceptJS 4 のテスト作成

作成中に一度も実行されなかったテストは信頼できません。CodeceptJS MCP サーバーを介して実際のブラウザーを操作し、すべてのロケーターを実際のページで検証して、成功したステップだけをコミットしてください。

フローをどの程度把握しているかに応じて、2 つのモードから選びます。

• モード A — 段階的な run_code：1 回の呼び出しにつき I.* の行を 1～2 行送り、応答を読み取って繰り返します。既存のテストの拡張、既知のフロー、手動プランの移植に適しています。
• モード B — スキャフォールドして一時停止（新規作成／未知のフローに推奨）：I.amOnPage('/...'); pause(); を含むスタブの Scenario を作成し、MCP の run_test で実行します。ブラウザーが開き、pause() で制御が戻ります。run_code を使って実際のページを操作し、その後 pause() を検証済みのシーケンスに置き換えます。

どちらも、同じ探索／ロケーター／コミットの手順を共有します。異なるのは、進行中の探索をどこで行うかです。

ワークフロー

1. まずは基礎を確認 — codeceptjs-fundamentals を実行します。必要なものは、有効な Web ヘルパー、ベース URL、プラグイン（aiTrace、auth）、AI プロバイダー、ページオブジェクト、環境変数です。
2. 既存のものを把握 — check／list／dry-run（fundamentals § Discover を参照）を実行します。重複を検出し、予定しているフローをすでにカバーするカスタムステップやページオブジェクトのメソッドがないことを確認します。
   • ⚠ dry-run ではプラグインが初期化されません。Before(({ login }) => login('admin')) は、実行時には動作しても、dry-run では「login is not a function」エラーになります。--steps で形状を確認し、プラグインの注入エラーは無視します。認証は実際に実行して確認してください。
3. 認証 — ログインが必要な経路では、codeceptjs-auth スキルを呼び出します。既存のロールが設定済みの場合は、Before(({ login }) => login()) を使います。未設定の場合は、認証スキルの手順に沿って追加します。公開経路の場合はスキップします。
4. 類似するテストとページオブジェクト — 該当する機能領域の Scenario、include 配下の PO、アクターファイルのカスタムステップ、データファクトリーを確認します。PO のメソッドにこの領域のロケーターがすでに定義されている場合は、生の I.click の連鎖ではなく、そのメソッドを使って操作します。
5. 開始ページ — 認証後の実在する URL を使い、推測で指定しないでください。不明な場合はユーザーに確認します。相対 URL のみを指定します。ホストは設定（helpers.Playwright.url など）にあります。
6. aiTrace と MCP の接続設定：
   • MCP 経由の場合：aiTrace は MCP サーバーによって強制的に有効化されるため、設定は不要です。
   • CLI 実行の場合：自動では有効化されません。設定で宣言するか、-p aiTrace を渡してください。有効化しないと、手順 11 で実行分析に必要な output/trace_*/ アーティファクトが生成されません。
   • デフォルトではヘッドレスで実行します（CI=1 をエクスポートして setHeadlessWhen(CI) を使うか、show: false を指定します）。
   • MCP クライアントが node_modules/codeceptjs/bin/mcp-server.js を参照し、CODECEPTJS_CONFIG と CODECEPTJS_PROJECT_DIR が設定されていることを確認します。
7. ライブセッションを開始（モードを選択）：
   • モード A：run_code でひな形を実行します。必要に応じて login(<role>) を呼び出し、その後 I.amOnPage(<start URL>) を実行します。返された情報（URL、ARIA スナップショット、スクリーンショット、コンソール）が、以降のすべての作業の根拠になります。
   • モード B：テストファイルに最小限ながら実際に動作する下書きを記述します。

     Before(({ login }) => login('admin'))   // if needed
     
     Scenario('draft - feature exploration', ({ I }) => {
       I.amOnPage('/dashboard')
       pause()
     })
     

     MCP の run_test から実行すると、{ status: 'paused', pausedAfter, page, suggestions } が返されます。これで、テスト自体の I／ブラウザーを run_code から操作できる状態になります。
8. ページを調査 — codeceptjs-exploration に引き継ぎます。まず ARIA スナップショットを使い、次に必要であれば HTML に切り替えます。候補を列挙して区別し、run_code でロケーターが要素 1 つだけに一致することを確認してから確定します。モード B では、これは一時停止中に行います。
9. Scenario を作成 — スクラッチパッドで run_code を使い、一度に 1～2 個のコマンドを実行します。各実行後に、URL／ARIA が想定どおり変化したか、新たなコンソールエラーがないか、取得した値が想定と一致するかを確認します。
   • ステップが失敗した場合は、別のロケーターを試す、具体的な waitFor* を追加する、またはフローを見直します。
   • 本当に判断が難しい場合（Save ボタンが 2 つある、空の状態が不明確、機能フラグの可能性があるなど）は、作業を止めてユーザーに確認します。
   • Cookie バナーなどの任意の UI 要素には、if ではなく await tryTo(...)（fundamentals § Effects）を使います。Scenario を直線的に保てます。
10. 検証済みの手順を確定：
    • 既存の命名規則に合わせ、ファイルごとに Feature を 1 つだけ記述します。
    • 適切な場合はページオブジェクトのメソッド／カスタムステップを使い、セレクターを重複させないようにします。
    • すべてのロケーターを読みやすい形式に置き換えます（優先順位は以下を参照）。確定コードでの厳密な { css }／{ xpath } の使用は、他に適切な方法がない場合を除き、レビュー上の警告サインです。
    • 認証情報には環境変数のみを使い、secret(...) でラップします。
    • モード B：pause() の行を一連の手順に置き換え、draft - ... を実際の目的を表す名前に変更します。
11. 最終確認：aiTrace を有効にして npx codeceptjs run --grep '<scenario>' --steps を実行し、出力を codeceptjs-run-analysis に渡して、output/trace_*/ でフローが問題なく実行されたことを確認します。そこで成功した場合にのみ完了です。

ロケーターの優先順位（作成時）

常にコンテキストを渡してください。理由については codeceptjs-fundamentals § ロケーターを参照してください。優先度の高い順です。

1. セマンティック文字列 — 表示テキスト、ラベル、プレースホルダー、name、aria-label：I.click('Save', '.toolbar')
2. ARIA ロール — コンテキスト内でテキストが曖昧な場合（「Delete」のリンクとボタンの両方がある場合）、またはロールがアサーションの一部である場合：I.click({ role: 'button', name: 'Sign In' }, '#login-form')
3. customLocator を使った $name — アプリが data-testid／data-qa を広範に提供している場合
4. locate() ビルダー — 構造条件を指定する場合。構造に関する条件は、多くの場合コンテキスト側に含められます：I.click('Edit', locate('tr').withText('Acme Corp'))
5. 厳密な { id }／{ name }／{ css } — 上記の方法を使い尽くした場合の最終手段
6. { xpath } — ビルダーで表現できない軸やテキスト述語を使う場合

基礎ルールに加え、作成時に適用される具体的なルール：

• 通常の文字列はすでに aria-label に一致します。'aria-label=Save' や { css: '[aria-label="Save"]' } は決して記述しないでください。
• 安定したコンテキストを優先してください。ランドマーク（nav、main、{ role: 'dialog' }）、アプリシェルのコンテナー（.sidebar、.modal）、データで識別される行やカードを使います。
• I.see／I.dontSee にはコンテキストが必要です — 最初の引数はページ全体から照合される通常のテキストです。スコープを指定しないと、ナビゲーションやフッターの内容で誤ってパスすることがあります。
• 複数の要素に一致する場合は、step.opts({ elementIndex: N })（1始まり、負の値、'first'／'last'）または step.opts({ exact: true }) を使います。codeceptjs/steps から step をインポートしてください。

作成中の待機

• 自動待機はインタラクションをカバーします。MCP ステップの間に、ライブ HTML／ARIA からゲート要素（スピナーのオーバーレイ、フェッチ後のレンダリング）を検出し、安定したセレクターと具体的な waitFor* を選んでください。
• I.wait(N) は 作成中 に、タイミングに関する仮説を確認する目的で使用してもかまいません。スリープを入れるとステップがパスするなら、原因はタイミングです。コミットする前に、具体的な waitFor* に置き換えてください。

避けるべきこと

• 想像上のロケーターやルートを使ってテストを書くこと。すべてライブページから取得してください。
• セマンティックな方法／ARIA／locate() が適している場面で、厳密なロケーターを使うこと。
• 短いロケーターとコンテキストを使わず、スコープを指定しない長いロケーターを使うこと。
• アクセシブル名を明示したり、呼び出し箇所ごとに [data-testid=...] を繰り返したりすること。
• ハードコードされた認証情報をどこかに記述すること。
• 類似テスト／ページオブジェクトの調査を省略すること。
• 通常のアクションステップに await を使うこと（基礎ルールの await 規則）。また、自動待機を確認する前に waitFor* を推測で使うこと。
• コミットするテストに I.wait(N) や pause() を残すこと。
• 実際に未知のフローに Mode A を使うこと。Mode B より遅く、状態を失いやすくなります。
• エンドツーエンドの aiTrace 実行をせずに完了とすること。

関連スキル

• codeceptjs-fundamentals — ルール、効果、調査（最初に実行）
• codeceptjs-exploration — ページの調査、WebElement API
• codeceptjs-auth — ログイン／セッションの再利用
• codeceptjs-run-analysis — トレースの検証
• debugging-codeceptjs-tests — コミットしたテストが正常に動作しない場合