In the introduction to unit testing recipe, welearned how to test Dart classes using the test package. In order to testWidget classes, we’ll need a few additional tools provided by theflutter_testpackage, which ships with the Flutter SDK.

The flutter_test package provides the following tools for testing Widgets:

• The WidgetTester, which allows us to build and interact with Widgets in a test environment.
• The testWidgets function. This function will automatically create a new WidgetTester for each test case, and is used in place of the normal test function.
• Finder classes. These allow us to search for Widgets in the test environment.
• Widget-specific Matcher constants, which help us verify whether a Finder locates a Widget or multiple Widgets in the test environment.If this sounds overwhelming, don’t worry! We’ll see how all of these pieces fittogether throughout this recipe.

Directions

• Add the flutter_test dependency
• Create a Widget to test
• Create a testWidgets test
• Build the Widget using the WidgetTester
• Search for our Widget using a Finder
• Verify our Widget is working using a Matcher

1. Add the flutter_test dependency

Before we can begin writing tests, we’ll need to include the flutter_testdependency in the dev_dependencies section of our pubspec.yaml file. Ifyou create a new Flutter project with the command line tools or code editor,this dependency should already be in place!

dev_dependencies:
  flutter_test:
    sdk: flutter

2. Create a Widget to test

Next, we’ll need to create a Widget that we can test! For this recipe, we’llcreate a Widget that displays a title and message.

class MyWidget extends StatelessWidget {
  final String title;
  final String message;
  const MyWidget({
    Key key,
    @required this.title,
    @required this.message,
  }) : super(key: key);
  @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

Now that we have a Widget to test, we can begin writing our first test! To getstarted, we’ll use thetestWidgetsfunction provided by the flutter_test package to define a test. ThetestWidgets function will allow us to define a Widget test and will create aWidgetTester for us to work with.

Our test will verify that MyWidget displays a given title and message.

void main() {
  // Define a test. The TestWidgets function will also provide a WidgetTester
  // for us to work with. The WidgetTester will allow us to build and interact
  // with Widgets in the test environment.
  testWidgets('MyWidget has a title and message', (WidgetTester tester) async {
    // Test code will go here!
  });
}

4. Build the Widget using the WidgetTester

Next, we’ll want to build MyWidget inside the test environment. To do so, wecan use thepumpWidgetmethod provided by the WidgetTester. The pumpWidget method will build andrender the Widget we provide.

In this case, we’ll create a MyWidget instance that displays “T” as the titleand “M” as the message.

void main() {
  testWidgets('MyWidget has a title and message', (WidgetTester tester) async {
    // Create the Widget tell the tester to build it
    await tester.pumpWidget(MyWidget(title: 'T', message: 'M'));
  });
}

Note

After the initial call to pumpWidget, the WidgetTester provides additionalways to rebuild the same Widget. This is useful if you’re working with aStatefulWidget or animations.

For example, if we tap a button, and this button calls setState, Flutter willnot automatically rebuild your Widget in the test environment. We need to useone of the following methods to ask Flutter to build our Widget once again.

• • tester.pump()
  • Triggers a rebuild of the Widget after a given duration.
• • 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 fine-grained control over the build lifecycle, which isparticularly useful while testing.

5. Search for our Widget using a Finder

Now that we’ve built our Widget in the test environment, we’ll want to searchthrough the Widget tree for the title and message Text Widgets using aFinder. This will allow us to verify that we’re displaying these Widgetscorrectly!

In this case, we’ll use the top-level findmethod provided by the flutter_test package to create our Finders. Since weknow we’re looking for Text widgets, we can use thefind.textmethod.

For more information about Finder classes, please see theFinding Widgets in a Widget Testrecipe.

void main() {
  testWidgets('MyWidget has a title and message', (WidgetTester tester) async {
    await tester.pumpWidget(MyWidget(title: 'T', message: 'M'));
    // Create our Finders
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');
  });
}

6. Verify our Widget is working using a Matcher

Finally, we can verify the title and message Text Widgets appear on screenusing the Matcher constants provided by flutter_test. Matcher classes area core part of the test package, and provide a common way to verify a givenvalue meets our expectations.

In this case, we want to ensure our Widgets appear on screen exactly one time.Therefore, we can use thefindsOneWidgetMatcher.

void main() {
  testWidgets('MyWidget has a title and message', (WidgetTester tester) async {
    await tester.pumpWidget(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 our
    // 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 forcommon cases.

• • findsNothing
  • verifies that no Widgets are found
• • findsWidgets
  • verifies one or more Widgets are found
• • findsNWidgets
  • verifies a specific number of Widgets are found

Complete example

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
void main() {
  // Define a test. The TestWidgets function will also provide a WidgetTester
  // for us to work with. The WidgetTester will allow us to build and interact
  // with Widgets in the test environment.
  testWidgets('MyWidget has a title and message', (WidgetTester tester) async {
    // Create the Widget tell the tester to build it
    await tester.pumpWidget(MyWidget(title: 'T', message: 'M'));
    // Create our Finders
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');
    // Use the `findsOneWidget` matcher provided by flutter_test to verify our
    // Text Widgets appear exactly once in the Widget tree
    expect(titleFinder, findsOneWidget);
    expect(messageFinder, findsOneWidget);
  });
}
class MyWidget extends StatelessWidget {
  final String title;
  final String message;
  const MyWidget({
    Key key,
    @required this.title,
    @required this.message,
  }) : super(key: key);
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Scaffold(
        appBar: AppBar(
          title: Text(title),
        ),
        body: Center(
          child: Text(message),
        ),
      ),
    );
  }
}