igmarin/rails-tdd-slices

Rails TDD Slices

Use this skill when the hardest part of the task is deciding where TDD should start.

Core principle: Start at the highest-value boundary that proves the behavior with the least unnecessary setup.

Quick Reference

| Change type | First spec | Path | Why | |-------------|-----------|------|-----| | API contract, params, status code, JSON shape | Request spec | spec/requests/ | Proves the real HTTP contract | | Domain rule on a cohesive record or value object | Model spec | spec/models/ | Fast feedback on domain behavior | | Multi-step orchestration across collaborators | Service spec | spec/services/ | Focuses on the workflow boundary | | Enqueue/run/retry/discard behavior | Job spec | spec/jobs/ | Captures async semantics directly | | Critical Turbo/Stimulus or browser-visible flow | System spec | spec/system/ | Use only when browser interaction is the real risk | | Engine routing, generators, host integration | Engine spec | spec/requests/ or engine path | Normal app specs miss engine wiring — see rails-engine-testing | | Bug fix | Reproduction spec | Where the bug is observed | Proves the fix and prevents regression | | Unsure between layers | Higher boundary first | — | Easier to prove real behavior before drilling down |

HARD-GATE

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.

Process

1. Name the behavior: State the user-visible outcome or invariant to prove.
2. Locate the boundary: Decide where the behavior is observed first: HTTP request, service entry point, model rule, job execution, engine integration, or external adapter.
3. Pick the smallest strong slice: Choose the spec type that proves the behavior without dragging in unrelated layers.
4. Suggest the path: Name the likely spec path using normal Rails conventions (for example spec/requests/..., spec/services/..., spec/jobs/..., spec/models/...).
5. Write one failing example: Keep it minimal; one example is enough to open the gate.
6. Run and validate: Confirm the failure is because the behavior is missing, not because the setup is broken.
7. Hand off: Continue with rspec-best-practices, rspec-service-testing, rails-engine-testing, or the implementation skill that fits the slice.

Examples

Good: New JSON Endpoint

# 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

Good: New Orchestration Service

# 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

Test Feedback Checkpoint

After writing and running the first failing spec, pause before implementation and present the test for review:

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.

Why this matters: Implementing against a poorly designed test wastes the TDD cycle. A 2-minute review of the test now prevents a full rewrite later.

Hand off: After test design is confirmed → rspec-best-practices for the full TDD gate cycle.

Pitfalls

| Pitfall | What to do | |---------|------------| | Starting with a PORO spec because it is easy | Easy ≠ high-signal — choose the boundary that proves the real behavior | | Writing three spec types before running any | Pick one slice, run it, prove the failure, then proceed | | Defaulting to request specs for everything | Some domain rules are better proven at the model or service layer | | Defaulting to model specs for controller behavior | Controllers and APIs need request-level proof | | Using controller specs as the default HTTP entry point | Prefer request specs unless the repo has an existing reason | | Jumping to system specs too early | Reserve for critical browser flows that lower layers cannot prove | | "We'll add the request spec later" | The spec is the gate — implement only after the first slice is failing for the right reason | | First spec requires excessive factory setup | Excessive setup = wrong boundary. Simplify or move the slice. |

Integration

| Skill | When to chain | |-------|---------------| | rspec-best-practices | After choosing the first slice, to enforce the TDD loop correctly | | rspec-service-testing | When the first slice is a service object spec | | rails-engine-testing | When the first slice belongs to an engine | | rails-bug-triage | When the starting point is an existing bug report | | refactor-safely | When the task is mostly structural and needs characterization tests first |