Widget Tests
A widget test builds a widget in a fake environment, then taps and types like a user and checks what is on the screen. It runs without an emulator, so it is fast.
A Counter Widget Test
dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('counter increments when button is tapped', (tester) async {
await tester.pumpWidget(const MaterialApp(home: CounterPage()));
expect(find.text('0'), findsOneWidget);
expect(find.text('1'), findsNothing);
await tester.tap(find.byIcon(Icons.add));
await tester.pump(); // rebuild after setState
expect(find.text('1'), findsOneWidget);
});
}
The Tester Toolbox
| Method | Purpose |
tester.pumpWidget(widget) | Show a widget |
tester.pump() | Run one frame (apply state changes) |
tester.pumpAndSettle() | Wait until all animations and timers finish |
tester.tap(finder) | Tap |
tester.enterText(finder, 'abc') | Type into a field |
tester.drag(finder, Offset(0, -300)) | Scroll or swipe |
Finders and Matchers
| Finder | Finds |
find.text('Hello') | A Text with that content |
find.byType(ElevatedButton) | Widgets of a type |
find.byKey(const Key('login')) | A widget with that key |
find.byIcon(Icons.add) | An icon |
find.byTooltip('Add') | A tooltip |
Matchers: findsOneWidget, findsNothing, findsNWidgets(3), findsWidgets.
Test a Login Form
dart
testWidgets('shows error for empty email', (tester) async {
await tester.pumpWidget(const MaterialApp(home: Scaffold(body: LoginForm())));
await tester.tap(find.text('Login'));
await tester.pump();
expect(find.text('Email is required'), findsOneWidget);
});
testWidgets('accepts valid input', (tester) async {
await tester.pumpWidget(const MaterialApp(home: Scaffold(body: LoginForm())));
await tester.enterText(find.byType(TextFormField).first, 'a@b.com');
await tester.enterText(find.byType(TextFormField).last, 'secret1');
await tester.tap(find.text('Login'));
await tester.pumpAndSettle();
expect(find.text('Email is required'), findsNothing);
});
Providers in tests: If your widget needs Provider or Riverpod, wrap it in the same ChangeNotifierProvider or ProviderScope inside pumpWidget, with fake data.
Integration Tests
Integration tests run the real app on a device or emulator and drive it like a user. They are slower, so use them for the most important flows, such as login and checkout.
bash
flutter pub add dev:integration_test --sdk=flutter
dart
// integration_test/app_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart' as app;
void main() {
IntegrationTestWidgetsFlutterBinding.ensureInitialized();
testWidgets('user can add an item', (tester) async {
app.main();
await tester.pumpAndSettle();
await tester.tap(find.byIcon(Icons.add));
await tester.pumpAndSettle();
expect(find.text('1'), findsOneWidget);
});
}
bash
flutter test integration_test/app_test.dart -d <device-id>
Testing Strategy
- Many unit tests for logic
- Some widget tests for important screens
- A few integration tests for the key journeys
- Run tests automatically in CI before each release
Use keys: Add key: const Key('loginButton') to important widgets. Finding them by key makes tests stable even when the text changes.
Conclusion
Widget tests check what the user sees and does, and integration tests prove the whole app works on a device. Use the pyramid: many small tests, few big ones.
Quick Summary: Use testWidgets with pumpWidget, find, tap and pump, and use integration_test for complete flows.