In theintroduction to unit testing recipe, you learned how to test Dart classes using thetest package. To test widget classes, you need a few additional tools provided by theflutter_test package, which ships with the Flutter SDK.

Theflutter_test package provides the following tools for testing widgets:

• TheWidgetTester allows building and interacting with widgets in a test environment.
• ThetestWidgets() function automatically creates a newWidgetTester for each test case, and is used in place of the normaltest() function.
• TheFinder classes allow searching for widgets in the test environment.
• Widget-specificMatcher constants help verify whether aFinder locates a widget or multiple widgets in the test environment.

If this sounds overwhelming, don't worry. Learn how all of these pieces fit together throughout this recipe, which uses the following steps:

1. Add theflutter_test dependency.
2. Create a widget to test.
3. Create atestWidgets test.
4. Build the widget using theWidgetTester.
5. Search for the widget using aFinder.
6. Verify the widget using aMatcher.

Before writing tests, include theflutter_test dependency in thedev_dependencies section of thepubspec.yaml file. If creating a new Flutter project with the command line tools or a code editor, this dependency should already be in place.

dev_dependencies:flutter_test:sdk:flutter

Next, create a widget for testing. For this recipe, create a widget that displays atitle andmessage.

classMyWidgetextendsStatelessWidget{constMyWidget({super.key,requiredthis.title,requiredthis.message});​finalStringtitle;finalStringmessage;​@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(title:'Flutter Demo',home:Scaffold(appBar:AppBar(title:Text(title)),body:Center(child:Text(message)),),);}}

With a widget to test, begin by writing your first test. Use thetestWidgets() function provided by theflutter_test package to define a test. ThetestWidgets function allows you to define a widget test and creates aWidgetTester to work with.

This test verifies thatMyWidget displays a given title and message. It is titled accordingly, and it will be populated in the next section.

voidmain(){// 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.});}

Next, buildMyWidget inside the test environment by using thepumpWidget() method provided byWidgetTester. ThepumpWidget method builds and renders the provided widget.

Create aMyWidget instance that displays "T" as the title and "M" as the message.

voidmain(){testWidgets('MyWidget has a title and message',(tester)async{// Create the widget by telling the tester to build it.awaittester.pumpWidget(constMyWidget(title:'T',message:'M'));});}

After the initial call topumpWidget(), theWidgetTester provides additional ways to rebuild the same widget. This is useful if you're working with aStatefulWidget or animations.

For example, tapping a button callssetState(), but Flutter won't automatically rebuild your widget in the test environment. Use one of the following methods to ask Flutter to rebuild the widget.

tester.pump(Duration duration)

Schedules a frame and triggers a rebuild of the widget. If aDuration is specified, 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.

tester.pumpAndSettle()

Repeatedly callspump() with the given duration until there are no longer any frames scheduled. This, essentially, waits for all animations to complete.

These methods provide fine-grained control over the build lifecycle, which is particularly useful while testing.

With a widget in the test environment, search through the widget tree for thetitle andmessage Text widgets using aFinder. This allows verification that the widgets are being displayed correctly.

For this purpose, use the top-levelfind() method provided by theflutter_test package to create theFinders. Since you know you're looking forText widgets, use thefind.text() method.

For more information aboutFinder classes, see theFinding widgets in a widget test recipe.

voidmain(){testWidgets('MyWidget has a title and message',(tester)async{awaittester.pumpWidget(constMyWidget(title:'T',message:'M'));​// Create the Finders.finaltitleFinder=find.text('T');finalmessageFinder=find.text('M');});}

Finally, verify the title and messageText widgets appear on screen using theMatcher constants provided byflutter_test.Matcher classes are a core part of thetest 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 thefindsOneWidgetMatcher.

voidmain(){testWidgets('MyWidget has a title and message',(tester)async{awaittester.pumpWidget(constMyWidget(title:'T',message:'M'));finaltitleFinder=find.text('T');finalmessageFinder=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);});}

In addition tofindsOneWidget,flutter_test provides additional matchers for common cases.

findsNothing

Verifies that no widgets are found.

findsWidgets

Verifies that one or more widgets are found.

findsNWidgets

Verifies that a specific number of widgets are found.

matchesGoldenFile

Verifies that a widget's rendering matches a particular bitmap image ("golden file" testing).

import'package:flutter/material.dart';import'package:flutter_test/flutter_test.dart';​voidmain(){// 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.awaittester.pumpWidget(constMyWidget(title:'T',message:'M'));​// Create the Finders.finaltitleFinder=find.text('T');finalmessageFinder=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);});}​classMyWidgetextendsStatelessWidget{constMyWidget({super.key,requiredthis.title,requiredthis.message});​finalStringtitle;finalStringmessage;​@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(title:'Flutter Demo',home:Scaffold(appBar:AppBar(title:Text(title)),body:Center(child:Text(message)),),);}}