Getting started

Patrol consists of 2 packages:


First, add the patrol package as a dev_dependency in your app's pubspec.yaml. You can do this by executing the following command in the app's directory:

flutter pub add patrol --dev


To use patrol in your test files, first import it:

import 'package:patrol/patrol.dart';

Once imported, you can write widget tests:

void main() {
    'counter is incremented when plus button is tapped',
    (PatrolTester $) async {
      await $.pumpWidget(const MyApp());

      expect($('0'), findsOneWidget);
      expect($('-1'), findsNothing);

      await $(Icons.remove).tap();

      expect($('0'), findsNothing);
      expect($('-1'), findsOneWidget);

To run the test, simply execute:

flutter test

Below is the same test written using vanilla Flutter:

void main() {
    'counter is incremented when plus button is tapped',
    (WidgetTester tester) async {
      await tester.pumpWidget(const MyApp());

      expect(find.text('0'), findsOneWidget);
      expect(find.text('-1'), findsNothing);

      await tester.tap(find.byIcon(Icons.remove));
      await tester.pump();

      expect(find.text('0'), findsNothing);
      expect(find.text('-1'), findsOneWidget);

This is just a small demo: Patrol's got many more features that make writing tests easier and more fun.

There are 2 types of tests specific to Flutter: widget tests (living in the test directory) and integration tests (living in the integration_test directory). Use flutter test to run widget tests. To run integration tests using Patrol's native automation feature, use patrol test instead. Read on to learn more!

Going from here#

Patrol has 2 main features that can be used independently of each other: custom finders and native capabilities. The choice if to use one or both belongs to you (yet most people use both!)

Here you can learn more about custom finders. They make interacting with Flutter widgets in tests much easier and more concise – you've seen the tiny sample above! They are platform independent and work in widget tests and integration tests.

Here you can learn more about our native automation. Native automation lets you do things that were previously impossible in Flutter integration tests - for example, you can go to the home screen, tap on notifications, change device settings, or toggle Wi-Fi.