Module 18: Testing -- Proving Your Code Works

Why Testing Matters

You might be thinking: "I can just run the app and tap around to check if it works." That works when your app has one screen and three buttons. It stops working when you have fifteen screens, shared state, and edge cases you forgot about.

Automated tests give you three superpowers:

1. Confidence to refactor. Want to rewrite that messy function? Run the tests. If they pass, your rewrite works. If they fail, you broke something and you know exactly what.

2. Protection against regressions. You fix a bug on Monday. Without a test, you might reintroduce the same bug on Thursday. With a test, it is impossible -- the test would fail.

3. Documentation. Tests describe what your code is supposed to do. A test named "sortByPriority returns tasks with priority 1 first" tells you exactly what that method does without reading the implementation.

Flutter has three levels of testing:

This module focuses on unit tests and widget tests. They are fast, reliable, and cover the vast majority of what you need to verify.

Unit Tests with the test Package

Unit tests live in the test/ directory and test pure Dart logic -- no Flutter widgets involved.

// lib/models/calculator.dart
class Calculator {
  double add(double a, double b) => a + b;
  double divide(double a, double b) {
    if (b == 0) throw ArgumentError('Cannot divide by zero');
    return a / b;
  }
}

// test/calculator_test.dart
import 'package:test/test.dart';
import 'package:my_app/models/calculator.dart';

void main() {
  late Calculator calculator;

  setUp(() {
    calculator = Calculator();
  });

  group('Calculator', () {
    test('add returns the sum of two numbers', () {
      expect(calculator.add(2, 3), equals(5));
    });

    test('add handles negative numbers', () {
      expect(calculator.add(-1, -2), equals(-3));
    });

    test('divide returns the quotient', () {
      expect(calculator.divide(10, 2), equals(5));
    });

    test('divide by zero throws ArgumentError', () {
      expect(() => calculator.divide(10, 0), throwsArgumentError);
    });
  });
}

Key Test Functions

• test('description', () { ... }) -- defines a single test case
• group('name', () { ... }) -- groups related tests together (shows up as a nested section in test output)
• setUp(() { ... }) -- runs before each test in the current group
• tearDown(() { ... }) -- runs after each test (for cleanup)
• expect(actual, matcher) -- the assertion that makes or breaks a test

Common Matchers

Matchers are the right side of expect(). They describe what you expect the actual value to look like:

// Equality
expect(value, equals(42));
expect(value, isNull);
expect(value, isNotNull);
expect(value, isTrue);
expect(value, isFalse);

// Collections
expect(list, contains('item'));
expect(list, hasLength(3));
expect(list, isEmpty);

// Comparison
expect(value, greaterThan(5));
expect(value, lessThanOrEqualTo(10));

// Type checking
expect(value, isA<String>());

// Exceptions
expect(() => riskyFunction(), throwsException);
expect(() => riskyFunction(), throwsA(isA<ArgumentError>()));
expect(() => riskyFunction(), throwsArgumentError);

Test Organization and Naming

Good test names describe the behavior, not the implementation:

// Bad: describes the implementation
test('calls removeWhere on the list', () { ... });

// Good: describes the behavior
test('deleteTask removes the task from the list', () { ... });

Group tests by the method or behavior they cover:

group('sortByPriority', () {
  test('returns tasks with priority 1 first', () { ... });
  test('returns empty list for empty input', () { ... });
  test('preserves order for equal priorities', () { ... });
});

Running Tests

# Run all tests
flutter test

# Run a specific test file
flutter test test/calculator_test.dart

# Run with verbose output
flutter test --reporter expanded

Widget Tests with flutter_test

Widget tests use the flutter_test package (included in every Flutter project by default) and the WidgetTester helper.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:my_app/widgets/counter_widget.dart';

void main() {
  testWidgets('Counter increments when button is tapped',
      (WidgetTester tester) async {
    // Arrange: render the widget
    await tester.pumpWidget(
      const MaterialApp(home: CounterWidget()),
    );

    // Assert: verify initial state
    expect(find.text('0'), findsOneWidget);
    expect(find.text('1'), findsNothing);

    // Act: tap the button
    await tester.tap(find.byIcon(Icons.add));
    await tester.pump(); // Rebuild after state change

    // Assert: verify updated state
    expect(find.text('1'), findsOneWidget);
    expect(find.text('0'), findsNothing);
  });
}

Finding Widgets

The find object is your search tool. It locates widgets in the rendered tree:

find.text('Hello');              // Find by text content
find.byType(ElevatedButton);    // Find by widget type
find.byIcon(Icons.add);         // Find by icon
find.byKey(const Key('myKey')); // Find by Key
find.byWidgetPredicate(
  (w) => w is Text && w.data == 'Hi'
);                               // Find by custom predicate

Widget Matchers

After finding a widget, verify its existence:

findsOneWidget          // Exactly one widget found
findsNothing            // No widgets found
findsNWidgets(3)        // Exactly 3 widgets found
findsAtLeastNWidgets(1) // At least 1 widget found

Interacting with Widgets

WidgetTester can simulate taps, text entry, drags, and long presses:

await tester.tap(find.byType(ElevatedButton));
await tester.enterText(find.byType(TextField), 'Hello');
await tester.drag(find.byType(ListView), const Offset(0, -200));
await tester.longPress(find.byType(ListTile));

After every interaction that changes state, call one of:

await tester.pump();           // Rebuild once (good for setState)
await tester.pumpAndSettle();  // Rebuild until all animations complete

Testing Callbacks

To verify a widget calls its callback when tapped, use a flag variable:

testWidgets('calls onPressed when tapped', (tester) async {
  bool wasPressed = false;

  await tester.pumpWidget(
    MaterialApp(
      home: Scaffold(
        body: MyButton(
          onPressed: () => wasPressed = true,
        ),
      ),
    ),
  );

  await tester.tap(find.byType(MyButton));
  expect(wasPressed, isTrue);
});

Testing State Changes

To verify that state changes update the UI correctly:

testWidgets('checkbox toggles task completion', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: Scaffold(
        body: TaskTile(
          task: Task(id: '1', title: 'Test', isCompleted: false),
          onToggle: () {},
          onDelete: () {},
        ),
      ),
    ),
  );

  // Find the Checkbox widget and verify it is unchecked
  final checkbox = tester.widget<Checkbox>(find.byType(Checkbox));
  expect(checkbox.value, isFalse);
});

The Key to Widget Keys

When you have multiple widgets of the same type (like multiple delete buttons), find.byType returns all of them. Use Key to distinguish between them:

// In the widget
IconButton(
  key: Key('delete_${task.id}'),
  icon: const Icon(Icons.delete),
  onPressed: onDelete,
)

// In the test
await tester.tap(find.byKey(const Key('delete_1')));

Mocking -- Faking Dependencies

When your code depends on an external service (API, database), you do not want your tests calling real servers. Create mock implementations:

abstract class ApiService {
  Future<String> fetchData();
}

class MockApiService implements ApiService {
  String? mockResponse;
  bool shouldThrow = false;

  @override
  Future<String> fetchData() async {
    if (shouldThrow) throw Exception('Network error');
    return mockResponse ?? 'default';
  }
}

// In the test
test('handles API response', () async {
  final mockApi = MockApiService();
  mockApi.mockResponse = 'test data';

  final result = await mockApi.fetchData();
  expect(result, equals('test data'));
});

There Are No Dumb Questions

Q: Do I need to test every single widget?

A: No. Focus on widgets that have logic -- conditional rendering, state changes, callbacks. A widget that just displays a Text in a Card is probably not worth testing individually. But a widget with a checkbox that toggles state, a conditional loading spinner, or complex conditional layout? Test those.

Q: Why do I need MaterialApp in pumpWidget?

A: Many Flutter widgets depend on inherited widgets provided by MaterialApp -- things like Theme, MediaQuery, Navigator, and Directionality. Without MaterialApp, widgets that use Theme.of(context) or Navigator.of(context) will throw errors. Always wrap your test widget in MaterialApp.

Q: What is the difference between pump() and pumpAndSettle()?

A: pump() triggers a single frame rebuild. Use it after setState calls. pumpAndSettle() keeps pumping frames until there are no more scheduled frames -- essentially waiting for all animations to complete. Use pumpAndSettle() when your widget has animations (like AnimatedContainer or Hero transitions).

Q: Should tests be in the same file as the code they test?

A: No. Tests go in the test/ directory, mirroring the structure of lib/. If your model is at lib/models/task.dart, your tests go at test/task_test.dart or test/models/task_test.dart.

Q: How do I test async code?

A: Mark your test callback as async and use await:

test('fetches data successfully', () async {
  final result = await myService.fetchData();
  expect(result, isNotNull);
});

For widget tests with async operations, use await tester.pumpAndSettle() to wait for async rebuilds.

📝 Module Quiz

Test what you learned. 45 seconds per question. Passing score is set per module. Your best attempt is saved in your browser so you can track progress -- nothing is sent to a server.

Sharpen Your Pencil

Exercise 1: Task Model Unit Tests

Create a Task class with id, title, description, isCompleted (default false), priority (1-3), and createdAt. Include copyWith, toggleCompleted, static sortByPriority, filterCompleted, filterPending, and equality override based on id.

Then write comprehensive unit tests covering:

• Task creation -- defaults are correct, all fields are set
• copyWith -- no-arg returns equal task, single-field changes only that field, other fields preserved
• toggleCompleted -- pending becomes completed, completed becomes pending, other fields unchanged
• sortByPriority -- priority 1 first, empty list returns empty, same-priority preserved
• filterCompleted / filterPending -- correct filtering, empty list, all-completed list
• equality -- same id equals, different id not equals

Exercise 2: Widget Tests for TaskTile

Create a TaskTile StatelessWidget that shows a Checkbox, the task title (strikethrough if completed), a priority color indicator, and a delete IconButton. Use widget keys: Key('checkbox_${task.id}') and Key('delete_${task.id}').

Then write widget tests for:

• Displays the task title text
• Shows checkbox unchecked for pending task
• Shows checkbox checked for completed task
• Calls onToggle when checkbox is tapped
• Calls onDelete when delete button is tapped
• Shows strikethrough text decoration for completed task
• Shows correct priority color (red for 1, orange for 2, green for 3)

Exercise 3: Screen Widget Tests

Create a TaskListScreen with 3 sample tasks, a ListView of TaskTile widgets, and a FloatingActionButton that adds a new task. Write tests that verify:

• All 3 initial task titles are visible
• Tapping the FAB increases the visible task count to 4
• Tapping a delete button decreases the count to 2
• Tapping a checkbox toggles its checked state