Patrol

Visit Website

Introduction

Patrol is a multiplatform end-to-end UI testing framework for Flutter apps, developed by LeanCode since 2022. Its README describes it as overcoming the limitations of Flutter’s integration_test package by handling native interactions, and LeanCode says it is battle-tested on production apps it builds for clients. The latest release at the time of writing was patrol v4.11.0, published on 2 November 2026.

The core problem Patrol solves is that Flutter’s default integration_test package cannot interact with the operating system the app runs on. That makes it impossible to test many important flows, such as granting runtime permissions, signing in through a WebView or Google services, or tapping notifications. Patrol’s native automation lets tests do this in plain Dart: enable or disable Wi-Fi and cellular data, toggle dark mode, handle location permission dialogs, open the notification shade and tap a notification, and more. The documentation keeps a feature-parity table for Android and iOS.

Patrol’s custom finders make tests shorter and more readable. Instead of repeated tester.enterText(find.byKey(Key('emailTextField')), ...) and pumpAndSettle() calls, you write await $(#emailTextField).enterText('...') and await $('Welcome, Charlie!').waitUntilVisible(). The finders are also published standalone as the patrol_finders package, so they can be used in widget tests.

The Patrol CLI (patrol_cli) is needed to run tests with native automation and speeds up development with Hot Restart. Widget tests can still run with flutter test. The website highlights full isolation between tests and sharding, which address weaknesses of the plain integration_test runner, real-time console logs during execution, and a Patrol DevTools extension for inspecting visible Android and iOS views. Recent releases added Patrol 4.0 with cross-platform improvements, Patrol Web for Flutter web apps, a VS Code extension for running and debugging tests, an MCP integration, and Swift Package Manager support for iOS and macOS in Patrol 4.7.0.

Because Patrol tests run as native instrumentation tests, they work on device farms. The website lists Firebase Test Lab, BrowserStack, LambdaTest, Sauce Labs, Marathon, emulator.wtf and AWS Device Farm as compatible.

How it compares: Flutter’s integration_test is official and simple but cannot touch native UI. Appium can drive native UI but is outside the Flutter toolchain and does not use Dart. Maestro uses YAML flows and works across frameworks. Patrol keeps tests in Dart, close to the app code, while reaching native features. LeanCode offers paid setup, training and test-automation services, but the framework itself is fully open source.

In the quality loop, Patrol covers the end-to-end layer of a Flutter test pyramid above unit and widget tests, especially for flows involving permissions, notifications and system settings.

The source code is at leancodepl/patrol on GitHub under the Apache-2.0 licence, with about 1,500 stars; the most recent commit was on 10 November 2026.

Features

1. Native automation: Handle permission dialogs, notifications, WebViews and device settings from Dart.
2. Custom finders: Concise $() syntax, also available as patrol_finders.
3. Patrol CLI: Runs native-enabled tests and supports Hot Restart.
4. Test isolation and sharding: Overcomes integration_test limitations for reliable suites.
5. Device farm support: Works with Firebase Test Lab, BrowserStack, Sauce Labs, LambdaTest and others.
6. DevTools and VS Code extensions: Inspect native views and run or debug tests from the editor.
7. Patrol Web: Testing support for Flutter web apps.
8. Swift Package Manager support: iOS and macOS projects using SPM are supported (4.7.0+).

Pros

1. Tests stay in Dart: No second language or toolchain for E2E tests.
2. Solves real gaps: Permissions and notifications become testable.
3. Free to use: Open source under the Apache-2.0 licence, so the core tool costs nothing to use.
4. Actively maintained: The repository had commits as recent as 10 November 2026.

Cons

1. Flutter only: Not for native or React Native apps.
2. Extra native setup: Android and iOS projects need configuration for the native test runner.
3. Requires the Patrol CLI: Native features do not work with plain flutter test.
4. Fast-moving releases: Major versions have required migrations (for example from native to platform).

Usage and Links (Example)

Add Patrol and the CLI (follow the platform setup guide for Android and iOS):

flutter pub add patrol --dev
dart pub global activate patrol_cli

A test that grants a permission and taps a notification (API as shown in the README):

import 'package:patrol/patrol.dart';
import 'package:my_app/main.dart';

void main() {
  patrolTest('shows nearby stores', ($) async {
    await $.pumpWidgetAndSettle(const MyApp());
    await $(#findStoresButton).tap();
    await $.platform.mobile.grantPermissionWhenInUse();
    await $('Nearby stores').waitUntilVisible();
  });
}

Run it on a connected device or emulator:

patrol test --target integration_test/stores_test.dart

Practical tips:

1. Keep most coverage in unit and widget tests; use Patrol for critical journeys.
2. Use stable keys (#symbol finders) rather than text where copy changes often.
3. Shard long suites across devices on a device farm.

Resources:

• Patrol website
• GitHub repository
• Patrol documentation

Pricing

Patrol is free and open source under the Apache-2.0 licence.

Recommended for?

1. Flutter teams needing E2E tests for permissions, notifications and native screens.
2. Teams running device farms, which support Patrol’s native test runners.
3. Developers who want tests in Dart alongside widget tests.
4. Not a fit for non-Flutter apps.

Conclusion

Patrol is the leading way to write true end-to-end tests for Flutter apps, filling the native-interaction gap in integration_test while keeping tests in Dart.

Invest in the setup once and you can test the flows that matter most to users, from permissions to notifications.