test-driven-development

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.