write-tests

テストを書く

このスキルは、RSpec テストの作成、レビュー、またはクリーンアップがタスクである場合に使用します。

クイックリファレンス

観点	ルール
スペックの種類	Model: ドメインロジック / 純粋なドメイン → ここから始める。Request: HTTP エンドポイント。Job: バックグラウンド処理。Service/PORO: クリーンな Ruby。System: レイヤーをまたぐ E2E ジャーニー（控えめに）
アサーション	実装ではなく振る舞いをテストする
ファクトリ	属性は最小限に。オプションには trait を使用。create よりも build/build_stubbed を優先
モック	外部境界はクラスレベルでスタブする（例: allow(Client).to receive）。Active Record のモックは禁止
Service スペック	必須: describe '.call' と subject(:result)（assets/output_checklist.md を参照）
let と let!	デフォルトは let。アクションの前にオブジェクトが存在しなければならない場合のみ let! を使用
example 名	現在形。should は使わない。and も使わない（assets/output_checklist.md を参照）

HARD-GATE

DO NOT write implementation code before a failing test exists.
Run bundle exec rspec and keep the real failure class and message.

コアプロセス

RSpec で新しい振る舞いを駆動する場合は、次の順序に従います。

1. 失敗するスペックを書く — 意図する振る舞いを検証する最小のスペック種別を選びます（model > service > request > system）。上記の「スペックの種類」の行に示すとおりです。
2. 実行して失敗メッセージを確認する — 具体的な RED の失敗クラス/メッセージを示します。これをプレースホルダーのテンプレートのままにしないでください。最終成果物に説明的な e.g. の失敗例を使わないでください。
3. スペックをパスさせるための最小限のコードを実装する。
4. リファクタリングする — スイートをグリーンに保ちながら、重複と命名をクリーンアップします。
5. 検証する — コミットする前に、関連するスペックファイル全体を実行し、その後スイートを実行します。

出力形式と RED/GREEN の証明要件については、assets/tdd_proof_checklist.md を参照してください。

Service スペック（アンカーパターン）

RSpec.describe Invoices::MarkOverdue do
  describe '.call' do
    subject(:result) { described_class.call(invoice: invoice) }

    context 'when the invoice is overdue and unpaid' do
      let(:invoice) { create(:invoice, due_date: 2.days.ago, paid_at: nil) }
      it 'marks the invoice overdue' do
        expect { result }.to change { invoice.reload.overdue? }.from(false).to(true)
      end
    end
  end
end

1 つの example につき 1 つの振る舞い

it/specify の説明にある and は毎回分割してください — 例外はありません。

# BAD — two assertions; if the first fails, the second never runs
it 'returns 201 and creates the record' do; end

# GOOD — one observable outcome per example
it 'returns 201' do; end
it 'creates the record' do; end

フレーキーなテストと決定論的なアサーション

原因	修正
時間依存のロジック	freeze_time / travel_to を使用。ショートカットとして過去の日付を設定しない
状態の漏洩	各 example が自身の状態をセットアップする。before(:all) を避ける
非同期ジョブ	queue_adapter = :test + have_enqueued_job を使用。副作用を命令的にアサートしない
外部 HTTP	WebMock / VCR を使用。CI で実際のネットワークを許可しない
DB 状態の漏洩	トランザクショナルフィクスチャまたは DatabaseCleaner を使用。コンテキスト間で let! を共有しない
競合状態	明示的な Capybara の待機を使用。sleep を避ける
不正確なアサーション	最終状態よりも change.from().to() を使用。be_truthy/be_falsey よりも正確な値を使用。ルール 16 を参照

拡張リソース（プログレッシブディスクロージャー）

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

• assets/complete_example.md — 高スコアの answer.md の完全なステップバイステップの例。プラン、スペック、現実的な Observed RED/GREEN 出力、検証テーブルを示します。
• assets/examples.md — Service スペック、shared examples、ファクトリ設計のコード例について。
• assets/spec_templates.md — さまざまな種類のスペックの標準テンプレート。
• assets/tdd_proof_checklist.md — タスクが新しい振る舞いを含む場合に使用します。RED/GREEN の証明形式、出力フォーマットのルール、GREEN プログレスバーの要件を定義します。
• assets/output_checklist.md — RSpec 出力の構造、規約、セルフ監査のための完全な 18 項目のチェックリスト。すべての出力スタイルルール（スペック構造、ファイルパスのミラーリング、frozen_string_literal、subject(:result)、TDD 証明形式）も定義します。

出力スタイル

assets/tdd_proof_checklist.md と assets/output_checklist.md に従ってください。実際の RED/GREEN コマンド出力を示してください。1 つの example につき 1 つの振る舞いとします。

統合

スキル	チェーンするタイミング
plan-tests	最初のスライスの選択が自明でない場合
test-service	スライスがサービスの .call である場合
tdd	PR までの完全な機能ループ