Testing Strategy & Factories
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The TDD Guard project employs a robust testing strategy designed to ensure the reliability of its TDD enforcement logic across multiple programming languages. The strategy relies on high-level integration tests, unit tests for core modules, and specialized reporter tests to verify the capturing of test results from various runners. Central to this strategy is the use of test factories and helpers to maintain concise and readable test code.
Sources: CLAUDE.md:83-88, DEVELOPMENT.md:18-30
Testing Hierarchy
The project categorizes tests into four distinct levels to ensure comprehensive coverage of the CLI, the validation logic, and the language-specific reporters.
Test Categories
| Category | Purpose | Command |
|---|---|---|
| Unit Tests | Fast validation of individual modules (e.g., CLI, storage, config). | npm run test:unit |
| Integration Tests | Validates the interaction between the validator and mock model clients. | npm run test:integration |
| Reporter Tests | Verifies language-specific collectors (Jest, Vitest, Pytest, Go, etc.). | npm run test:reporters |
| Full Suite | Runs all unit and base integration tests. | npm run test |
Sources: CLAUDE.md:83-88, DEVELOPMENT.md:18-40
Test Factories and Scenarios
To handle the complexity of validating TDD principles across different environments, the project uses a factory-based approach to generate consistent test data and scenarios.
Language Scenarios
Factories provide mock data for different languages, such as TypeScript and Python, including common TDD failure states like "not defined," "not a constructor," and "assertion error." This allows integration tests to iterate through different language contexts using a unified interface.
The diagram shows how the Scenario Factory abstracts language-specific details into common TDD states for the validator.
Sources: test/utils/factories/scenarios/languages/typescript.ts:1-200, test/integration/validator.scenarios.test.ts:25-45
Scenario Data Structure
The Scenario interface defines the requirements for an integration test case, including the expected outcome of the validation logic.
| Field | Description |
|---|---|
filePath | Path to the file being modified (test or implementation). |
oldContent | The content of the file before the operation. |
newContent | The proposed changes to the file. |
testResult | Mocked test runner output (e.g., failing assertion). |
violation | Boolean indicating if the scenario represents a TDD violation. |
Sources: test/integration/validator.scenarios.test.ts:28-35
Validation Logic Testing
The validator.test.ts file ensures that the core validation engine correctly parses AI model responses and handles edge cases such as invalid JSON or network errors.
Response Parsing Flow
The validator must extract a specific JSON format from the model's markdown response, even if the response includes conversational text or multiple code blocks.
The sequence diagram illustrates the robust extraction and error-handling flow within the validator module.
Sources: src/validation/validator.test.ts:39-150
Integration and Scenarios
Integration tests iterate through language-specific modifications to verify that the validator correctly identifies TDD violations.
Key Test Scenarios
- Creating new tests: Validates that adding a single test is allowed even without prior test output.
- Minimal Implementation: Ensures that creating an implementation to pass a failing test is allowed, provided it matches the failure type (e.g., creating a class stub for a "not defined" error).
- Refactoring: Verifies that refactoring of both tests and implementation is only permitted when relevant tests are passing.
- Multi-Test Violation: Ensures that adding more than one test simultaneously is blocked.
Sources: test/integration/validator.scenarios.test.ts:50-180, test/utils/factories/scenarios/languages/typescript.ts:200-300
Conclusion
The testing strategy of TDD Guard is highly structured, utilizing language-specific factories to simulate a wide array of TDD cycles. By separating core validation logic from language-specific reporters and using a standardized scenario-based integration suite, the project maintains high confidence in its ability to enforce TDD principles across diverse development environments.