Write Tests

Use this skill when the task is to write, review, or clean up RSpec tests.

Quick Reference

TDD Workflow (RED → GREEN → REFACTOR)

HARD GATE: DO NOT write implementation code before a failing test exists.

When driving new behaviour with RSpec, follow this sequence:

1. Write the failing spec — pick the smallest spec type that exercises the intended behaviour (model > service > request > system), as shown in the Spec types row above.
2. Run it and confirm the failure message — show the concrete RED failure class/message. Do not leave this as a placeholder template; do not use illustrative e.g. failure examples in the final artifact.
3. Implement the minimum code to make the spec pass.
4. Refactor — clean up duplication and naming while keeping the suite green.
5. Verify — run the full relevant spec file, then the suite, before committing.

For output format and RED/GREEN proof requirements, see assets/tdd_proof_checklist.md.

Service Spec (anchor pattern)

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

One Behavior Per Example

Split and in it/specify descriptions every time — no exceptions.

# 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

Flaky Tests & Deterministic Assertions

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

• assets/complete_example.md — A complete, step-by-step example of a high-scoring answer.md showing plan, spec, realistic Observed RED/GREEN outputs, and verification tables.
• assets/examples.md — For code examples of service specs, shared examples, and factory design.
• assets/spec_templates.md — Standard templates for different types of specs.
• assets/tdd_proof_checklist.md — Use when the task involves new behavior; defines RED/GREEN proof format, output formatting rules, and GREEN progress bar requirements.
• assets/output_checklist.md — Complete 18-point checklist for RSpec output structure, conventions, and self-auditing; also defines all output style rules (spec structure, file path mirroring, frozen_string_literal, subject(:result), and TDD proof format).