tdd-tom-testing-rules

New Feature TDD Rule

Description:

Mandatory Rule: All new features MUST be implemented using Test-Driven Development (TDD) principles. Prioritize tests before code, ensuring comprehensive coverage and a robust design. Tests should be focused and efficient, employing either unit or integration tests as appropriate. All tests MUST adhere to the Test Object Model for improved maintainability and reusability where it makes sense.

Instructions:

1. Choose the Right Testing Strategy:

   • BEFORE writing any tests, deeply consider whether a UNIT test or an INTEGRATION test is most effective for the feature or component being developed.
   • UNIT Tests: Focus on individual modules or functions in isolation, mocking dependencies. Ideal for testing complex logic within a single unit.
     • Consider using unit tests when:
       • The logic within a single function or class is complex and needs thorough testing.
       • Dependencies can be easily and realistically mocked.
       • You need to isolate a specific unit to verify its behavior in detail.
     • For guidance on writing unit tests, refer to the Unit Test Writing Guide: READ @.brain/knowledge/testing/vitest/vitest-unit-testing.rules.ts
   • INTEGRATION Tests: Test the interaction between multiple modules or systems. They verify that different parts of the application work together correctly.
     • Consider using integration tests when:
       • The functionality depends on the interaction between multiple components, services, or external systems (e.g., databases, APIs, CLIs).
       • Mocking is difficult, unrealistic, or overly complex.
       • You need to ensure that different parts of the system work together correctly in a realistic environment.
     • For guidance on writing integration tests, refer to the Integration Test Writing Guide: READ @.brain/knowledge/testing/vitest/vitest-integration-testing.rules.ts
   • Document the reasoning behind your choice of unit or integration testing in the code or test file.

2. Start with tests: Before writing any implementation code, create a failing test case that defines the desired behavior of the new feature, based on the chosen testing strategy.

3. Follow the Red-Green-Refactor cycle:

   • Red: Write a failing test (unit or integration).
   • Green: Write the minimal code to make the test pass.
   • Refactor: Improve code structure while keeping the test green. Be cautious about over-abstracting or introducing unnecessary complexity during refactoring. If tests get more complicated because of the refactoring, it is a code smell.
   • Repeat: Move to the next part of the feature

4. Employ the Test Object Model (When Appropriate):

   • If the Test Object Model is deemed beneficial for organization and reusability (e.g., in complex integration tests or UI tests), create a *.to.ts file for each logical group of interactions or components being tested.

   • Encapsulate interaction logic within this test object.

   • Example:

     // user-registration.to.ts
     import { UserService } from './user-service';
     
     export class UserRegistrationTestObject {
         private userService: UserService;
     
         constructor() {
             this.userService = new UserService();
         }
     
         async registerUser(userData: any) {
             return await this.userService.register(userData);
         }
     }
     

   • Do not force the use of the Test Object Model if it adds unnecessary complexity or doesn't provide significant value in simpler scenarios.

5. Consult the detailed guidelines for comprehensive instructions:

   • TDD: READ @.brain/knowledge/testing/vitest/vitest-tdd.rules.ts
   • Test Object Model: READ @.brain/knowledge/testing/vitest/vitest-test-object-model.rules.ts
   • Unit vs. Integration Testing: READ @.brain/knowledge/testing/unit-vs-integration-testing.rules.ts