awesome-ai-setup testing.instructions.md

Testing Conventions

These conventions apply to all test code in test/.

---

Test Structure

Mirror the lib/ structure in test/:

test/
├── features/
│   ├── tasks/
│   │   ├── data/
│   │   │   ├── datasources/
│   │   │   │   └── task_remote_datasource_test.dart
│   │   │   └── repositories/
│   │   │       └── task_repository_impl_test.dart
│   │   ├── domain/
│   │   │   └── usecases/
│   │   │       ├── get_tasks_test.dart
│   │   │       └── create_task_test.dart
│   │   └── presentation/
│   │       ├── screens/
│   │       │   └── task_list_screen_test.dart
│   │       └── providers/
│   │           └── task_list_provider_test.dart
├── core/
│   └── ...
└── helpers/
    ├── mock_factories.dart    # shared mock creation
    └── test_helpers.dart      # shared pump helpers

---

Test Naming

// File naming - matches source file with _test suffix
// task_list_provider.dart → task_list_provider_test.dart

// Group structure - describe the subject
group('TaskListProvider', () {
  // Subgroup for specific behaviors
  group('build', () {
    test('returns empty state when user has no tasks', () async { ... });
    test('returns tasks sorted by due date', () async { ... });
    test('emits error state when repository throws', () async { ... });
  });

  group('createTask', () {
    test('adds task to list on success', () async { ... });
    test('reverts to previous state on failure', () async { ... });
  });
});

Test names should read as complete sentences: "returns empty state when user has no tasks".

---

Mocking Strategy

Mock at the repository layer. Do not mock data sources in widget tests or provider tests. Repository mocks are the correct abstraction level for testing business logic and UI.

// Correct - mock the repository interface
class MockTaskRepository extends Mock implements TaskRepository {}

// Wrong - mocking too deep for a widget test
class MockTaskRemoteDataSource extends Mock implements TaskRemoteDataSource {}