debugging-codeceptjs-tests

CodeceptJS 4 テストのデバッグ

失敗の原因は誤解を招くことがあります。エラーはたいてい、それ以前の何か（認証の期限切れ、フレームの切り替え漏れ、ネットワークリクエストの保留など）による副作用として発生したステップを指しています。再現し、状態を取得して確認してから、修正します。

方法

• MCP 優先（AI エージェント向け）：run_test／テスト内の pause() を使うと、テストが使用するのと同じ I／ブラウザーで、エージェントに制御が渡されます。run_code／snapshot で調査し、run_step_by_step + continue でステップごとに実行します。
• CLI による代替手段（人間／CI／フレームワーク内部向け）：--debug → --verbose → DEBUG="codeceptjs:*" の順に試します。DEBUG の切り札を使うのは、レコーダーのハング、プラグインの競合、イベントの漏れ、「ステップが実行されない」など、フレームワーク内部に原因があると疑われる場合のみです。名前空間：codeceptjs:recorder、codeceptjs:pause、codeceptjs:ai、codeceptjs:plugin:<name>。

pause() は操作する側に応じて動作を切り替えます。TTY では readline REPL を起動し、MCP ではエージェントに制御を渡し、TTY でも MCP でもないサブプロセスでは通知を出力して処理を完了します（CI のデッドロックを防ぎます）。

ワークフロー

1. 基本事項 — codeceptjs-fundamentals を実行します。ヘルパー、プラグイン（aiTrace、screenshot、pageInfo、retryFailedStep、pause、auth）、環境変数、MCP の利用可否を確認します。aiTrace が宣言されていない場合は、plugins: { aiTrace: { enabled: true } } を一度だけ追加します。このスキルの大半は、その出力を活用します。

   • 一度だけ宣言し、トリガーを変更するために設定を編集しないでください。 -p aiTrace:on=step|fail|test|file|url で実行ごとに上書きします（fundamentals § Plugins from CLI）。簡潔な CI 再現には on=fail、診断中は on=step を使います。設定の on: を切り替えると、リポジトリに不要な変更が発生し、ほかの実行にも影響します。

2. 最小限の手順で再現する：npx codeceptjs run --grep '<scenario>' --steps を実行します。CI 固有の場合は -c codecept.ci.conf.js を追加します。計測を始める前に、再現できることを確認します。

3. ツールを選ぶ：

   • MCP run_test <test> — プロセス内で実行します。レポーターの結果、または { status: 'paused', pausedAfter, page, suggestions } を返します。
   • MCP run_step_by_step + continue — 各ステップの後で一時停止します。フロー全体を確認する場合に使います。
   • MCP run_code — ライブセッションで任意のコードを実行します。新規セッションでも一時停止中でも動作し、生成された値、コンソール出力、最終状態のスナップショットを返します。
   • MCP snapshot — 操作を行わずに現在のブラウザー状態を取得します（URL、Cookie、ストレージ、HTML、ARIA、スクリーンショット、コンソール）。
   • MCP list_actions — I.* メソッドが存在するか確認します。
   • CLI npx codeceptjs run --grep '<scenario>' --debug — MCP を使わない場合の最初の手段です。--verbose を追加すると、プロミスキュー、リトライ、タイムアウトのログも表示されます。

4. ブレークポイント：

   • テスト内の pause() — すでに編集している場合や、within／ループ／フックの中で停止する場合に最適です。
   • run_test の pauseAt: N — テストを編集せずに、N 番目のリーフステップの後で一時停止します。
   • N の特定方法：npx codeceptjs dry-run --debug --grep '<scenario>' --numbers --no-ansi を実行します（テストごとに 1 から採番され、停止する行の番号です）。
   • 一時停止中：run_code で調査し、snapshot でクリーンな状態を取得します。output/trace_<TestName>_<hash>/trace.md で前のステップを確認し、continue で再開します。

5. トレースを読む — codeceptjs-run-analysis に引き継ぎ、最初の失敗ステップに注目します。後の失敗は、先に見逃された問題の副作用であることがほとんどです。このスキルでは、大きな HTML の grep、複数のトレースにまたがるエラーの分類、再実行の比較についても扱います。

6. 仮説を立てる：

   症状	考えられる原因
   要素が見つからず、ページが /login	認証：セッションキャッシュが古い、環境変数がない
   要素は HTML にあるが display: none	waitForElement ではなく waitForVisible を使う
   ロケーターが 2 件以上に一致する（strict モード）	範囲を指定します：context 引数、次に ARIA ロール、次に step.opts({ elementIndex })
   スクリーンショット N+1 では要素があり、N ではない	アニメーション／遅延読み込み → waitForVisible(loc, t)
   console.json に 401/403	API トークンの期限切れ、または環境変数がない
   ステップは成功するが、次の I.see が失敗する	フレームの切り替え漏れ → within({ frame })
   CI とローカルで結果が異なる	setHeadlessWhen(CI)、ビューポート、タイミング、環境変数
   レコーダーが停止し、ステップが実行されない	DEBUG="codeceptjs:recorder"
   プラグインが正しく動作しない	DEBUG="codeceptjs:plugin:<name>"

7. ライブページで修正を検証する — ファイルを編集する前に、候補の置き換えステップを run_code で試します（一時停止中に、同じ I を使って動作します）。TTY を使う場合も、テスト内の pause() で同じことができます。

8. 修正して再実行する：編集後、npx codeceptjs run --grep '<scenario>' --steps を実行します。codeceptjs-run-analysis で確認し、失敗箇所が別のステップに移っていないことを確かめます。修正で waitFor* または step.opts を追加する場合は、1 行の Why: コメントを残してください。こうしたコメントは残しておく価値があります。

codeceptq でクエリトレースの HTML を調べる

aiTrace は、ステップごとの <NNNN>_<step>_page.html スナップショットを出力します（1 行に 1 要素で、行番号は要素と 1 対 1 で対応します）。codeceptq は、保存済みスナップショットに対して CodeceptJS のロケーターを解決します。

• ページ HTML を手動でコンテキストに読み込まないでください。スナップショットは数千行に及びますが、codeceptq は一致した要素とその行番号だけを返します。
• run_code で適用する前に、候補のロケーターをオフラインでテストしてください。一致すれば実環境で試す目安になりますが、保証ではありません（表示状態、再レンダリングなど）。
• 複数一致した場合は、より壊れやすい XPath を書かず、codeceptq が出力した順序に従って step.opts({ elementIndex }) で区別してください。

npx codeceptq '#submit-btn' --file output/trace_*/0007_*_page.html     # CSS
npx codeceptq 'Email' --field --file output/trace_*/0003_*_page.html   # semantic field
npx codeceptq 'Save' '.modal' --click --file output/trace_*/0005_*_page.html  # scoped clickable
npx codeceptq 'Username' --field --json --file ...                     # machine-readable

主なフラグ：--field/--click/--checkable/--select はセマンティックな方法を強制します。--xpath/--css は自動判定を上書きします（select.foo のようなタグ名だけの指定は、あいまいなテキストとして扱われます）。終了コードは、一致が 0、なしが 1、入力が無効な場合が 2 です。

⚠ 2 番目の位置引数 [context] ではスコープを指定できません（CodeceptJS 4.1.0）。N matches within '<ctx>' と表示されますが、返されるのはページ全体の結果です。lib/command/query.js はコンテキストノードに対して絶対 XPath（//…）を評価し、//foo はドキュメントを起点にし直すためです。要素を含まないコンテナー内の一致も報告されます。オフラインでスコープ付きロケーターを確認するには、セレクターを 1 つにまとめて（codeceptq '.modal button[aria-label="Save"]'）、スコープなしの形式と一致件数を比較してください。コンテキストに依存するロケーターを本当に検証できるのは、ステップを実行した場合だけです。

さらに詳しく調べる

トレースで失敗した内容は分かっても、ページの状態をさらに詳しく知る必要がある場合（「このボタンは実際に無効になっているか？」「Save ボタンは本当に 2 つあるか？」）は、codeceptjs-exploration に引き継いでください。デバッグ時に役立つ方法は次のとおりです。

• ボタンは描画されているのにクリックが効かない → grabWebElement('Submit') + isEnabled() + getBoundingBox()（無効になっているか？ 画面外にあるか？）
• Strict モードで複数一致 → exploration の、広い XPath を反復して一致を絞り込むパターン
• Iframe のコンテンツ → 失敗するステップを within({ frame }) で囲む

調査には usePlaywrightTo/useWebDriverTo よりもこちらを優先してください。ヘルパー間で同じコードが使え、定型コードも少なくなります。

ネイティブヘルパーでの回避策

I.* の機能では本当に対応できない場合（ネットワークのインターセプト、ストレージの操作、ヘルパー専用 API）に限り、次を使ってください。

• Playwright：I.usePlaywrightTo('label', async ({ browser, browserContext, page }) => { ... })
• Puppeteer：I.usePuppeteerTo('label', async ({ page }) => { ... })
• WebDriver：I.useWebDriverTo('label', async ({ browser }) => { ... })

ラベルはステップの出力とトレースに表示されます。MCP の run_code 内でも動作します。これらを使うとテストが特定のヘルパーに依存するため、最終手段としてください。

ヘルパーの注意点

• Playwright：strict: true は複数一致時にエラーをスローします。'networkidle' より 'load'/'domcontentloaded' を優先してください。trace: 'on' → output/trace.zip（npx playwright show-trace）
• Puppeteer：長時間ポーリングするページでは 'networkidle0' が停止するため、'networkidle2' または 'domcontentloaded' を使ってください
• WebDriver：smartWait が対象とするのはアクションのみで、アサーションは対象外です。executeScript の引数は JSON でシリアライズ可能である必要があります

認証関連の失敗

テスト中に /login へリダイレクトされたり、コンソールに 401/403 が表示されたりする場合は、失敗したステップではなく認証を修正してください。プラグインの check、認証情報の環境変数、output/<role>_session.json にある古いキャッシュ済みセッションを確認してください（削除すると再ログインが強制されます）。全体的なパターンについては codeceptjs-auth を参照してください。

不安定な動作と待機

「断続的な」失敗の多くは、待機の見落としが原因です。汎用的な遅延を追加するのではなく、トレース HTML/ARIA を使って実際に処理を妨げている要素を特定してください（基本事項 § Waiting に対応関係があります）。デバッグ中の I.wait(N) はタイミングに関する仮説の確認には使えますが、コミット前に具体的な waitFor* に置き換えてください。

避けること

• トレースを読まずに、エラーメッセージだけを見て修正すること。
• run_code で修正を検証する前にテストを編集すること。
• pause() の呼び出しをコミットすること。デバッグ専用です。
• 実際のゲーティング要素を特定せず、むやみに waitFor* を使うこと。
• コミットするテストに I.wait(N) を残すこと。
• 実行のたびに設定ファイルの aiTrace の on: を編集すること。一度だけ宣言し、実行ごとに上書きしてください。
• 設定の確認を省略すること。setHeadlessWhen(CI) や環境変数による URL 設定が、「ローカルでは動くのに CI では失敗する」問題の原因であることは少なくありません。
• 原因を修正せず、retries で失敗を隠すこと。

関連スキル

• codeceptjs-fundamentals — 効果、CLI からのプラグイン、待機ルール
• codeceptjs-exploration — WebElement の検査、広範な XPath の曖昧さの解消
• codeceptjs-run-analysis — trace.md の読み進め方、エラーの分類、再実行の比較
• codeceptjs-auth — 認証失敗のパターン