Cursor rule

1---
2paths:
3  - "**/*.dart"
4  - "**/pubspec.yaml"
5  - "**/analysis_options.yaml"
6---
7# Dart/Flutter Testing
8 
9> This file extends [common/testing.md](../common/testing.md) with Dart and Flutter-specific content.
10 
11## Test Framework
12 
13- **flutter_test** / **dart:test** — built-in test runner
14- **mockito** (with `@GenerateMocks`) or **mocktail** (no codegen) for mocking
15- **bloc_test** for BLoC/Cubit unit tests
16- **fake_async** for controlling time in unit tests
17- **integration_test** for end-to-end device tests
18 
19## Test Types
20 
21| Type | Tool | Location | When to Write |
22|------|------|----------|---------------|
23| Unit | `dart:test` | `test/unit/` | All domain logic, state managers, repositories |
24| Widget | `flutter_test` | `test/widget/` | All widgets with meaningful behavior |
25| Golden | `flutter_test` | `test/golden/` | Design-critical UI components |
26| Integration | `integration_test` | `integration_test/` | Critical user flows on real device/emulator |
27 
28## Unit Tests: State Managers
29 
30### BLoC with `bloc_test`
31 
32```dart
33group('CartBloc', () {
34  late CartBloc bloc;
35  late MockCartRepository repository;
36 
37  setUp(() {
38    repository = MockCartRepository();
39    bloc = CartBloc(repository);
40  });
41 
42  tearDown(() => bloc.close());
43 
44  blocTest<CartBloc, CartState>(
45    'emits updated items when CartItemAdded',
46    build: () => bloc,
47    act: (b) => b.add(CartItemAdded(testItem)),
48    expect: () => [CartState(items: [testItem])],
49  );
50 
51  blocTest<CartBloc, CartState>(
52    'emits empty cart when CartCleared',
53    seed: () => CartState(items: [testItem]),
54    build: () => bloc,
55    act: (b) => b.add(CartCleared()),
56    expect: () => [const CartState()],
57  );
58});
59```
60 
61### Riverpod with `ProviderContainer`
62 
63```dart
64test('usersProvider loads users from repository', () async {
65  final container = ProviderContainer(
66    overrides: [userRepositoryProvider.overrideWithValue(FakeUserRepository())],
67  );
68  addTearDown(container.dispose);
69 
70  final result = await container.read(usersProvider.future);
71  expect(result, isNotEmpty);
72});
73```
74 
75## Widget Tests
76 
77```dart
78testWidgets('CartPage shows item count badge', (tester) async {
79  await tester.pumpWidget(
80    ProviderScope(
81      overrides: [
82        cartNotifierProvider.overrideWith(() => FakeCartNotifier([testItem])),
83      ],
84      child: const MaterialApp(home: CartPage()),
85    ),
86  );
87 
88  await tester.pump();
89  expect(find.text('1'), findsOneWidget);
90  expect(find.byType(CartItemTile), findsOneWidget);
91});
92 
93testWidgets('shows empty state when cart is empty', (tester) async {
94  await tester.pumpWidget(
95    ProviderScope(
96      overrides: [cartNotifierProvider.overrideWith(() => FakeCartNotifier([]))],
97      child: const MaterialApp(home: CartPage()),
98    ),
99  );
100 
101  await tester.pump();
102  expect(find.text('Your cart is empty'), findsOneWidget);
103});
104```
105 
106## Fakes Over Mocks
107 
108Prefer hand-written fakes for complex dependencies:
109 
110```dart
111class FakeUserRepository implements UserRepository {
112  final _users = <String, User>{};
113  Object? fetchError;
114 
115  @override
116  Future<User?> getById(String id) async {
117    if (fetchError != null) throw fetchError!;
118    return _users[id];
119  }
120 
121  @override
122  Future<List<User>> getAll() async {
123    if (fetchError != null) throw fetchError!;
124    return _users.values.toList();
125  }
126 
127  @override
128  Stream<List<User>> watchAll() => Stream.value(_users.values.toList());
129 
130  @override
131  Future<void> save(User user) async {
132    _users[user.id] = user;
133  }
134 
135  @override
136  Future<void> delete(String id) async {
137    _users.remove(id);
138  }
139 
140  void addUser(User user) => _users[user.id] = user;
141}
142```
143 
144## Async Testing
145 
146```dart
147// Use fake_async for controlling timers and Futures
148test('debounce triggers after 300ms', () {
149  fakeAsync((async) {
150    final debouncer = Debouncer(delay: const Duration(milliseconds: 300));
151    var callCount = 0;
152    debouncer.run(() => callCount++);
153    expect(callCount, 0);
154    async.elapse(const Duration(milliseconds: 200));
155    expect(callCount, 0);
156    async.elapse(const Duration(milliseconds: 200));
157    expect(callCount, 1);
158  });
159});
160```
161 
162## Golden Tests
163 
164```dart
165testWidgets('UserCard golden test', (tester) async {
166  await tester.pumpWidget(
167    MaterialApp(home: UserCard(user: testUser)),
168  );
169 
170  await expectLater(
171    find.byType(UserCard),
172    matchesGoldenFile('goldens/user_card.png'),
173  );
174});
175```
176 
177Run `flutter test --update-goldens` when intentional visual changes are made.
178 
179## Test Naming
180 
181Use descriptive, behavior-focused names:
182 
183```dart
184test('returns null when user does not exist', () { ... });
185test('throws NotFoundException when id is empty string', () { ... });
186testWidgets('disables submit button while form is invalid', (tester) async { ... });
187```
188 
189## Test Organization
190 
191```
192test/
193├── unit/
194│   ├── domain/
195│   │   └── usecases/
196│   └── data/
197│       └── repositories/
198├── widget/
199│   └── presentation/
200│       └── pages/
201└── golden/
202    └── widgets/
203 
204integration_test/
205└── flows/
206    ├── login_flow_test.dart
207    └── checkout_flow_test.dart
208```
209 
210## Coverage
211 
212- Target 80%+ line coverage for business logic (domain + state managers)
213- All state transitions must have tests: loading → success, loading → error, retry
214- Run `flutter test --coverage` and inspect `lcov.info` with a coverage reporter
215- Coverage failures should block CI when below threshold
216