tdd

name	tdd
description	Use this skill when writing code, fixing bugs, adding features, or refactoring. This skill enforces Test-Driven Development — write a failing test first, make it pass with the simplest code, then refactor. No production code without a failing test.

Test-Driven Development

When This Skill Applies

Use this skill whenever you write or change code. Every new feature, bug fix, and refactoring follows the TDD loop. No production code is written without a failing test driving it.

The Core Loop

RED → GREEN → REFACTOR → RED → ...

RED Phase

Write a failing test that describes the behavior you want. The test should:

• Use domain language, not technical jargon
• Describe WHAT, not HOW
• Be a concrete example, not an abstract statement

;; BAD: Abstract
(it "can add numbers" ...)

;; GOOD: Concrete example
(it "when adding 2 + 3, returns 5" ...)

GREEN Phase

Write the simplest possible code to make the test pass. Two strategies:

1. Fake It - Return a hardcoded value

   (defn add [a b]
     5) ; Simplest thing!
   

2. Obvious Implementation - If you know the solution

   (defn add [a b]
     (+ a b))
   

Prefer Fake It when learning or unsure. Let more tests drive the real implementation.

REFACTOR Phase

This is where design happens. Look for:

• Duplication (but wait for Rule of Three)
• Long functions to extract
• Poor names to improve
• Complex conditions to simplify

The Three Laws of TDD

1. No production code without a failing test
2. No more test code than sufficient to fail (compilation failures count)
3. No more production code than sufficient to pass the one failing test

The Rule of Three

Only extract duplication when you see it THREE times.

Why? Wrong abstractions are worse than duplication. Wait for the pattern to emerge.

;; Duplication #1 - Leave it
;; Duplication #2 - Note it, leave it
;; Duplication #3 - NOW extract it

Triangulation

Each new test "sculpts" the solution toward a general, robust implementation.

Think of degrees of freedom - like a car that needs forward/back, left/right, and rotation. Each test carves out one degree of freedom until the implementation handles all cases.

Transformation Priority Premise

When going from RED to GREEN, prefer simpler transformations:

Priority	Transformation
1	{} → nil
2	nil → constant
3	constant → variable
4	unconditional → conditional
5	scalar → collection
6	statement → recursion
7	value → mutated value

Higher priority = simpler. Avoid jumping to complex transformations too early.

Arrange-Act-Assert with Speclj

Structure every test:

(describe "Order"
  (it "calculates total with discount"
    ;; ARRANGE - Set up the world
    (let [order {:items [{:price 100}]}
          discount {:type :percent :value 10}]
      ;; ACT - Execute the behavior
      (let [total (calculate-total order discount)]
        ;; ASSERT - Verify the outcome
        (should= 90 total)))))

Writing Tests Backwards

Sometimes it helps to write AAA in reverse:

1. Write the ASSERT first - what do you want to verify?
2. Write the ACT - what action produces that result?
3. Write the ARRANGE - what setup is needed?

;; Start with what you want to verify
(should= 90 total)

;; What produces that?
(let [total (calculate-total order discount)]
  (should= 90 total))

;; What setup is needed?
(let [order {:items [{:price 100}]}
      discount {:type :percent :value 10}]
  (let [total (calculate-total order discount)]
    (should= 90 total)))

Keep the Loop Tight

During RED/GREEN, prefer running the smallest spec that covers the behavior you are changing:

lein spec spec/my_app/order_spec.clj:42
clj -M:spec spec/my_app/order_spec.clj:42
bb spec -F spec/my_app/order_spec.clj:42

Use file:line to target the nearest enclosing Speclj form. Prefer --focus or -F with wrapper commands when they would otherwise inject default spec directories and run the whole suite.

Test Naming Principles

• Use behavior-driven names with domain language
• Provide concrete examples, not abstract statements
• One example per test for easy debugging
• Avoid leaking implementation details

;; BAD: Technical, implementation-focused
(it "should set the data property to 1" ...)

;; GOOD: Behavior-focused, domain language
(it "recognizes 'mom' as a palindrome" ...)
(it "returns 5 when adding 2 and 3" ...)
(it "applies 20% discount for premium users" ...)

TDD Example: Building a Calculator

;; RED: First failing test
(describe "Calculator"
  (it "returns 5 when adding 2 and 3"
    (should= 5 (add 2 3))))

;; GREEN: Simplest passing implementation
(defn add [a b]
  5) ; Fake it!

;; RED: Another test to triangulate
(it "returns 7 when adding 3 and 4"
  (should= 7 (add 3 4)))

;; GREEN: Now we need the real implementation
(defn add [a b]
  (+ a b))

;; REFACTOR: Nothing to refactor yet...

;; RED: New feature
(it "returns 0 when adding 0 and 0"
  (should= 0 (add 0 0)))

;; GREEN: Already passes! Good test coverage indicator.

TDD Example: Building a Stack

;; RED: Empty stack
(describe "Stack"
  (it "is empty when created"
    (should (empty-stack? (make-stack)))))

;; GREEN
(defn make-stack [] [])
(defn empty-stack? [stack] (empty? stack))

;; RED: Push makes it non-empty
(it "is not empty after push"
  (should-not (empty-stack? (push (make-stack) 1))))

;; GREEN
(defn push [stack item]
  (conj stack item))

;; RED: Pop returns pushed item
(it "returns pushed item when popped"
  (let [stack (-> (make-stack) (push 1))]
    (should= 1 (peek-stack stack))))

;; GREEN
(defn peek-stack [stack]
  (peek stack))

;; RED: LIFO behavior
(it "returns items in LIFO order"
  (let [stack (-> (make-stack) (push 1) (push 2))]
    (should= 2 (peek-stack stack))))

;; Already passes! The design emerges.

Classic vs Mockist TDD

Classic (Detroit/Chicago) TDD:

• Test with real dependencies
• Higher confidence, slower tests
• Best for: Pure functions, domain logic

Mockist (London) TDD:

• Mock external dependencies
• Faster tests, more isolated
• Best for: Functions with infrastructure dependencies

Start with Classic TDD to learn the technique. Add mocks when testing code with databases, APIs, etc.

;; Classic: Use real collaborators
(describe "OrderService"
  (it "calculates total correctly"
    (let [pricing (->StandardPricing)
          order {:items [{:price 100}]}]
      (should= 100 (calculate-total pricing order)))))

;; Mockist: Mock infrastructure
(describe "OrderService"
  (it "saves order to database"
    (let [saved (atom nil)]
      (with-redefs [db/save! #(reset! saved %)]
        (save-order! {:id "123"})
        (should= "123" (:id @saved))))))

Clean Test Output

Test output must be clean. The only output from a test run should be the test framework's own reporting (dots, summaries, failures). No println noise.

Production code that prints (CLI progress, logging, etc.) must be silenced during tests. When calling functions that print to stdout in test code, wrap them:

;; BAD: println from production code clutters test output
(it "parses features"
  (parse-features! dir output-dir)  ; prints "Parsing foo.feature -> ..."
  (should ...))

;; GOOD: suppress stdout in tests
(it "parses features"
  (with-out-str (parse-features! dir output-dir))
  (should ...))

If you need the return value from a function that prints:

(it "returns exit code 0"
  (let [result (atom nil)]
    (with-out-str (reset! result (run-features dir)))
    (should= 0 @result)))

Before closing a bead, run the full test suite and verify the output is clean — only dots and the summary line. If you see any text that isn't from the test framework, fix it.

Test DON'Ts

Tests must be fast, deterministic, and isolated. Real I/O makes tests slow, flaky, and dependent on external state.

• No sleep calls — if you're waiting for something, the design needs a seam to inject timing control
• No filesystem access — unless the code under test is explicitly filesystem management; prefer mocking or an in-memory implementation
• No HTTP requests — mock the HTTP layer; tests should not depend on network availability or remote state
• No other I/O — stdin/stdout beyond test output, sockets, message queues — prefer mocked or in-memory equivalents
• No external database interaction — use an in-memory implementation or repository stub; never hit a real database in a unit test

Polling Instead of Sleeping

Never use Thread/sleep to wait for async state to change. Fixed sleeps are slow on fast machines and flaky on slow ones.

Instead, poll the condition directly:

;; BAD
(trigger-something!)
(Thread/sleep 50)
(should= expected (get-state))

;; GOOD — exits as soon as the condition is true, up to 1s
(trigger-something!)
(await-condition #(= expected (get-state)))
(should= expected (get-state))

Implement an await-condition helper in your project's test-helper namespace that polls every 1ms for up to 1 second.

Thread/sleep is only acceptable when the spec is explicitly testing that a function blocks for a minimum duration (e.g. verifying a poll timeout).

When You Can't Poll a Positive Condition

If you're asserting that something did not change, polling won't help — the negative is always true until something later proves it false. Instrument the triggering function instead. For example, wrap a polling function with a counter atom and wait for the second call — that signals the first processing cycle completed — then assert the unchanged state.

Common Mistakes

1. Writing code before tests - Violates the fundamental principle
2. Writing too much test - Just enough to fail
3. Writing too much code - Just enough to pass
4. Skipping refactor - This is where design lives
5. Testing implementation - Test behavior, not how it's done
6. Abstract test names - Use concrete examples
7. Extracting too early - Wait for Rule of Three
8. Noisy test output - Production println leaking into test runs

TDD Rhythm

1. Think about what you want to achieve
2. Write a test expressing that
3. See it fail (confirms test works)
4. Write minimal code to pass
5. See it pass
6. Look for refactoring opportunities
7. Refactor if needed (tests still pass)
8. Repeat

When TDD Feels Hard

• Don't know what to test? → Start with the simplest case
• Test is hard to write? → Design might need simplification
• Many mocks needed? → Too many dependencies, consider redesign
• Tests are brittle? → Testing implementation, not behavior
• Tests are slow? → Too many integration tests, add more unit tests