Introduction to Patrol

What is Patrol?

Patrol is a powerful, open-source UI testing framework designed specifically for Flutter apps. Released in September 2022 and developed by LeanCode, one of the world’s leading Flutter development consultancies, Patrol builds upon Flutter’s core testing tools to enable developers to do things that were previously impossible.

Native Automation

Interact with permission dialogs, notifications, WebViews, and device settings directly from your Dart tests

Custom Finders

Write cleaner, more intuitive tests with Patrol’s streamlined finder syntax

Hot Restart

Develop tests faster with hot restart support - no need to rebuild your app

Production-Ready

Battle-tested in production apps with millions of users

Why Patrol?

Flutter’s built-in integration_test package is powerful, but it has significant limitations that make it difficult to test real-world scenarios. Patrol overcomes these limitations while providing a better developer experience.

Native Platform Access

Unlock native platform features right within your Flutter tests:

Interact with permission dialogs, notifications, and WebViews
Modify device settings, toggle Wi-Fi, and control network conditions
Handle system alerts and native UI elements
Achieve all this effortlessly using plain Dart code

patrolTest('handles location permission', ($) async {
  await $.pumpWidgetAndSettle(MyApp());
  
  // Tap button that requests location permission
  await $('Get Location').tap();
  
  // Handle the native permission dialog
  if (await $.platform.mobile.isPermissionDialogVisible()) {
    await $.platform.mobile.grantPermissionWhenInUse();
  }
  
  // Continue testing your app
  expect($('Location granted'), findsOneWidget);
});

Intuitive Custom Finders

Say goodbye to verbose test code. Patrol’s custom finder system makes tests readable and maintainable.

With Patrol
Without Patrol

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

  await $(#emailTextField).enterText('[email protected]');
  await $(#nameTextField).enterText('Charlie');
  await $(#passwordTextField).enterText('ny4ncat');
  await $(#termsCheckbox).tap();
  await $(#signUpButton).tap();

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

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

  await tester.enterText(
    find.byKey(Key('emailTextField')),
    '[email protected]',
  );
  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);
});

Patrol’s custom finders are also available standalone in the patrol_finders package for use in widget tests.

Production-Grade Features

Patrol revolutionizes Flutter’s built-in integration_test plugin:

Full test isolation between tests prevents flaky tests
Test sharding for parallel execution on CI/CD
Hot Restart makes development fast and enjoyable
Console logs provide real-time insights during test execution
DevTools extension for inspecting Android/iOS views

Compatible with Device Farms

With Patrol’s native-like testing capabilities, you can use popular device farms:

Firebase Test Lab

BrowserStack

LambdaTest

Marathon

emulator.wtf

AWS Device Farm

Platform Support

Patrol supports multiple platforms with comprehensive native automation capabilities:

Platform	Support Level	Minimum Version	Native Automation
Android	✅ Full	API 21 (Android 5.0)	✅ Yes
iOS	✅ Full	iOS 13.0	✅ Yes
macOS	🟡 Alpha	macOS 10.14	⏳ Coming soon
Web	✅ Full	Modern browsers	✅ Yes
Windows	❌ Not supported	-	-
Linux	❌ Not supported	-	-

Patrol works on both physical devices and emulators/simulators for supported platforms.

Version Requirements

To use Patrol, you need:

name: my_app

environment:
  sdk: '>=3.8.0 <4.0.0'
  flutter: '>=3.32.0'

dev_dependencies:
  patrol: ^4.1.1
  flutter_test:
    sdk: flutter

Minimum requirements:

Dart SDK: 3.8.0 or higher
Flutter SDK: 3.32.0 or higher
patrol package: 4.1.1 (current stable)
patrol_cli: 4.1.0 (current stable)

Make sure patrol and patrol_cli versions are compatible. See the compatibility table for details.

How Patrol Works

Patrol consists of three main components:

Dart package (patrol) - The test API you use in your test code
CLI tool (patrol_cli) - Runs your tests and manages the test environment
Native automation servers - Android and iOS native code that executes platform interactions

Write tests in Dart

Use Patrol’s intuitive API to write tests that interact with both Flutter widgets and native platform features.

Run with patrol CLI

The CLI builds your app in a special test mode and runs the native test runner.

Native automation executes

Native servers on Android/iOS receive commands from your Dart code and execute platform interactions.

Get results

Tests run to completion and you get detailed results with logs and reports.

Trusted by the Flutter Community

Patrol is a fully open-source project used by developers and companies worldwide. At LeanCode, we use Patrol to test production-grade apps for clients across industries.

Get Started with Patrol

Ready to write your first test? Follow our quickstart guide to set up Patrol in minutes.

Need Expert Help?

LeanCode offers end-to-end automated UI testing services tailored for Flutter apps:

🚀 Automate Flutter App Testing with Patrol
🎓 Patrol Setup & Training

Learn More

Quickstart Guide

Get Patrol installed and running in your project

Write Your First Test

Follow a hands-on tutorial to write a complete test

GitHub Repository

View the source code and contribute

Join Discord

Get help from the community

Video Introduction: Watch our YouTube video for a quick introduction to Patrol.

Getting Started

Core Concepts

Custom Finders

Native Automation

Platform Support

Introduction to Patrol

What is Patrol?

Native Automation

Custom Finders

Hot Restart

Production-Ready

Why Patrol?

Native Platform Access

Intuitive Custom Finders

Production-Grade Features

Compatible with Device Farms

Firebase Test Lab

BrowserStack

LambdaTest

Marathon

emulator.wtf

AWS Device Farm

Platform Support

Version Requirements

How Patrol Works

Trusted by the Flutter Community

Get Started with Patrol

Need Expert Help?

Learn More

Quickstart Guide

Write Your First Test

GitHub Repository

Join Discord

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Custom Finders

Native Automation

Platform Support

​What is Patrol?

Native Automation

Custom Finders

Hot Restart

Production-Ready

​Why Patrol?

​Native Platform Access

​Intuitive Custom Finders

​Production-Grade Features

​Compatible with Device Farms

Firebase Test Lab

BrowserStack

LambdaTest

Marathon

emulator.wtf

AWS Device Farm

​Platform Support

​Version Requirements

​How Patrol Works

​Trusted by the Flutter Community

Get Started with Patrol

​Need Expert Help?

​Learn More

Quickstart Guide

Write Your First Test

GitHub Repository

Join Discord

Build docs developers (and LLMs) love

What is Patrol?

Why Patrol?

Native Platform Access

Intuitive Custom Finders

Production-Grade Features

Compatible with Device Farms

Platform Support

Version Requirements

How Patrol Works

Trusted by the Flutter Community

Need Expert Help?

Learn More