zudo-test-wisdom
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

テスト時の必須行動

フロントエンドコードをテストする際のAIエージェントの必須行動。

5つのコアルール

フロントエンドコードに取り組むすべてのAIエージェントは、テスト時にこの5つのルールに従う必要があります：

ルール1: 最初にテスト計画を宣言する

テストを書いたり検証を実行したりする前に、以下を明示します：

  • 何をテストするか

  • どのレベルを使用するか

  • なぜそのレベルが適切か

Test plan:
- Testing: notification banner visibility after CSS fix
- Level: 5 (verify-ui + screenshot)
- Reason: This is a visual bug — the element exists in DOM but
  user reports it's not visible. Need to check computed styles.

Note

テスト計画を宣言することで、習慣的にレベル1をデフォルトにしてしまうよくある間違いを防げます。意識的なレベル選択を強制します。

ルール2: テストレベルを目標に合わせる

テストレベルは実際に検証しているものと一致しなければなりません：

検証している内容最低限使用すべきレベル
関数が正しい値を返すレベル1
コンポーネントが正しい要素をレンダリングするレベル2
ビルド出力に期待されるコンテンツが含まれるレベル3
ユーザーフローがブラウザで動作するレベル4
何かが視覚的に正しいレベル5
canvas／フォトエディタなどでL4が書けず、かつL5でも到達できないレベル6（最終手段、CIには使わない）

レベル5の問題にレベル1を使用しないでください。テストはパスしますが、バグは残ります。L4が難しいだけ、L5が扱いにくいだけでレベル6に飛ばないでください — L6は下位の両方の階層が真に実行不可能な場合にのみ正当化されます。

ルール3: 下位レベルがパスしても問題が解消しない場合はエスカレーションする

テストがパスしたにもかかわらず、ユーザーが問題が修正されていないと言う場合：

  1. 同じテストを再実行しない

  2. ユーザーにキャッシュのクリアを提案しない

  3. 次のテストレベルにエスカレーションする

  4. すでにレベル4の場合、レベル5にエスカレーションする

  5. レベル5の場合、より深く調査する（祖先要素、スタッキングコンテキストなどをチェック）

  6. レベル6（AIベース）には、L4が書けないかつL5がアサーションに届かない場合のみエスカレーションする。L6はレベル5の次のデフォルトのステップではない — 決定論的なチェックが不可能なcanvas／フォトエディタ系のサーフェスのために確保された階層です。

Warning

「ブラウザキャッシュをクリアしてください」や「ハードリフレッシュしてください」を解決策として提案しないでください。 ユーザーがまだ壊れていると言う場合、コードがまだ壊れています。キャッシュのせいにするのではなく、実際の原因を調査してください。

ルール4: UI/CSSはデフォルトでレベル5

以下に関わるタスク：

  • CSSの変更

  • レイアウトの変更

  • 表示の問題

  • 視覚的な外観

  • レスポンシブデザイン

  • 間隔、色、フォント

はレベル5の検証をデフォルトにすべきです。下位レベルはCSSの正しさを検証する構造的能力がありません。

ルール5: テストしなかったものを報告する

テスト後、ブラインドスポットを明示的に述べます：

Verification complete:
- Tested: computed styles confirm banner has display:block,
  opacity:1, and parent has overflow:visible
- Screenshot: banner is visible at top of page
- NOT tested: responsive behavior at mobile breakpoints
- NOT tested: animation transition timing

この透明性により、追加のテストが必要かどうかをユーザーが判断できます。

4つの実行ルール

階層化されたテストスイートの中で動作するエージェントは、さらにこの4つのルールに従う必要があります。検証アーティファクト、ティアタグ、および昇格ライフサイクルの背景については、実行ティアを参照してください。

ルール6 — 検証テストは自己昇格しない

エージェントが作成した検証スペックには @verification タグを付け、すべてのゲートから除外します。ティアへの昇格は明示的で意図的なステップです：

  1. @verification タグを削除する

  2. 適切なティアタグを割り当てる（例：@heavy、@gpu）

  3. 対象スイートの時間予算内に収まることを確認する

エージェントは自分の検証テストを自己昇格させません。PRの説明で昇格を提案し、決定はレビュアーに委ねます。

# PR description excerpt
## Verification spec — graduation proposal
- spec: tests/banner-render.spec.ts
- currently: @verification (excluded from gates)
- proposed tier: T1 (untagged CI-safe e2e)
- rationale: stable for 5 runs, sub-2s, no platform dependency
- action needed: reviewer removes @verification tag and assigns tier

Note

検証アーティファクトと回帰ゲートの概念、および完全な昇格ライフサイクルは実行ティアページにあります。このルールが定めるのはエージェントの強制可能な行動のみです：タグを付け、昇格を提案し、自己昇格しない。

ルール7 — 赤いチェックは作者をブロックする

自分が作成したPRにある赤いチェックは、リポジトリ設定で必須チェックとして指定されているかどうかに関わらず、あなたをブロックします。唯一の例外：失敗したテストに、リンクされたオープンなissueを伴う @flaky タグがある場合。

# Blocked — do not merge
PR #42 authored by agent-session-A
  ✗  unit: auth-service.test.ts — 1 failed
     (not a required check, but authored by this session)
  → investigate and fix before declaring done

# Not blocked — exception applies
  ✗  e2e: flaky-animation.spec.ts @flaky — see issue #38
     (quarantined; allowed-to-fail in scheduled tier)
  → merge may proceed; issue #38 tracks the fix

Warning

「そのチェックは必須ではない」というのは、自分のPRの赤い結果を無視する正当な理由にはなりません。必須チェックのステータスはCI設定の詳細です — あなたの作者としての責任はそれとは独立しています。

ルール8 — ゲートを不正操作しない

以下のいずれも、リンクされたオープンなissueの参照なしに導入してはなりません：

  • 既存のテストへの test.skip

  • 以前はパスしていたテストへの @flaky タグ

  • スクリーンショット許容値の緩和（例：ピクセル閾値の引き上げ）

  • アサーションの削除

既存のアサーションを編集してゲートをパスさせる場合、テスト差分についてフレッシュコンテキストのレビューが必要です — 元の変更を作成したのと同じセッションで編集を適用してはなりません。

# Wrong — no issue reference
test.skip('banner renders correctly', () => { ... })

# Wrong — no issue reference
expect(page).toHaveScreenshot({ maxDiffPixels: 500 }) // was 50

# Right
test.skip('banner renders correctly', () => { ... })
// @flaky: issue #55 — animation timing non-deterministic on CI

ルール9 — スコープを絞った重い検証

変更がヘビーレーンテスト（@heavy、@gpu、@interactive、または @macos-only タグの付いたもの）のみでカバーされているコードに触れる場合、作業完了を宣言する前に、関連するヘビースペックを対応可能なホスト上で実行してください。あるいは、ブランチに対してexamワークフローをディスパッチしてください。

どのテストがヘビーレーンとみなされるか、またどのホストが必要かを特定する方法については、ヘビーテスト判断ルールを参照してください。

# Before declaring done — change touches GPU rendering path
$ gh workflow run exam.yml --ref my-feature-branch
# or, if running locally on a capable host:
$ pnpm exec playwright test --grep "@gpu" tests/gpu-render.spec.ts

Warning

変更されたコードのヘビーレーンカバレッジを実行せずに作業完了を宣言することは、ゲートをスキップすることと同等です。スケジュールされた再検証がそれを検出しますが、その遅延は回帰ウィンドウを生み出します。

サマリーチェックリスト

修正完了を宣言する前に：

  • [ ] テスト前にテスト計画を宣言した

  • [ ] テストレベルが変更の性質と一致している

  • [ ] テストがパスしたがユーザーが失敗を報告した場合、次のレベルにエスカレーションした

  • [ ] CSS/ビジュアルの変更にはレベル5を使用した

  • [ ] テストしたものとしなかったものを報告した

  • [ ] 新しい検証スペックには @verification タグが付いており、自己昇格していない

  • [ ] 自分のPRの赤いチェックはすべて解決済み、またはリンクされたissueを伴う @flaky タグがある

  • [ ] test.skip、@flaky、または許容値の緩和はリンクされたissueなしに導入していない

  • [ ] 変更がヘビーレーン専用のコードに触れる場合、対応可能なホスト上で関連するヘビースペックを実行した

Revision History

Takeshi Takatsudo作成: 2026-04-04T07:11:52+09:00更新: 2026-06-17T02:14:42+09:00