rails-tdd-slices

Rails TDD スライス

タスクで最も難しいのが、TDD をどこから始めるかの判断である場合に、このスキルを使用します。

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

クイックリファレンス

変更の種類	最初のスペック	パス	理由
API コントラクト、パラメーター、ステータスコード、JSON の構造	リクエストスペック	spec/requests/	実際の HTTP コントラクトを証明できます
一貫性のあるレコードまたは値オブジェクトに関するドメインルール	モデルスペック	spec/models/	ドメインの振る舞いをすばやくフィードバックできます
複数のコラボレーターにまたがる複数ステップのオーケストレーション	サービススペック	spec/services/	ワークフローの境界に焦点を当てます
エンキュー／実行／再試行／破棄の振る舞い	ジョブスペック	spec/jobs/	非同期のセマンティクスを直接捉えます
重要な Turbo／Stimulus またはブラウザーで見えるフロー	システムスペック	spec/system/	ブラウザー操作が実際のリスクである場合にのみ使用します
エンジンのルーティング、ジェネレーター、ホストとの統合	エンジンスペック	spec/requests/ またはエンジンのパス	通常のアプリスペックではエンジンの配線を見落とします。rails-engine-testing を参照してください
バグ修正	再現スペック	バグが確認される場所	修正を証明し、再発を防ぎます
レイヤーの判断に迷う場合	まず上位の境界	—	詳細に踏み込む前に、実際の振る舞いを証明するほうが簡単です

ハードゲート

DO NOT choose the first spec based on convenience alone.
DO NOT start with a lower-level unit if the real risk is request, job, engine, or persistence wiring.
ALWAYS run the chosen spec and verify it fails for the right reason before implementation.

プロセス

1. 振る舞いを明確にする： 証明すべき、ユーザーから見える結果または不変条件を述べます。
2. 境界を特定する： 振る舞いが最初に観測される場所を判断します。HTTP リクエスト、サービスのエントリーポイント、モデルルール、ジョブの実行、エンジン統合、外部アダプターのいずれかです。
3. 最小限で強力なスライスを選ぶ： 無関係なレイヤーを巻き込まずに振る舞いを証明できるスペックの種類を選びます。
4. パスを提案する： 通常の Rails の規約に従って、想定されるスペックのパスを示します（例：spec/requests/...、spec/services/...、spec/jobs/...、spec/models/...）。
5. 失敗する例を 1 つ書く： 最小限に保ちます。ゲートを開くには 1 つの例で十分です。
6. 実行して検証する： セットアップの不具合ではなく、振る舞いが欠けていることが原因で失敗することを確認します。
7. 引き継ぐ： その後は、スライスに合った rspec-best-practices、rspec-service-testing、rails-engine-testing、または実装スキルを続けて使用します。

例

良い例：新しい 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

テストフィードバックのチェックポイント

最初の失敗するスペックを書いて実行した後、実装に進む前に一度立ち止まり、レビュー用にテストを提示します。

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: Only proceed to implementation once test design is approved.

重要な理由： 設計の悪いテストをもとに実装すると、TDD のサイクルを無駄にします。今ここで 2 分かけてテストをレビューすれば、後で全面的に書き直すのを防げます。

引き継ぎ： テスト設計が確認されたら、TDD ゲートサイクル全体には rspec-best-practices を使用します。

落とし穴

落とし穴	対応方法
簡単だからと PORO のスペックから始める	簡単であることは、信号が強いことを意味しません。実際の振る舞いを証明できる境界を選びます
実行前に 3 種類のスペックを書く	スライスを 1 つ選び、実行して失敗を証明してから進めます
何でもリクエストスペックにする	ドメインルールによっては、モデルまたはサービスレイヤーで証明するほうが適しています
コントローラーの振る舞いにモデルスペックを使う	コントローラーと API には、リクエストレベルでの証明が必要です
HTTP のエントリーポイントとしてコントローラースペックを既定で使う	リポジトリに既存の理由がない限り、リクエストスペックを優先します
システムスペックに早々に進む	下位レイヤーでは証明できない重要なブラウザーフローに限って使用します
「リクエストスペックは後で追加します」	スペックがゲートです。最初のスライスが正しい理由で失敗してから実装します
最初のスペックに過剰なファクトリーのセットアップが必要になる	過剰なセットアップは境界が間違っている兆候です。簡素化するか、スライスを移動します

統合

スキル	連携するタイミング
rspec-best-practices	最初のスライスを選んだ後、TDD のループを正しく実施するため
rspec-service-testing	最初のスライスがサービスオブジェクトのスペックの場合
rails-engine-testing	最初のスライスがエンジンに属する場合
rails-bug-triage	既存のバグレポートが出発点の場合
refactor-safely	タスクの大部分が構造的なもので、まず特性テストが必要な場合