Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

test-driven-development

Strict red-green-refactor TDD workflow for implementing features, fixing bugs, or changing behavior in Rails applications. Enforces the discipline of writing a failing test before any production code. Use whenever you want to implement with TDD — whether a new feature, a bugfix, a refactor, or any behavior change.

thoughtbot · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add thoughtbot/rails-consultant --skill test-driven-development

About this skill


name: test-driven-development description: Strict red-green-refactor TDD workflow for implementing features, fixing bugs, or changing behavior in Rails applications. Enforces the discipline of writing a failing test before any production code. Use whenever you want to implement with TDD — whether a new feature, a bugfix, a refactor, or any behavior change. argument-hint: "[feature, bug, or behavior to implement]" disable-model-invocation: true

Test-Driven Development (TDD)

Overview

Write the test first. Watch it fail. Write minimal code to pass.

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

Violating the letter of the rules is violating the spirit of the rules.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete

Implement fresh from tests. Period.

Outside-In Development

Start every feature with a high-level test that describes behavior from the user's perspective. Run it, read the failure, and let that failure dictate your next move. As failures push you down the stack, write a new failing test at each layer you drop into — never write code for a layer without a failing test at that layer demanding it.

Read examples/outside-in-testing.md for a walkthrough of the philosophy and examples/testing-pyramid.md for how test types combine into an optimal suite.

One Change, One Run

After every change — writing a test, adding a route, creating a file, implementing a method — run the affected test immediately:

bundle exec rspec spec/features/guest_searches_for_items_spec.rb

The failure message is your instruction for what to do next. Don't batch changes and don't guess ahead: one change, one run, read the failure, decide. If you made two changes before running, you no longer know which one the test is reacting to.

Drop Down by Writing the Next Failing Test

A failure rarely means "write this exact line." It usually means "the layer below isn't there yet." When the active test's failure points to a layer that has behavior of its own — a controller action, an endpoint, a model method — drop down and write a failing test at that layer before building it.

Think of it as a stack of failing tests:

  • The active test is the one whose failure you're reading right now.
  • Its failure points to a missing lower layer → write a new failing test at that layer. It becomes the active test.
  • Drive that test with Red-Green-Refactor. If it forces you down another level, push another failing test.
  • When the active test goes green, pop it: rerun the test one layer up. Its next failure drives the next move.

Drop to whichever layer the failure names — not always one rung at a time. Continue until the top-level feature spec is green with nothing left on the stack.

The ladder of test types, top to bottom:

When the failure points to…Write this failing test
End-to-end behavior from the user's perspectiveFeature / system spec
A controller action, response, status, or redirectRequest (or controller) spec
Logic in a model, service object, query, calculation, or validationModel / unit spec

Feature and request specs are integration tests: real database records, no mocks — except external services (use webmock or fakes), so the suite runs offline. Unit specs isolate the object under test: mock collaborators aggressively, because the goal is to prove this object, not its collaborators. Difficulty testing two objects in isolation signals too-tight coupling.

Build Directly Only for Inert Glue

A few things have no behavior of their own, so they get no test of their own — but you still add them only because a failing test one layer up demanded them:

  • The route line (a request spec failing with No route matches drives it)
  • An empty class or module to clear a NameError
  • Trivial markup a feature spec's content expectation already covers

Everything with behavior gets its own failing test first. When in doubt, drop down and write the test.

The testing pyramid: many unit tests at the bottom, fewer request specs in the middle, a few feature specs at the top. Unit tests are fast and precise; feature tests prove the system works end-to-end. Each plays to its strengths.

Red-Green-Refactor

The cycle every test follows — feature spec, request spec, and model spec alike. Each failing test on the stack runs this loop; a test going green is what lets you pop back up to the layer above.

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

RED — Write Failing Test

Write one minimal test showing what should happen.

RSpec.describe Item, ".search" do
  it "filters items by the search term" do
    desired_item = create(:item, name: "Widget")
    _other_item = create(:item, name: "Gadget")

    expect(Item.search("Widget
Read the complete source ↗