Test-Driven Development

Work in small red-green-refactor cycles. The clean-code skill governs the refactor step and the quality of the test code itself.

Before coding

1. Restate the behavior as concrete examples: inputs, expected outputs, and edge cases.
2. Write a test list of behaviors to cover, simplest first. Keep it visible and update it as you learn.
3. For a bug, write a test that reproduces the bug before you touch any code.

The cycle

1. Red: write one small failing test for the next behavior on the list.
   • Run it and confirm it fails for the expected reason, not because of a compile error or a typo.
2. Green: write the minimum code that passes.
   • Faking the result or hard-coding a value is fine when it keeps the step small.
   • Run the whole relevant suite.
3. Refactor: with all tests green, remove duplication and improve names and structure. Apply clean-code.
   • Refactor the test code too.
   • Don't add behavior during this step.
4. Repeat. Each cycle should take minutes. If a step gets large, back out and pick a smaller test.

Choosing the next test

• Start with the degenerate case: empty input, zero, null, or the simplest happy path.
• Then add one dimension of variation at a time.
• Triangulate: add a second example to force out the fake implementation.
• Leave error paths and boundaries for after the core behavior works, but before you call the feature done.

Good tests

• Test observable behavior through the public API, never private methods or internals.
• Each test checks one behavior and is named for it (shouldRejectOrder_whenStockIsInsufficient).
• Structure each test as Arrange-Act-Assert. Keep tests independent and deterministic.
• Control time, randomness, and IDs by injecting them.
• A test that is hard to write is design feedback. Fix the design rather than forcing the test.

Test doubles

• Prefer real objects and in-memory fakes.
• Mock only at architectural boundaries: external services, messaging, and the clock. Don't mock what you don't own.
  • Wrap third-party code in an adapter and test the adapter with integration tests.
• Verify interactions only when the interaction is the behavior, such as sending an event or an email.

Testing levels

• Unit tests cover domain logic. These are the bulk of the suite.
• Integration tests cover adapters: repositories, HTTP clients, and messaging.
• Contract tests cover service-to-service APIs (consumer-driven).
• End-to-end tests cover a few critical user journeys only.
• Outside-in (double loop) for features:
  1. Start with a failing acceptance test.
  2. Drive the inner pieces with unit-level TDD.
  3. Finish when the acceptance test passes.

Java / Spring Boot notes

• Use JUnit 5 and AssertJ. Use Mockito sparingly, and only at boundaries.
• Unit-test domain and service classes without Spring. Construct them directly.
• Use slice tests for adapters: @WebMvcTest for controllers and @DataJpaTest for repositories.
• Use Testcontainers for real databases and brokers in integration tests. Don't use H2 as a stand-in for Postgres.
• Reserve @SpringBootTest for a few wiring and acceptance tests.
• Use Spring Cloud Contract or Pact for contract tests.

When reporting work

Show the test list and mark which items are done. For each cycle, show the test, why it failed, and the change that made it pass.