Write Tests

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

Core principle: Prefer behavioral confidence over implementation coupling. Good specs are readable, deterministic, and cheap to maintain.

Quick Reference

TDD Workflow

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).
2. Run it and confirm the failure message — the error should be about missing code, not a setup problem.
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.

Choosing the best first failing spec for a Rails change

Factory Design

Minimal factories only. Never rely on factory defaults for business logic — set explicitly or use traits. Avoid create when build/build_stubbed suffices.

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

    context 'when the invoice is already paid' do
      let(:invoice) { create(:invoice, due_date: 2.days.ago, paid_at: 1.day.ago) }

      it 'does not change the invoice' do
        expect { result }.not_to change { invoice.reload.updated_at }
      end
    end
  end
end

Shared Examples

Use only when the same behavioural contract applies to multiple subjects without per-example let overrides. Avoid when each context needs different setup — that signals a wrong abstraction.

One Behavior Per Example

The word "and" in an it / specify description signals two behaviors in one example. Split it every time — no exceptions for any spec type (model, request, service, job, mailer, system).

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

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

it 'saves the order' do; end
it 'sends the confirmation email' do; end

Self-check before finalizing any spec: scan every it '...' / it "..." / specify '...' string for and (case-insensitive, word-boundary). Every hit is a required split.

Output Style

When asked to write or review RSpec specs, your output MUST satisfy each rule below. Each is graded independently — one violation drops the whole check.

1. Spec file path mirrors the source: app/foo/bar.rb → spec/foo/bar_spec.rb.
2. # frozen_string_literal: true as the first line of every spec file.
3. RSpec.describe uses the full constant path (RSpec.describe Module::Class do), not a string.
4. describe '#method' / describe '.class_method' for each method under test.
5. context 'when ...' / context 'with ...' for scenario variations — never use context to group methods.
6. let for test data, let! ONLY when the object must exist before the action under test.
7. No let_it_be unless the project already depends on test-prof (check Gemfile.lock first).
8. NO "and" in any example description — see One Behavior Per Example. Perform an explicit scan before returning the spec.
9. subject(:result) { ... } for service / PORO specs invoking .call.
10. travel_to / freeze_time for any time-dependent assertion — never set past Time.now or stub Time.current directly.
11. External boundaries mocked at the class-method level (allow(SomeClient).to receive(:method)); ActiveRecord finders are NEVER mocked.

Flaky Tests & Deterministic Assertions