write-tests

编写测试

当任务是编写、审查或清理 RSpec 测试时，使用本技能。

快速参考

方面	规则
Spec 类型	Model：领域逻辑 / 纯领域 → 从这里开始；Request：HTTP 端点；Job：后台处理；Service/PORO：纯 Ruby；System：E2E 跨层旅程（谨慎使用）
断言	测试行为，而非实现
工厂	最小属性；用 trait 表示选项；优先使用 build/build_stubbed 而非 create
Mock	在类级别 stub 外部边界（例如 allow(Client).to receive）；不要 mock Active Record
Service spec	必需： describe '.call' 和 subject(:result)（见 assets/output_checklist.md）
let vs let!	默认使用 let；仅当对象必须在动作之前存在时才使用 let!
示例名称	使用现在时；不要用 should；不要用 and（见 assets/output_checklist.md）

硬性门槛

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

核心流程

当用 RSpec 驱动新行为时，遵循以下顺序：

1. 编写失败的 spec —— 选择能检验目标行为的最小 spec 类型（model > service > request > system），如上方 Spec 类型行所示。
2. 运行它并确认失败消息 —— 展示具体的 RED 失败类/消息。不要将其留作占位符模板；不要在最终产物中使用示意性的 e.g. 失败示例。
3. 实现最小代码使 spec 通过。
4. 重构 —— 在保持测试套件通过的同时清理重复和命名。
5. 验证 —— 提交前先运行相关的完整 spec 文件，再运行整个套件。

关于输出格式和 RED/GREEN 证明要求，请参阅 assets/tdd_proof_checklist.md。

Service Spec（锚定模式）

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

每个示例一种行为

每次都要拆分 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；永远不要为走捷径而设置过去的日期
状态泄漏	每个示例设置自己的状态；避免 before(:all)
异步 job	queue_adapter = :test + have_enqueued_job；永远不要以命令式方式断言副作用
外部 HTTP	WebMock / VCR；永远不要在 CI 中允许真实网络
数据库状态残留	事务性 fixtures 或 DatabaseCleaner；永远不要跨 context 共享 let!
竞态条件	显式使用 Capybara 等待；避免 sleep
不精确的断言	用 change.from().to() 而非最终状态；用精确值而非 be_truthy/be_falsey；见规则 16

扩展资源（渐进式披露）

仅当需要其特定内容时才加载这些文件：

• assets/complete_example.md —— 一个完整的、分步的 answer.md 高分示例，展示计划、spec、真实的 Observed RED/GREEN 输出以及验证表格。
• assets/examples.md —— 用于 service spec、共享示例和工厂设计的代码示例。
• assets/spec_templates.md —— 不同类型 spec 的标准模板。
• assets/tdd_proof_checklist.md —— 当任务涉及新行为时使用；定义 RED/GREEN 证明格式、输出格式规则和 GREEN 进度条要求。
• assets/output_checklist.md —— 完整的 18 点 RSpec 输出结构、约定和自我审查清单；还定义了所有输出风格规则（spec 结构、文件路径镜像、frozen_string_literal、subject(:result) 和 TDD 证明格式）。

输出风格

遵循 assets/tdd_proof_checklist.md 和 assets/output_checklist.md。展示真实的 RED/GREEN 命令输出。每个示例一种行为。

集成

技能	何时串联
plan-tests	首个切片的选择不明显
test-service	该切片是一个服务 .call
tdd	通过 PR 完成整个功能循环