juanjosegongi/testing

Testing & Test-Driven Development

Table of Contents

• SKILL.md (this file): Overview, TDD discipline, and when to use.
• TDD.md: TDD cycle, implementation patterns, and workflows.
• TEST-TYPES.md: Test Pyramid (Unit, Integration, E2E).
• TESTABLE-DESIGN.md: Principles of testable design.
• TESTING-ANTI-PATTERNS.md: Mock discipline and common pitfalls.
• REFERENCE.md: Best practices, coverage, and checklists.

When to Use

• Implementing new features — write tests before implementation (TDD)
• Fixing bugs — write a reproduction test first
• Refactoring — run regression tests throughout
• Code reviews — check test coverage and test quality

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.

Red-Green-Refactor

1. RED    — Write one failing test for desired behavior
2. Verify — Watch it fail for the RIGHT reason (not typos/errors)
3. GREEN  — Write minimal code to pass
4. Verify — All tests pass, output clean
5. REFACTOR — Clean up while staying green
6. Repeat

RED — Write Failing Test

One behavior. Clear name. Real code (no mocks unless unavoidable).

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Run the test. Watch it fail. If it passes, you're testing existing behavior — fix the test. If it errors (not fails), fix the error first.

GREEN — Minimal Code

Write the simplest code to pass. Don't add features, don't over-engineer.

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

Run the test. Watch it pass. If it fails, fix the code — not the test. If other tests broke, fix them now.

REFACTOR — Clean Up

Remove duplication, improve names, extract helpers. Keep all tests green. Don't add behavior.

See TDD.md for detailed examples and workflows.

AAA Pattern (Required)

All tests must follow Arrange-Act-Assert:

it('should create user with valid data', () => {
  // Arrange
  const userData = { name: 'John', email: '[email protected]' }

  // Act
  const user = userService.createUser(userData)

  // Assert
  expect(user.name).toBe('John')
})

Test Pyramid

        /\
       /  \      E2E (Few — critical paths only)
      /____\     Integration (Medium — API + DB interactions)
     /______\    Unit (Many — business logic, fast, isolated)

• Unit: 70% | Integration: 20% | E2E: 10%

See TEST-TYPES.md for details.

Coverage Goals

Business Logic:     100%
Utility Functions:  100%
Service Layer:       90%+
Controllers:         80%+
UI Components:       70%+

See REFERENCE.md for coverage commands and checklists.

Testable Design (Summary)

1. Dependency Injection — inject via constructor, don't new internally
2. Pure Functions — same input → same output, no side effects
3. Interface Abstraction — depend on interfaces, not concrete classes

See TESTABLE-DESIGN.md for patterns and anti-patterns.

Mock Discipline

• Never test mock behavior — test what real code does
• Never add test-only methods to production classes — use test utilities
• Mock minimally — understand dependencies before mocking
• Mock completely — partial mocks hide structural assumptions

See TESTING-ANTI-PATTERNS.md for gate functions and examples.

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll test after" | Tests passing immediately prove nothing. | | "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | | "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is debt. | | "Need to explore first" | Fine. Throw away exploration, start with TDD. | | "Test hard = skip test" | Hard to test = hard to use. Listen to the test. | | "TDD will slow me down" | TDD is faster than debugging in production. |

Red Flags — Stop and Start Over

• Code written before test
• Test passes immediately on first run
• Can't explain why test failed
• Rationalizing "just this once"
• "Keep as reference" or "adapt existing code"
• "It's about spirit not ritual"

All of these mean: delete code, start over with TDD.

Verification Checklist

Before marking work complete:

• [ ] Every new function/method has a test
• [ ] Watched each test fail before implementing
• [ ] Each test failed for the expected reason
• [ ] Wrote minimal code to pass each test
• [ ] All tests pass with clean output
• [ ] Tests use real code (mocks only if unavoidable)
• [ ] Edge cases and error paths covered
• [ ] AAA pattern followed
• [ ] Coverage goals met

When Stuck

| Problem | Solution | |---------|----------| | Don't know how to test | Write the assertion first. Design the wished-for API. | | Test too complicated | Design too complicated. Simplify the interface. | | Must mock everything | Code too coupled. Use dependency injection. | | Test setup huge | Extract helpers. Still complex? Simplify design. | | Bug found | Write failing test reproducing it. Follow TDD cycle. |