333-333-333/flutter-tdd

When to Use

• Starting implementation of any new feature (write test FIRST)
• Testing domain entities and value objects
• Testing use cases / application services
• Testing Riverpod notifiers and providers
• Creating mock implementations for repository interfaces
• Testing infrastructure adapters (API clients, local storage)

Critical Patterns

| Pattern | Rule | |---------|------| | Test FIRST | Write the failing test before production code. Always. | | Red -> Green -> Refactor | Fail -> pass -> clean up. Never skip a step. | | Mirror structure | test/ mirrors lib/ exactly | | File naming | foo.dart -> foo_test.dart | | Mocks via interfaces | Domain repository interfaces ARE the mock boundary — no mockito needed for simple cases | | No test pollution | Each test is independent, no shared mutable state | | group() for context | Use group() to organize related tests | | Riverpod: use ProviderContainer | Create isolated containers per test |

The TDD Cycle

1. RED    — Write a test that describes the desired behavior. Run it. It MUST fail.
2. GREEN  — Write the MINIMUM code to make the test pass. Nothing more.
3. REFACTOR — Clean up while keeping tests green.
4. REPEAT

When Writing Code with AI

1. DESCRIBE the behavior you want as a test
2. AI writes the failing test
3. Run it — confirm RED
4. AI writes the implementation
5. Run it — confirm GREEN
6. AI refactors if needed
7. Run it — confirm still GREEN

Test Directory Structure

mobile/
  test/
    features/
      auth/
        domain/
          entities/
            user_test.dart
          value_objects/
            email_test.dart
            password_test.dart
        application/
          use_cases/
            login_use_case_test.dart
        presentation/
          providers/
            auth_state_provider_test.dart
        infrastructure/
          repositories/
            auth_repository_impl_test.dart
      booking/
        domain/
        application/
        presentation/
        infrastructure/
    shared/
      domain/
        value_objects/
          money_test.dart
    helpers/
      mocks.dart            # Shared mock implementations
      test_providers.dart   # Riverpod test overrides

Domain Entity Tests

See assets/booking_test.dart

Value Object Tests

See assets/email_test.dart

Mock Pattern (Manual — No Framework)

See assets/mocks.dart

For more complex mocking needs, use mocktail:

See assets/mocks_mocktail.dart

Use Case Tests

See assets/login_use_case_test.dart

Riverpod Provider/Notifier Tests

See assets/auth_state_provider_test.dart

AsyncNotifier Tests

See assets/async_notifier_test.dart

Either Pattern Tests

When using fpdart or dartz for Either<Failure, T>:

See assets/either_test.dart

Commands

# Run all unit tests
flutter test

# Run specific test file
flutter test test/features/auth/domain/entities/user_test.dart

# Run tests matching a name pattern
flutter test --name "login"

# Run with coverage
flutter test --coverage
# View coverage report (install lcov first: brew install lcov)
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

# Run tests in a specific directory
flutter test test/features/auth/

# Watch mode (re-run on changes) — requires flutter_test_watch or similar
# Not built-in; use: find test -name '*_test.dart' | entr flutter test

Dev Dependencies

See assets/pubspec_dev_deps.yaml

Anti-Patterns

| Don't | Do | |-------|-----| | Write code first, tests later | Write test FIRST (red), then code (green) | | Test implementation details | Test behavior — inputs and outputs | | Shared mutable state between tests | Fresh setUp() per test | | Import infrastructure in domain tests | Mock via interfaces | | Skip tearDown for ProviderContainer | Always container.dispose() | | One giant test function | group() + focused test() with descriptive names | | Use print() for debugging tests | Use expect() with clear matchers | | Mock everything | Only mock external boundaries (repos, APIs) |