plan-tests

テストを計画する

クイックリファレンス

変更の種類	最初のスペック	パス	理由
API コントラクト、パラメータ、ステータスコード、JSON の形状	リクエストスペック	spec/requests/	実際の HTTP コントラクトを証明します
まとまりのあるレコードまたは値オブジェクトに対するドメインルール	モデルスペック	spec/models/	ドメインの振る舞いを迅速にフィードバックします
複数の協調オブジェクトにまたがる多段階のオーケストレーション	サービススペック	spec/services/	ワークフローの境界に焦点を当てます
エンキュー/実行/リトライ/破棄の振る舞い	ジョブスペック	spec/jobs/	非同期のセマンティクスを直接捉えます
重要な Turbo/Stimulus またはブラウザから見えるフロー	システムスペック	spec/system/	ブラウザ操作が本当のリスクである場合にのみ使用します
エンジンのルーティング、ジェネレーター、ホスト統合	エンジンスペック	spec/requests/ またはエンジンのパス	通常のアプリスペックではエンジンの配線を見逃します — test-engine を参照してください
バグ修正	再現スペック	バグが観測される場所	修正を証明し、リグレッションを防ぎます

HARD-GATE

CHECKPOINT: Test Design Review

1. Present: Show the failing spec(s) written
2. Ask:
   - Does this test cover the right behavior?
   - Is the boundary correct (request vs service vs model)?
   - Are the most important edge cases represented?
   - Is the failure reason correct (feature missing, not setup error)?
3. Confirm: Proceed after the test design meets the accepted requirements and RED is observed.

コアプロセス

不要なセットアップを最小限に抑えつつ、振る舞いを証明できる最も価値の高い境界から始めます。

手順

1. 振る舞いに名前を付ける: 証明すべきユーザーから見える結果または不変条件を述べます。
2. 境界を特定する: その振る舞いが最初に観測される場所を決めます — HTTP リクエスト、サービスのエントリポイント、モデルルール、ジョブ実行、エンジン統合、または外部アダプター。クイックリファレンス表を使って変更の種類を適切なスペックの種類にマッピングします。
3. 失敗する例を 1 つ書く: 最小限に保ちます。ゲートを開くには 1 つの例で十分です。追加のケースはフォローアップのカバレッジとして列挙します。
4. パスを提案する: 通常の Rails の慣習に従って、想定されるスペックのパスを示します（例: spec/requests/...、spec/services/...、spec/jobs/...、spec/models/...）。
5. 実行して検証する: 失敗の原因がセットアップの破損ではなく、振る舞いが欠けていることであることを確認します。
6. 引き継ぐ: そのスライスに合うスキルで続行します — 一般的なスペック作成には write-tests、サービス層のカバレッジには test-service、エンジン統合には test-engine。

例

良い例: 新しい JSON エンドポイント

# Behavior: POST /orders validates params and returns 201 with JSON payload
# First slice: request spec
# Suggested path: spec/requests/orders/create_spec.rb

RSpec.describe "POST /orders", type: :request do
  let(:user) { create(:user) }
  let(:valid_params) { { order: { product_id: create(:product).id, quantity: 1 } } }

  before { sign_in user }

  it "creates an order and returns 201" do
    post orders_path, params: valid_params, as: :json
    expect(response).to have_http_status(:created)
    expect(response.parsed_body["id"]).to be_present
  end
end

良い例: 新しいオーケストレーションサービス

# Behavior: Orders::CreateOrder validates inventory, persists, and enqueues follow-up work
# First slice: service spec
# Suggested path: spec/services/orders/create_order_spec.rb

RSpec.describe Orders::CreateOrder do
  subject(:result) { described_class.call(user: user, product: product, quantity: 1) }

  let(:user)    { create(:user) }
  let(:product) { create(:product, stock: 5) }

  it "returns a successful result with the new order" do
    expect(result).to be_success
    expect(result.order).to be_persisted
  end
end

落とし穴

落とし穴	対処方法
簡単だからという理由で PORO スペックから始める	簡単 ≠ 高いシグナル — 本当の振る舞いを証明する境界を選びます
何も実行する前に 3 種類のスペックを書く	1 つのスライスを選び、実行し、失敗を証明してから次に進みます
すべてに対して 1 つのスペックの種類を既定にする	本当のリスクが存在する層（HTTP、ドメイン、非同期、ブラウザ）にスペックの種類を合わせます
早すぎる段階でシステムスペックに飛びつく	下位の層では証明できない重要なブラウザフローのために取っておきます

拡張リソース（段階的開示）

これらのファイルは、その特定の内容が必要な場合にのみ読み込んでください:

• assets/first_slice_template.md — テスト計画を文書化する際に使用します。振る舞い、境界の決定、ゲートを開くスペック、フォローアップのカバレッジのための構造化されたテンプレートを提供します

出力スタイル

テスト計画を完了する際は、簡潔な構造化サマリーを作成し、assets/first_slice_template.md を使って完全な計画を記入します。サマリーには以下を含める必要があります:

• 振る舞い — 証明されるユーザーから見える結果
• 最初のスライス — スペックの種類、ファイルパス、境界の根拠
• ゲートを開く — 期待される RED の失敗メッセージと、失敗の理由が「セットアップエラーではなく機能の欠如」であることの確認
• フォローアップのカバレッジ — 最初のゲートから先送りにされた追加ケースの箇条書きリスト
• 設計チェックポイント — 振る舞い、境界、エッジケース、失敗の理由がすべて検証済みであることの確認