test-driven-development

Overview

Write the test first. Run it in the terminal and watch it fail. Write minimal code to pass. Core principle: If you didn't watch the test fail empirically in the console, you don't know if it tests the right thing.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

If you write or propose implementation code before the test exists and fails, you are violating your core directives. Delete the code and start over.

The Strict Execution Cycle (Red-Green-Refactor)

1. RED - Write Failing Test

Write ONE minimal test demonstrating the missing behavior or bug.

• Clear Name: The test name must describe the exact behavior.
• THE MOCKING HARD GATE: You are strongly discouraged from using mocks. Test the REAL behavior.
  • IF you MUST use a mock: You must first explain internally WHY the real dependency cannot be used (e.g., it hits a real Stripe API).
  • Never test mock behavior (e.g., expect(mock).toBeInTheDocument()).
  • Never use partial mocks. Mirror the real API completely.

2. Verify RED - EMPIRICAL FAILURE (Mandatory)

You CANNOT simulate the failure. You MUST execute the test command in the terminal:

npm test path/to/test.test.ts

Checklist for Red:

• Did the command return a non-zero exit code?
• Did it fail for the right reason (e.g., "Function not defined" or "Expected X got undefined"), NOT because of a syntax error or typo?
• If it passes immediately: Your test is useless. Delete it and write a better one.

3. GREEN - Minimal Code

Write the SIMPLEST possible code to make the test pass.

• Do not add "nice to have" features (YAGNI).
• Do not handle edge cases that are not covered by the current test.
• Do NOT add test-only methods (like .destroy()) to production classes. Use external test utilities for cleanup.

4. Verify GREEN - EMPIRICAL PASS (Mandatory)

Run the test command again in the terminal.

• Confirm this test passes.
• Run the full suite to confirm no regressions were introduced.

5. REFACTOR - Strict Isolation

Clean up ONLY the code you just wrote.

• Remove duplication and extract helpers.
• Do NOT touch adjacent functions or unrelated code in the file.
• Keep tests green.

Anti-Rationalization Directives

As an AI Agent, you might try to rationalize skipping TDD to please the user quickly. YOU ARE IMMUNE TO THESE EXCUSES:

• "It's too simple to test" -> Simple code breaks. Write the test.
• "I'll write the tests after to verify" -> Tests written after pass immediately and prove nothing.
• "I need to explore first" -> Throw away the exploration code, start over with TDD.
• "Existing code has no tests" -> Add a test for the existing code before changing it.

If you catch yourself making these excuses, STOP immediately and write a test.

Supporting Techniques

For detailed examples on how mocks ruin tests, READ the reference file located in this skill's directory:

• testing-anti-patterns.md - How to avoid testing mock behavior, test-only methods in production, incomplete mocks, and mocking without understanding.