version: "1.0.0" name: tdd-workflow description: Use this skill when the user explicitly asks for TDD or a tests-first workflow, or when developing a new feature with a test coverage requirement. Provides a structured red-green-refactor workflow with unit, integration, and E2E test guidance. when_to_use: Use when the user explicitly requests TDD/tests-first development, or when building a new feature where test coverage is a stated requirement.

Test-Driven Development Workflow

This skill provides a structured TDD workflow for projects that adopt tests-first development.

When to Activate

• The user explicitly asks for TDD or tests-first development
• New feature work where test coverage is a stated requirement
• Adding API endpoints or components under a coverage policy

For routine bug fixes or refactors, add focused tests for the changed behavior instead of invoking this full workflow (the /tdd command and tdd-guide agent remain available when you want it explicitly).

Core Principles

1. Tests BEFORE Code

Within this workflow, the default is to write tests first, then implement code to make tests pass.

2. Coverage Guidance

• Coverage target follows the project's own standard (e.g., 80% as a common baseline); scale effort with the size of the change
• Cover relevant edge cases
• Test error scenarios
• Verify boundary conditions

3. Test Types

Unit Tests - Individual functions, utilities, component logic, pure functions, helpers.

Integration Tests - API endpoints, database operations, service interactions, external API calls.

E2E Tests (Playwright) - Critical user flows, complete workflows, browser automation, UI interactions. Applies to web UI projects only.

TDD Workflow Steps

Step 1: Write User Journeys

As a [role], I want to [action], so that [benefit]
 
Example:
As a user, I want to search for markets semantically,
so that I can find relevant markets even without exact keywords.

Step 2: Generate Test Cases

For each user journey, create comprehensive test cases covering happy paths, edge cases, fallback behavior, and sorting/filtering logic.

Step 3: Run Tests (They Should Fail)

Use the project's test runner. Examples:

npm test                      # Node.js
pytest                        # Python
bash tests/run-unit-tests.sh  # shell projects
# Tests should fail - we haven't implemented yet

Step 4: Implement Code

Write minimal code to make tests pass.

Step 5: Run Tests Again

Re-run the same test command (e.g., npm test, pytest):

npm test
# Tests should now pass

Step 6: Refactor

Improve code quality while keeping tests green:

• Remove duplication
• Improve naming
• Optimize performance
• Enhance readability

Step 7: Verify Coverage

Use the project's coverage tooling. Examples:

npm run test:coverage   # Node.js
pytest --cov            # Python
# Verify coverage meets the project's target

Best Practices

1. Write Tests First - Always TDD
2. One Assert Per Test - Focus on single behavior
3. Descriptive Test Names - Explain what's tested
4. Arrange-Act-Assert - Clear test structure
5. Mock External Dependencies - Isolate unit tests
6. Test Edge Cases - Null, undefined, empty, large
7. Test Error Paths - Not just happy paths
8. Keep Tests Fast - Unit tests < 50ms each
9. Clean Up After Tests - No side effects
10. Review Coverage Reports - Identify gaps

Success Metrics

• Coverage target met (per project standard, e.g., 80%)
• All tests passing (green)
• No skipped or disabled tests
• Fast test execution (< 30s for unit tests)
• E2E tests cover critical user flows
• Tests catch bugs before production

References

These templates target JavaScript/TypeScript stacks; adapt the structure for other languages.

• references/test-templates.md - Unit, integration, E2E, and mocking code templates (JS/TS)
• references/testing-mistakes.md - Common pitfalls, file organization, coverage config, CI setup (JS/TS)

Remember: Give changed behavior a focused test. Tests are the safety net that enables confident refactoring, rapid development, and production reliability.