codeceptjs-run-analysis

CodeceptJS の実行分析

npx codeceptjs run の実行後、トレースの成果物は output/ に保存されます。このスキルでは、MCP 経由で再実行せず、bash ツールを使って適切なステップ、適切なファイル、巨大な HTML スナップショットの適切な範囲を効率的に読み取ります。

最終的な目的は一つではありません。状況に合ったユースケースを選んでください。基礎知識はどのユースケースにも当てはまります。

基礎知識

• aiTrace を有効にしてください。 すべての分析は output/trace_<TestName>_<hash>/trace.md に依存します。有効な設定を確認してください（不明な場合は codeceptjs-fundamentals を実行してください）。無効の場合はスクリーンショットと pageInfo のダンプしかないため、詳細な分析の前に有効化して再実行するよう提案してください。
• run_step_by_step はインタラクティブな実行専用です。ステップごとのファイルを生成するのは aiTrace だけです。アドホックな run_code / snapshot では、output/trace_run_code_* / output/snapshot_* に単発のバンドルが生成されます。
• トレースを見つけます：再実行すると新しいディレクトリが作成されます。どれか不明な場合は、最新のものを使います（ls -dt output/trace_*）。
• 最初に trace.md を読みます。各ステップとその成果物を結び付けるインデックスです。
  • 失敗したステップに注目します。失敗のマークがない場合は、トレース内の最後のステップを確認します。
  • 失敗のマークが複数ある場合は、通常、最初の失敗が原因で、残りはその連鎖です。

注目するステップの成果物の読み取り順（NNNN_<step>）

成果物	用途
NNNN_*_aria.txt	最初に読みます。簡潔で構造化されており、重複を見つけやすくなっています
NNNN_*_screenshot.png	見た目を確認します。レイアウト、アニメーション、「描画されているが正しくない」状態など
NNNN_*_console.json	消えた要素の原因となる JavaScript エラー、4xx/5xx、非推奨の警告を確認します
NNNN_*_storage.json	このステップの Cookie と localStorage です。認証が疑われる場合は最初に確認します
NNNN_*_page.html	最終手段として、grep 経由でのみ読みます

大きなファイルを丸ごと読まないでください

• HTML スナップショット：grep で検索します（テキスト、クラス、aria-label、data-*）。行番号と前後のコンテキストを指定すると、検索結果を読みやすく保てます。
• console.json：すべてのエントリを読まず、jq で絞り込みます。
• 多数のファイルを調べる場合：grep -l でファイル名だけを抽出します。

ユースケース

修正が維持されているか確認する

最新のトレースを見つける → trace.md を読む → FAILED マーカーがないことを確認します。そのついでに console.json をざっと見て、対処すべき警告がないか確認します。

CI バッチ全体のエラーを分類する

すべての trace.md から失敗したステップの行を抽出し、署名ごとにグループ化して（grep + sort + uniq -c）、頻度順に並べます。

• 多くのテストで同じエラーが発生している場合は、システム全体に関わる問題です（環境変数、認証、ベース URL、デプロイのリグレッション）。根本原因を一度修正し、バッチを再実行します。
• テストごとに異なるエラーが発生している場合は、個別の問題です。一つずつトリアージします。 最も頻度の高い根本原因から調査し、再実行して該当するテストがいくつ解決したか確認します。

不安定な動作を診断する

同じテストを 5～10 回再実行し、各トレースでどのステップが失敗したかを比較します。

• 実行ごとに異なるステップで失敗する → タイミング、環境、外部サービス
• 同じステップで失敗し、状態が異なる → 待機が不足しているか不適切です。実行間でそのステップの ARIA スナップショットを diff します
• 実行ごとに console.json が異なる → 一時的なバックエンドまたはネットワークのエラー
• バウンディングボックスが異なる → レイアウトの再フローまたはコンテンツの遅延読み込み

単一の失敗を調査する

失敗したステップ、または最後のステップを対象にします。まず ARIA とスクリーンショット、次にコンソール、最後に HTML を確認します（grep のみ）。仮説を立てます。トレースだけでは不十分、またはページを直接操作する必要がある場合は、debugging-codeceptjs-tests に引き継ぎます。

分析後

• システム全体に関わる原因 → テストごとではなく、根本原因（環境、認証、デプロイ）を一度修正します
• ロケーターのずれ → codeceptjs-exploration
• タイミングや待機の問題 → fundamentals / writing スキルの待機に関するガイダンスを参照します。I.wait(N) を具体的な waitFor* に置き換えます
• 静的分析では解決できない → debugging-codeceptjs-tests（ライブ MCP ループ）
• 正常に通過 → 完了です。ただし、念のため console.json もざっと確認します

避けること

• 大きな HTML や console.json を丸ごと読むこと。grep / jq を使います。
• 最後にマークされた失敗で止まり、最初の失敗を確認しないこと。
• 分類せずに個々の失敗をトリアージすること。
• 単一の実行だけで不安定さを判断すること。5 回以上の再実行が必要です。
• 調査中に output/ を削除すること。

関連スキル

• codeceptjs-fundamentals — 設定内容、aiTrace の -p による上書き
• codeceptjs-exploration — ロケーターのずれの修正
• debugging-codeceptjs-tests — codeceptq を使ったライブ実行ループとオフラインでのロケーター解決