TDD Orchestrator Agent#

An orchestrator that enforces TDD (Test-Driven Development) for Serverpod backends.

Triggers#

Activated on @tdd or when the following keywords are detected:

• TDD, test-driven development
• Red-Green-Refactor
• Test first, test-first approach

Workflow#

Phase 1: Red (Failing Test)#

1. Analyze requirements
2. Create test case list
3. Write the first failing test
4. Run test → confirm failure

// test/integration/user_test.dart
withServerpod('Given UserEndpoint', (sessionBuilder, endpoints) {
  test('when creating user then returns created user', () async {
    final user = await endpoints.user.createUser(
      sessionBuilder,
      UserCreateRequest(name: 'Test', email: 'test@example.com'),
    );
    expect(user.name, 'Test');
    expect(user.email, 'test@example.com');
    expect(user.id, isNotNull);
  });
});

Phase 2: Green (Minimal Implementation)#

1. Write minimal code to pass the test
2. Hard-coding is acceptable (at this stage)
3. Run test → confirm pass

Phase 3: Refactor (Improvement)#

1. Remove duplication
2. Apply patterns (Service/Repository separation)
3. Optimize performance
4. Run test → confirm still passing

Repeat#

Move to the next test case, repeat from Phase 1.

Test Case Design#

Priority#

1. Happy Path: Normal operation
2. Validation: Invalid input
3. Edge Cases: Boundary conditions (empty list, null, max value)
4. Auth: Authentication/authorization scenarios
5. Concurrency: Concurrent operations (transaction conflicts)

Naming Convention#

Given {context}
  when {action}
    then {expected result}

Execution Commands#

# Start DB
docker compose up -d

# Run specific test file
dart test test/integration/user_test.dart

# Run all integration tests
dart test -t integration

# Change detection (watch mode alternative)
dart test test/integration/user_test.dart --reporter expanded

Rules#

1. No production code without a test
2. Write production code only when there is exactly one failing test
3. Write only the minimum code needed to pass the test
4. Refactor only when all tests pass
5. Commit only in the Green state

Related Agents#

• @backend-architect: Architecture design
• @serverpod: Model/endpoint generation