Custom finders overview

Flutter's finders are powerful, but not very intuitive to use.

We took them and made something awesome.

Thanks to Patrol's custom finders, you'll take your tests from this:

testWidgets('signs up', (WidgetTester tester) async {
  await tester.pumpWidget(AwesomeApp());
  await tester.pumpAndSettle();

  await tester.enterText(
    find.byKey(Key('emailTextField')),
    'charlie@root.me',
  );
  await tester.pumpAndSettle();

  await tester.enterText(
    find.byKey(Key('nameTextField')),
    'Charlie',
  );
  await tester.pumpAndSettle();

  await tester.enterText(
    find.byKey(Key('passwordTextField')),
    'ny4ncat',
  );
  await tester.pumpAndSettle();

  await tester.tap(find.byKey(Key('termsCheckbox')));
  await tester.pumpAndSettle();

  await tester.tap(find.byKey(Key('signUpButton')));
  await tester.pumpAndSettle();

  expect(find.text('Welcome, Charlie!'), findsOneWidget);
});

to this:

patrolTest('signs up', (PatrolTester $) async {
  await $.pumpWidgetAndSettle(AwesomeApp());

  await $(#emailTextField).enterText('charlie@root.me');
  await $(#nameTextField).enterText('Charlie');
  await $(#passwordTextField).enterText('ny4ncat');
  await $(#termsCheckbox).tap();
  await $(#signUpButton).tap();

  await $('Welcome, Charlie!').waitUntilVisible();
});

Set up#

All you have to do is to add package patrol to dev_dependencies in your project's pubspec.yaml.

flutter pub add patrol --dev

Our custom finders depend only on Flutter itself. This means you can use them no matter if you're writing a mobile, web, desktop, or embedded app!

Writing#

When using Patrol's custom finders, you use patrolTest function instead of testWidgets.

The main difference between the testWidgets() function and the patrolTest() function is the type of the tester you get in the test callback. patrolTest() gives you a PatrolTester, which is much more powerful that the default WidgetTester.

testWidgets('sign in', (WidgetTester tester) async {
  await tester.tap(find.byKey(Key('signUpButton')));
}

patrolTest('sign in', (PatrolTester $) async {
  await $(#signUpButton).tap();
}

Usage#

You run widget tests using Patrol's custom finders the same way as you run normal widget tests:

flutter test