ci-fix-tests

CI での CodeceptJS テストの自動修復

非対話型の自動修復ループです。output/ にある失敗テストのベースライン（aiTrace がトレース成果物を残した場所）を読み込み、安全な修正をいくつか試し、失敗したシナリオだけを再実行して結果を比較し、output/ci-fix.md にレポートを書き込みます。効果のなかった編集はロールバックします。

保守的な設計です。 CI は、テストの構成を変更したり、抽象化を変えたり、人間の判断が必要な問題を修正したりする場所ではありません。目標は「実行をパスさせる」ことです。リスクの高い内容はすべてレポートでエスカレーションします。

このスキルでは、動作する git チェックアウトが必要です。元の状態に戻すには git checkout -- <file> を使用します。

ワークフロー

1. ベースラインの失敗を読み取る

既存の output/trace_*/ 成果物に対して codeceptjs-run-analysis スキルを使用し、失敗したシナリオをすべて列挙します。以下を記録します。

• 失敗したテストのセット（ファイルパス＋シナリオ名）
• 各テストで失敗したステップと、関係するロケーター／待機処理／アサーション
• 失敗ごとのクラスタシグネチャ（個別の問題か、システム全体の問題かを明確にするため）

これをベースラインとして保存します。count、failing_set、clusters を記録します。

2. 安全に修正できる候補を選ぶ

以下の許可されたリストにある修正のみを試します。

• ロケーターのずれ — 失敗したロケーターでは何も見つからなくなったものの、類似の要素が存在する場合。候補を探すには codeceptjs-exploration スキル（ヘッドレス）を使用します。安定した領域にスコープされた短いロケーターを、次の順序で選択します。I.click('Save', '.toolbar') — 可視テキスト／アクセシブル名 → ARIA { role, name } → $name（customLocator）→ 複合 CSS。失敗したステップのロケーターのみを置き換えます。
• スピナー／ローダー／モーダルに対する待機の不足 — 失敗したステップの ARIA スナップショットにスピナーまたはスケルトンが表示されている場合、あるいは対象要素が後から表示される場合。失敗したステップの直前に、条件に一致する I.waitFor* を1つ追加します。
• I.wait(N) の置き換え — ハードコードされたスリープだけが、失敗するアサーションと成功するアサーションの間にあり、条件となる要素を特定できる場合、スリープを特定の waitFor* に置き換えます。

次の修正は試さないでください。

• 認証／資格情報／環境変数の修正 — これらはテストコードではなく、CI 設定に関するものです。
• リファクタリング（ページオブジェクトやカスタムヘルパーの抽出、シナリオの分割）。
• シナリオ名またはタグの変更 — CI の --grep やパイプラインがこれらを参照しています。
• シナリオへの retries: N の追加 — 不安定さを隠すかどうかは人間が判断します。
• 失敗したテストファイル以外の変更（codecept.conf.*、ヘルパー、PO の編集は禁止）。

失敗が許可された修正パターンに当てはまらない場合は、スキップし、レポートで unresolved として記録します。

3. 編集を適用して再実行する

変更ごとに、ファイルパス、行番号、変更前／変更後のスニペット、修正の種類を記録します。その後、CI で使用したのと同じ設定で失敗したシナリオのみを再実行します。

npx codeceptjs run --grep '<scenario>|<scenario>|...'

package.json のスクリプトまたは CI ワークフローファイルから適切な設定を特定します。元の実行で run-workers が使用されていた場合は、ワーカー数を一致させます。

4. ベースラインと比較する

再度 codeceptjs-run-analysis を使用して、修正後に失敗したテストのセットを列挙します。

修正後の失敗セットとベースラインの比較	ステータス
空（失敗ゼロ）	SUCCESS_FULL
ベースラインの厳密な部分集合	SUCCESS_PARTIAL
同一のセット	NO_IMPROVEMENT
より大きい、またはベースラインにないテストを含む	REGRESSED

5. 維持するか、ロールバックするかを判断する

• SUCCESS_FULL／SUCCESS_PARTIAL → 編集を維持します。
• NO_IMPROVEMENT／REGRESSED → git checkout -- <files> ですべての編集をロールバックします。このスキルの終了時に、ディスク上の状態が開始時と同一でなければなりません。

リグレッションは改善なしと同じ扱いです。試みは成功せず、作業状態は実行前にディスク上にあった状態です。「悪い変更だけを元に戻す」ことはしないでください。バッチ全体を元に戻します。

6. レポートを書く（必須）

結果にかかわらず output/ci-fix.md を書き込みます。CI は結果を表示するためにこのファイルを読み込みます。

レポート形式

# CI Fix Report — <ISO timestamp>

**Status:** SUCCESS_FULL | SUCCESS_PARTIAL | NO_IMPROVEMENT | REGRESSED

## Baseline
Failing scenarios: N
- `tests/foo_test.js` — "user can log in"
- `tests/bar_test.js` — "checkout flow"
- ...

## Attempted fixes
- `tests/foo_test.js:42` — locator drift: `I.click('Save')` → `I.click('Save', '.toolbar')`
- `tests/bar_test.js:15` — added `I.waitForInvisible('.spinner')` before checkout click
- `tests/baz_test.js:7` — replaced `I.wait(3)` with `I.waitForVisible('.confirmation-dialog', 10)`

## Result
Failing scenarios after fix: M (was N)
- Resolved: `tests/foo_test.js` — "user can log in"
- Still failing: `tests/bar_test.js` — "checkout flow"
- New failures (REGRESSED only): `tests/baz_test.js` — "edit profile"

## Failure clusters (NO_IMPROVEMENT / REGRESSED only)
- **Cluster A (3 scenarios)** — `Element not found: button.btn-primary`. Likely a deploy regression or design change.
- **Cluster B (1 scenario)** — `Navigation timeout to /checkout`. Possible backend issue.

## Discarded changes (NO_IMPROVEMENT / REGRESSED only)
- `tests/foo_test.js` — restored
- `tests/bar_test.js` — restored
- `tests/baz_test.js` — restored

Status: の1行目は、機械で解析可能なシグナルです。残りの内容は、CI ビルドの失敗を確認する人向けです。

避けるべきこと

• 失敗したテストファイル以外のファイルを編集すること。このモードでは、設定、ヘルパー、ページオブジェクト、CI ワークフローは変更できません。
• 1 回の作業で同じシナリオに複数種類の修正を試みること。1 つ修正して結果を確認してから、次を試してください。
• 不安定さを隠すために retries: N を設定すること。これは人間が判断します。
• NO_IMPROVEMENT の場合にロールバックを省略すること。変更がなくても、次の実行や次のレビュー担当者を混乱させる可能性があります。
• output/ci-fix.md を一部だけ書いたり、作成しなかったりすること。CI はこのファイルに依存しており、レポートがないこと自体が失敗の原因になります。
• 検証時にスイート全体を実行すること。CI の実行時間を抑えるため、最初に失敗したシナリオだけを実行してください。

関連スキル

• codeceptjs-run-analysis — ベースライン、クラスタリング、修正後の比較
• codeceptjs-exploration — ドリフトが発生した場合の代替ロケーター
• codeceptjs-fundamentals — 設定、ヘルパー、CI 環境