Install Patrol
Check out our video version of this tutorial on YouTube!
If you want to use Patrol finders in your existing widget or golden tests, go to Using Patrol finders in widget tests.
Setup
Install patrol_cli:
flutter pub global activate patrol_cliPatrol CLI (command-line interface) is a small program that enables running
Patrol UI tests. It is necessary to run UI tests (flutter test won't work! Here's why).
Make sure to add patrol to your PATH environment variable.
It's explained in the README.
Verify that installation was successful and your environment is set up properly:
patrol doctorExample output:
Patrol CLI version: 2.3.1+1
Android:
• Program adb found in /Users/username/Library/Android/sdk/platform-tools/adb
• Env var $ANDROID_HOME set to /Users/username/Library/Android/sdk
iOS / macOS:
• Program xcodebuild found in /usr/bin/xcodebuild
• Program ideviceinstaller found in /opt/homebrew/bin/ideviceinstallerBe sure that for the platform you want to run the test on, all the checks are green.
Patrol CLI invokes the Flutter CLI for certain commands. To override the command used,
pass the --flutter-command argument or set the PATROL_FLUTTER_COMMAND environment
variable. This supports FVM (by setting the value to fvm flutter), puro (puro flutter)
and potentially other version managers.
Add a dependency on the patrol package in the
dev_dependencies section of pubspec.yaml. patrol package requires
Android SDK version 21 or higher.
flutter pub add patrol --devCreate patrol section in your pubspec.yaml:
dependencies:
# ...
dev_dependencies:
# ...
patrol:
app_name: My App
android:
package_name: com.example.myapp
ios:
bundle_id: com.example.MyApp
macos:
bundle_id: com.example.macos.MyAppIn this tutorial, we are using example app, which has package name
com.example.myapp on Android, bundle id com.example.MyApp on iOS,
com.example.macos.MyApp on macOS and My App name on all platforms.
Replace any occurences of those names with proper values.
If you don't know where to get package_name and bundle_id from, see the FAQ section.
Integrate with native side
The 3 first steps were common across platforms. The rest is platform-specific.
Psst... Android is a bit easier to set up, so we recommend starting with it!
Create a simple integration test
Let's create a dummy Flutter integration test that you'll use to verify that Patrol is correctly set up.
Paste the following code into integration_test/example_test.dart:
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:patrol/patrol.dart';
void main() {
patrolTest(
'counter state is the same after going to home and switching apps',
($) async {
// Replace later with your app's main widget
await $.pumpWidgetAndSettle(
MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text('app')),
backgroundColor: Colors.blue,
),
),
);
expect($('app'), findsOneWidget);
if (!Platform.isMacOS) {
await $.native.pressHome();
}
},
);
}It does only 2 things:
- first, it finds a text
app - then (on mobile platforms), it exits to home screen
It's a very simple test, but it's enough to verify that Patrol is correctly set
up. To run integration_test/example_test.dart on a connected Android, iOS or macOS device:
patrol test -t integration_test/example_test.dartIf the setup is successful, you should see a summary like one below.
Test summary:
📝 Total: 1
✅ Successful: 1
❌ Failed: 0
⏩ Skipped: 0
📊 Report: <some path>
⏱️ Duration: 4sIf something went wrong, please proceed to the FAQ section which might contain an answer to your issue.
If you are looking for a working example of a Flutter app with Patrol tests, check out the example app in the patrol repository.
Initializing app inside a test
To be able to test your app, you need to initialize it and pump the app's root widget, so it appears on the screen. It's very similar to what is done in main function of your app, but it has some key differences, that can break your tests. Easy way to implement it is to copy main function of your app and then adjust it, so it works with Patrol. Here's what to remove when running app inside a patrol test:
- DO NOT call
WidgetsFlutterBinding.ensureInitialized(). - DO NOT use
runApp(). Instead, use$.pumpWidget()(or$.pumpWidgetAndSettle()to wait until the UI is rendered). Pass the same argument which was passed torunApp(). - DO NOT modify
FlutterError.onError. Sometimes it is done by some monitoring tools (like Crashlytics). Those tools rely on intercepting errors by modifyingFlutterError.onErrorcallback and it causes that the test engine can't see any exceptions, thus can't end a test if it fails. One way is to move the code that would be common for both the test and the app into a method and leave the rest in main function of the app, or move whole app initialization to a function and define some arguments to enable or diable parts needed in a specific place.
For an example, look at createApp in common.dart in Patrol repository on GitHub.
Flavors
If your app is using flavors, then you can pass them like so:
patrol test --target integration_test/example_test.dart --flavor developmentor you can specify them in pubspec.yaml (recommended):
patrol:
app_name: My App
flavor: development
android:
package_name: com.example.myapp
ios:
bundle_id: com.example.MyApp
app_name: The Awesome App
macos:
bundle_id: com.example.macos.MyAppFAQ
Android
iOS
If you couldn't find an answer to your question/problem, feel free to ask on Patrol Discord Server.
Going from here
To learn how to write Patrol tests, see finders and native automation sections.