Dart Testing Suite

Unit Testing
Mocking Dependencies
Test Coverage
Workflow: Testing Execution

Unit Testing

Utilize package:test as the standard testing library for Dart CLI and backend applications.

Organize test files to mirror the lib directory structure. Append _test.dart to test files.
Group related tests using the group() function.
Use setUp() and tearDown() for shared test state.
Write pure logic inside Domain/BLoC and extract to static pure functions for 100% unit test coverage.
Use string interpolation for test group names: group('$ClassName', ...)
Structure each test using the Arrange-Act-Assert (Given-When-Then) convention:
- Arrange: Set up mocks, create instances, prepare input data.
- Act: Call the method under test.
- Assert: Verify the output or side effects.
Separate setup from verification to keep tests readable and maintainable.

Mocking Dependencies

mocktail vs mockito Decision

Criteria	`mocktail` (Recommended)	`mockito`
Code generation	Not needed	Requires `build_runner`
Setup speed	Fast (extend `Mock`)	Slower (annotation + codegen)
Null safety	Full support	Full support
API style	`when(() => mock.method())`	`when(mock.method())`
Best for	Most projects, fast iteration	Large projects with complex APIs

Rule: Default to mocktail (no codegen, faster setup). Use mockito only when you need @GenerateNiceMocks for complex APIs with many overloads.

mocktail Setup (Recommended)

import 'package:mocktail/mocktail.dart';

// Create mock — no code generation needed
class MockUserRepository extends Mock implements UserRepository {}

void main() {
  late MockUserRepository mockRepo;

  setUp(() {
    mockRepo = MockUserRepository();
  });

  test('fetches user successfully', () {
    // Arrange
    when(() => mockRepo.getUser('1'))
        .thenAnswer((_) async => const User(id: '1', name: 'Alice'));

    // Act
    final user = await mockRepo.getUser('1');

    // Assert
    expect(user.name, 'Alice');
    verify(() => mockRepo.getUser('1')).called(1);
  });
}

mockito Setup (Code-Gen)

import 'package:mockito/annotations.dart';
import 'package:mockito/mockito.dart';

@GenerateNiceMocks([MockSpec<UserRepository>()])
import 'user_test.mocks.dart';  // Generated by: dart run build_runner build

Verification APIs

API	Purpose
`verify(() => mock.method()).called(1)`	Assert method was called exactly once
`verifyNever(() => mock.method())`	Assert method was never called
`verifyNoMoreInteractions(mock)`	Assert no unchecked interactions remain
`verifyInOrder([...])`	Assert methods were called in specific order
`reset(mock)`	Clear all stubs and interactions

Registering Fallback Values

For methods with custom types as parameters:

setUpAll(() {
  registerFallbackValue(const User(id: '0', name: 'fallback'));
});

Test Coverage

Target 100% logic coverage for domain models and business logic.
Run coverage with dart test --coverage=coverage or flutter test --coverage.
See dart-coverage skill for detailed LCOV/HTML report generation.

Workflow: Testing Execution

Follow this sequential workflow when testing a Dart feature. Copy the checklist to track progress.

Task Progress

[ ] Step 1: Write Unit Tests. Focus on core business logic. Ensure files end with _test.dart.
[ ] Step 2: Generate Mocks. Run dart run build_runner build to generate mocks if using Mockito.
[ ] Step 3: Run Tests. Execute dart test.
[ ] Step 4: Check Coverage. Run dart test --coverage=coverage and verify coverage targets are met.