/testing

name: testing
description: "Use when writing or reviewing Flutter/Dart tests (unit, widget, golden), fixing flaky tests, adding coverage, or choosing between unit and widget tests."
license: MIT

Testing Skill

Write effective, meaningful Flutter and Dart tests that catch real regressions.

When to Use

Use this skill when:

• Writing unit tests for business logic, repositories, or utility classes.
• Writing widget tests for UI components.
• Reviewing existing tests for correctness and coverage.
• Fixing flaky or false-positive tests.
• Deciding between unit tests, widget tests, and integration tests.

---

1. Test Validity

Before writing or accepting a test, ask:

> **"Can this test actually fail if the real code is broken?"**

• Avoid tests that only confirm mocked/fake behavior without exercising real logic.
• Avoid tests that confirm behavior guaranteed by the language or standard library.
• Every test must be capable of catching a real regression.

// BAD — tests the mock, not real logic
test('should return user', () {
  when(() => repo.getUser()).thenReturn(fakeUser);
  expect(repo.getUser(), fakeUser); // Only proves the mock works
});

// GOOD — tests the cubit's state transitions driven by the mock
blocTest<UserCubit, UserState>(
  'should emit loaded state when getUser succeeds',
  build: () {
    when(() => repo.getUser()).thenAnswer((_) async => fakeUser);
    return UserCubit(repo);
  },
  act: (cubit) => cubit.fetchUser(),
  expect: () => [
    const UserState(status: UserStatus.loading),
    UserState(status: UserStatus.loaded, user: fakeUser),
  ],
);

---

2. Structure

Always use `group()` in test files. Name the group after the **class under test**:

group('Counter', () {
  late Counter counter;

  setUp(() {
    counter = Counter();
  });

  test('value should start at 0', () {
    expect(counter.value, 0);
  });

  test('should increment value by 1', () {
    counter.increment();
    expect(counter.value, 1);
  });
});

Rules:

• Use `setUp` for shared object creation; use `tearDown` for cleanup (closing streams, controllers).
• Keep each test focused on one behavior.
• Nest `group()` blocks for sub-features when a class has many methods.

---

3. Naming

Name test cases using **"should"** to describe expected behavior:

test('should emit updated list when item is added', () { ... });
test('should throw ArgumentError when input is negative', () { ... });

---

4. Unit Tests vs Widget Tests

| Type | Target | Tools | |---|---|---| | **Unit test** | Pure Dart logic, repositories, cubits/blocs | `test`, `bloc_test`, `mocktail` | | **Widget test** | Individual widgets, UI behavior, navigation | `flutter_test`, `WidgetTester` |

Default to **unit tests** for business logic. Use **widget tests** when verifying UI rendering, gesture handling, or widget interaction.

---

5. Widget Test Patterns

testWidgets('should display error message on failure', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: BlocProvider<LoginCubit>.value(
        value: mockLoginCubit,
        child: const LoginView(),
      ),
    ),
  );

  // Simulate failure state
  whenListen(
    mockLoginCubit,
    Stream.fromIterable([const LoginState(status: LoginStatus.failure, errorMessage: 'Invalid')]),
    initialState: const LoginState(),
  );
  await tester.pump();

  expect(find.text('Invalid'), findsOneWidget);
});

Rules:

• Wrap widgets in `MaterialApp` (or the app's root widget) to provide `MediaQuery`, `Directionality`, etc.
• Use `pump()` for a single frame or `pumpAndSettle()` when animations must complete.
• Prefer `find.byKey` over `find.text` for widgets that may have localized or dynamic text.

---

6. Mocking Best Practices

• Use `mocktail` for mocks (no code generation required).
• Call `registerFallbackValue()` in `setUpAll` for custom types passed to `any()`.
• Mock at the repository boundary, not at the HTTP/database layer.

class MockAuthRepository extends Mock implements AuthRepository {}

void main() {
  setUpAll(() {
    registerFallbackValue(FakeLoginRequest());
  });

  // ... tests
}

---

7. Test File Organization

test/
  feature_a/
    cubit/
      feature_a_cubit_test.dart
    view/
      feature_a_view_test.dart
    model/
      feature_a_model_test.dart

• Mirror the `lib/` folder structure under `test/`.
• One test file per source file.
• Name test files `<source_file>_test.dart`.