Flutter Docs Get started
Packages & plugins
Flu er 3.35 has landed! Get ready for a performance boost and stateful hot reload on the web. Learn more
Testing & debugging
Testing
On this page
Overview An introduction to widget testing 1. Add the u er_test
Unit testing
Cookbook Testing Widget Introduction
dependency
Widget testing 2. Create a widget to test
In the introduction to unit testing recipe, you learned how to test Dart classes using the 3. Create a testWidgets test
Introduction
test package. To test widget classes, you need a few additional tools provided by the
4. Build the widget using the
Find widgets flutter_test package, which ships with the Flu er SDK.
WidgetTester
Simulate scrolling
The flutter_test package provides the following tools for testing widgets: Notes about the pump()
Simulate user interaction methods
The WidgetTester allows building and interacting with widgets in a test environment.
Integration testing The testWidgets() function automatically creates a new WidgetTester for each
5. Search for our widget
using a Finder
Test a plugin test case, and is used in place of the normal test() function.
The Finder classes allow searching for widgets in the test environment. 6. Verify the widget using a
Handle plugin code in tests Matcher
Widget-speci c Matcher constants help verify whether a Finder locates a widget or
Debugging multiple widgets in the test environment. Additional Matchers
Debugging tools If this sounds overwhelming, Complete example
docs. u er.dev uses cookies from Google to deliver anddon't worry.
enhance theLearn how
quality ofall
itsof these pieces
services t together
and to analyze tra c. Learn more. OK, got it
Debug your app throughout this recipe, which uses the following steps:
programmatically
Add the flutter_test dependency.
Create a widget to test.
Create a testWidgets test.
Build the widget using the WidgetTester .
Search for the widget using a Finder .
Verify the widget using a Matcher .
1. Add the flutter_test dependency
Before writing tests, include the flutter_test dependency in the dev_dependencies
section of the pubspec.yaml le. If creating a new Flu er project with the command line
tools or a code editor, this dependency should already be in place.
yaml
dev_dependencies:
flutter_test:
sdk: flutter
2. Create a widget to test
Next, create a widget for testing. For this recipe, create a widget that displays a title and
message .
dart
class MyWidget extends StatelessWidget {
const MyWidget({super.key, required this.title, required this.message});
final String title;
final String message;
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
home: Scaffold(
appBar: AppBar(title: Text(title)),
body: Center(child: Text(message)),
),
);
}
}
3. Create a testWidgets test
With a widget to test, begin by writing your rst test. Use the testWidgets() function
provided by the flutter_test package to de ne a test. The testWidgets function allows
you to de ne a widget test and creates a WidgetTester to work with.
This test veri es that MyWidget displays a given title and message. It is titled accordingly,
and it will be populated in the next section.
dart
void main() {
// Define a test. The TestWidgets function also provides a WidgetTester
// to work with. The WidgetTester allows you to build and interact
// with widgets in the test environment.
testWidgets('MyWidget has a title and message', (tester) async {
// Test code goes here.
});
}
4. Build the widget using the WidgetTester
Next, build MyWidget inside the test environment by using the pumpWidget() method
provided by WidgetTester . The pumpWidget method builds and renders the provided
widget.
Create a MyWidget instance that displays "T" as the title and "M" as the message.
dart
void main() {
testWidgets('MyWidget has a title and message', (tester) async {
// Create the widget by telling the tester to build it.
await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
});
}
Notes about the pump() methods
A er the initial call to pumpWidget() , the WidgetTester provides additional ways to
rebuild the same widget. This is useful if you're working with a StatefulWidget or
animations.
For example, tapping a bu on calls setState() , but Flu er won't automatically rebuild
your widget in the test environment. Use one of the following methods to ask Flu er to
rebuild the widget.
tester.pump(Duration duration)
Schedules a frame and triggers a rebuild of the widget. If a Duration is speci ed, it
advances the clock by that amount and schedules a frame. It does not schedule multiple
frames even if the duration is longer than a single frame.
Note
To kick o the animation, you need to call pump() once (with no duration speci ed) to
start the ticker. Without it, the animation does not start.
tester.pumpAndSettle()
Repeatedly calls pump() with the given duration until there are no longer any frames
scheduled. This, essentially, waits for all animations to complete.
These methods provide ne-grained control over the build lifecycle, which is particularly
useful while testing.
5. Search for our widget using a Finder
With a widget in the test environment, search through the widget tree for the title and
message Text widgets using a Finder . This allows veri cation that the widgets are being
displayed correctly.
For this purpose, use the top-level find() method provided by the flutter_test
package to create the Finders . Since you know you're looking for Text widgets, use the
find.text() method.
For more information about Finder classes, see the Finding widgets in a widget test
recipe.
dart
void main() {
testWidgets('MyWidget has a title and message', (tester) async {
await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
// Create the Finders.
final titleFinder = find.text('T');
final messageFinder = find.text('M');
});
}
6. Verify the widget using a Matcher
Finally, verify the title and message Text widgets appear on screen using the Matcher
constants provided by flutter_test . Matcher classes are a core part of the test
package, and provide a common way to verify a given value meets expectations.
Ensure that the widgets appear on screen exactly one time. For this purpose, use the
findsOneWidget Matcher .
dart
void main() {
testWidgets('MyWidget has a title and message', (tester) async {
await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
final titleFinder = find.text('T');
final messageFinder = find.text('M');
// Use the `findsOneWidget` matcher provided by flutter_test to verify
// that the Text widgets appear exactly once in the widget tree.
expect(titleFinder, findsOneWidget);
expect(messageFinder, findsOneWidget);
});
}
Additional Matchers
In addition to findsOneWidget , flutter_test provides additional matchers for common
cases.
findsNothing
Veri es that no widgets are found.
findsWidgets
Veri es that one or more widgets are found.
findsNWidgets
Veri es that a speci c number of widgets are found.
matchesGoldenFile
Veri es that a widget's rendering matches a particular bitmap image ("golden le"
testing).
Complete example
dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
// Define a test. The TestWidgets function also provides a WidgetTester
// to work with. The WidgetTester allows building and interacting
// with widgets in the test environment.
testWidgets('MyWidget has a title and message', (tester) async {
// Create the widget by telling the tester to build it.
await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
// Create the Finders.
final titleFinder = find.text('T');
final messageFinder = find.text('M');
// Use the `findsOneWidget` matcher provided by flutter_test to
// verify that the Text widgets appear exactly once in the widget tree
expect(titleFinder, findsOneWidget);
expect(messageFinder, findsOneWidget);
});
}
class MyWidget extends StatelessWidget {
const MyWidget({super.key, required this.title, required this.message});
final String title;
final String message;
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
home: Scaffold(
appBar: AppBar(title: Text(title)),
body: Center(child: Text(message)),
),
);
}
}
Was this page's content helpful?
Unless stated otherwise, the documentation on this site re ects the latest stable version of Flu er. Page last updated on
2025-02-12. View source or report an issue.
Except as otherwise noted, this site is licensed under a Creative Commons A ribution 4.0 International License, Terms Brand Privacy Security
and code samples are licensed under the 3-Clause BSD License.
