tdd

Write one meaningful failing test against the public contract, confirm it fails for the expected missing behavior, then make the smallest implementation that passes. Repeat for each subsequent behavior instead of writing the whole test suite upfront.

Mock only system boundaries such as external APIs, time, randomness, and sometimes databases or the file system. Never mock your own classes or internal collaborators, since that couples tests to implementation details.

Tests break during refactoring when they assert on internal method names, call counts, or private methods instead of observable behavior. Test through the public interface so internal restructuring leaves the suite green.

Refactor only after a test passes and the working change reveals a concrete friction, such as repeated logic or unnecessary indirection. Keep the change minimal, rerun the tests, and avoid expanding into a broader architecture audit.

Use dependency injection to pass clients in rather than constructing them internally, and prefer SDK-style interfaces with one function per operation. This gives each mock a single return shape without conditional logic in test setup.