In order to locate Widgets in a test environment, we need to use Finderclasses. While it’s possible to write our own Finder classes, it’s generallymore convenient to locate Widgets using the tools provided by theflutter_testpackage.

In this recipe, we’ll look at thefindconstant provided by the flutter_test package and demonstrate how to work withsome of the Finders it provides. For a full list of available finders, pleaseconsult theCommonFinders documentation.

If you’re unfamiliar with Widget testing and the role of Finder classes,review the Introduction to widget testing recipe.

Directions

  • Find a Text Widget
  • Find a Widget with a specific Key
  • Find a specific Widget instance

1. Find a Text Widget

In our tests, we often need to find Widgets that contain specific text. This isexactly what the find.text method is for. It will create a Finder thatsearches for Widgets that display a specific String of text.

  1. testWidgets('finds a Text Widget', (WidgetTester tester) async {
  2.   // Build an App with a Text Widget that displays the letter 'H'
  3.   await tester.pumpWidget(MaterialApp(
  4.     home: Scaffold(
  5.       body: Text('H'),
  6.     ),
  7.   ));
  9.   // Find a Widget that displays the letter 'H'
  10.   expect(find.text('H'), findsOneWidget);
  11. });

2. Find a Widget with a specific Key

In some cases, we may want to find a Widget based on the Key that has beenprovided to it. This can be handy if we’re displaying multiple instances of thesame Widget. For example, we might have a ListView that displays severalText Widgets that contain the same text.

In this case, we can provide a Key to each Widget in the list. This will allowus to uniquely identify a specific Widget, making it easier to find the Widgetin the test environment.

  1. testWidgets('finds a Widget using a Key', (WidgetTester tester) async {
  2.   // Define our test key
  3.   final testKey = Key('K');
  5.   // Build a MaterialApp with the testKey
  6.   await tester.pumpWidget(MaterialApp(key: testKey, home: Container()));
  8.   // Find the MaterialApp Widget using the testKey
  9.   expect(find.byKey(testKey), findsOneWidget);
  10. });

3. Find a specific Widget instance

Finally, we might be interested in locating a specific instance of a Widget.For example, this can be useful when creating Widgets that take a childproperty and we want to ensure we’re rendering the child Widget.

  1. testWidgets('finds a specific instance', (WidgetTester tester) async {
  2.   final childWidget = Padding(padding: EdgeInsets.zero);
  4.   // Provide our childWidget to the Container
  5.   await tester.pumpWidget(Container(child: childWidget));
  7.   // Search for the childWidget in the tree and verify it exists
  8.   expect(find.byWidget(childWidget), findsOneWidget);
  9. });

Summary

The find constant provided by the flutter_test package gives us several waysto locate Widgets in the test environment. This recipe demonstrated three ofthese methods, and several more methods exist for different purposes.

If the above examples do not work for a particular use-case, please see theCommonFinders documentationto review all available methods.

Complete example

  1. import 'package:flutter/material.dart';
  2. import 'package:flutter_test/flutter_test.dart';
  4. void main() {
  5.   testWidgets('finds a Text Widget', (WidgetTester tester) async {
  6.     // Build an App with a Text Widget that displays the letter 'H'
  7.     await tester.pumpWidget(MaterialApp(
  8.       home: Scaffold(
  9.         body: Text('H'),
  10.       ),
  11.     ));
  13.     // Find a Widget that displays the letter 'H'
  14.     expect(find.text('H'), findsOneWidget);
  15.   });
  17.   testWidgets('finds a Widget using a Key', (WidgetTester tester) async {
  18.     // Define our test key
  19.     final testKey = Key('K');
  21.     // Build a MaterialApp with the testKey
  22.     await tester.pumpWidget(MaterialApp(key: testKey, home: Container()));
  24.     // Find the MaterialApp Widget using the testKey
  25.     expect(find.byKey(testKey), findsOneWidget);
  26.   });
  28.   testWidgets('finds a specific instance', (WidgetTester tester) async {
  29.     final childWidget = Padding(padding: EdgeInsets.zero);
  31.     // Provide our childWidget to the Container
  32.     await tester.pumpWidget(Container(child: childWidget));
  34.     // Search for the childWidget in the tree and verify it exists
  35.     expect(find.byWidget(childWidget), findsOneWidget);
  36.   });
  37. }