Compatibility

This page documents version compatibility requirements for Patrol packages and the Flutter/Dart SDKs.

Current Requirements

The latest stable versions of Patrol require:

patrol package

Version: 4.1.1

Dart SDK: >=3.8.0 <4.0.0
Flutter SDK: >=3.32.0

patrol_cli

Version: 4.1.0

Dart SDK: >=3.8.0 <4.0.0
Compatible with patrol: ^4.1.0

patrol_finders

Version: 3.1.0

Dart SDK: >=3.8.0 <4.0.0
Flutter SDK: >=3.32.0

patrol_log

Version: 0.7.1

Dart SDK: >=3.8.0 <4.0.0
No Flutter version requirement

Package Compatibility Matrix

The following table shows which versions of patrol_cli and patrol are compatible with each other:

patrol_cli version	patrol version	Minimum Flutter version	Notes
4.1.0+	4.1.0+	3.32.0	✅ Current stable
4.0.2 - 4.0.x	4.1.0+	3.32.0	Compatible with newer patrol
4.0.0 - 4.0.1	4.0.0 - 4.0.1	3.32.0	Exact version match
3.11.0	3.20.0	3.32.0
3.9.0 - 3.10.0	3.18.0 - 3.19.0	3.32.0
3.7.0 - 3.8.0	3.16.0 - 3.17.0	3.32.0
3.5.0 - 3.6.0	3.14.0 - 3.15.2	3.24.0
3.4.1	3.13.1 - 3.13.2	3.24.0
3.4.0	3.13.0	3.24.0
3.3.0	3.12.0	3.24.0
3.2.1	3.11.2	3.24.0
3.2.0	3.11.0 - 3.11.1	3.22.0
3.1.0 - 3.1.1	3.10.0	3.22.0
2.6.5 - 3.0.1	3.6.0 - 3.10.0	3.16.0
2.6.0 - 2.6.4	3.4.0 - 3.5.2	3.16.0
2.3.0 - 2.5.0	3.0.0 - 3.3.0	3.16.0
2.2.0 - 2.2.2	2.3.0 - 2.3.2	3.3.0
2.0.1 - 2.1.5	2.0.1 - 2.2.5	3.3.0
2.0.0	2.0.0	3.3.0
1.1.4 - 1.1.11	1.0.9 - 1.1.11	3.3.0	⚠️ Legacy versions

Reading the table:

Versions marked with + (e.g., 4.1.0+) indicate compatibility with all later versions
Ranges (e.g., 3.9.0 - 3.10.0) indicate compatibility with all versions in that range
The minimum Flutter version applies to both packages

Platform Support

Different platforms have different minimum version requirements:

Android

Android Requirements

Minimum SDK: API 21 (Android 5.0 Lollipop)
Target SDK: API 34+ recommended
Gradle: 7.0+
Kotlin: 1.7.0+ (if using Kotlin DSL)
Java: JDK 17 (recommended)

Configured in android/app/build.gradle:

android {
    compileSdk = 34
    defaultConfig {
        minSdk = 21
        targetSdk = 34
    }
}

iOS

iOS Requirements

Minimum version: iOS 13.0
Xcode: 14.0+
CocoaPods: 1.10.0+
Swift: 5.7+ (if using Swift code)

Configured in ios/Podfile:

platform :ios, '13.0'

macOS

macOS Requirements

Minimum version: macOS 10.14 (Mojave)
Xcode: 14.0+
Status: 🟡 Alpha support
Native automation: ⏳ Coming soon

Configured in macos/Podfile:

platform :macos, '10.14'

macOS support is in alpha stage. Some features may not work as expected, and there is no native automation support yet.

Web

Web Requirements

Supported browsers:
- Chrome/Chromium (recommended)
- Firefox
- Safari (limited support)
Node.js: 16.0+ (for development)
Status: ✅ Full support

Run tests with:

patrol test --target patrol_test/app_test.dart --platform web

Checking Your Versions

To check which versions you’re currently using:

patrol --version
# Output: 4.1.0

Updating Patrol

To ensure compatibility, update both packages together:

Update patrol_cli

flutter pub global activate patrol_cli

Update patrol package

flutter pub upgrade patrol

Or specify a version in pubspec.yaml:

dev_dependencies:
  patrol: ^4.1.1

Then run:

flutter pub get

Verify compatibility

patrol doctor

Best practice: Always use the latest stable versions of both patrol and patrol_cli to ensure compatibility and get the latest features and bug fixes.

Troubleshooting Version Issues

Error: test_bundle.dart compilation failed

This usually indicates a version mismatch between patrol and patrol_cli.Solution:

Check versions: patrol --version and flutter pub deps | grep patrol
Refer to the compatibility matrix above
Update to compatible versions
Clean and rebuild: flutter clean && flutter pub get

Error: Unsupported Flutter version

Your Flutter SDK version may be too old.Solution:

Check your Flutter version: flutter --version
Update Flutter: flutter upgrade
Make sure you’re on at least Flutter 3.32.0
If you need to use an older Flutter version, consult the compatibility matrix for older Patrol versions

Error: Unsupported Dart SDK version

Your Dart SDK version may be incompatible.Solution:

Check pubspec.yaml environment constraints:
```
environment:
  sdk: '>=3.8.0 <4.0.0'
```
Update Flutter (which includes Dart): flutter upgrade
Or switch to a compatible Flutter channel: flutter channel stable

Android build fails with 'minSdkVersion' error

Patrol requires Android API 21 or higher.Solution: Update android/app/build.gradle:

defaultConfig {
    minSdk = 21  // Minimum for Patrol
    targetSdk = 34
}

iOS build fails with deployment target error

Patrol requires iOS 13.0 or higher.Solution:

Update ios/Podfile:
```
platform :ios, '13.0'
```
In Xcode, set deployment target to 13.0 for both Runner and RunnerUITests targets
Run: cd ios && pod install && cd ..

Using Older Versions

If you need to use an older version of Flutter or Dart, you may need to use older versions of Patrol. Consult the compatibility matrix to find compatible versions.

Older versions receive limited support. We recommend upgrading to the latest stable Flutter and Patrol versions when possible.

Example: Using Patrol with Flutter 3.24.0

If you’re on Flutter 3.24.0, you can use:

pubspec.yaml

dev_dependencies:
  patrol: ^3.15.2

And install:

flutter pub global activate patrol_cli 3.6.0

Patrol Dependencies

Patrol packages have the following dependency relationships:

patrol depends on patrol_finders and patrol_log
patrol_finders can be used standalone in widget tests
patrol_log is a shared logging utility used by both packages

Version Announcements

Stay updated on new releases:

Migration Guides

When upgrading between major versions, refer to our migration guides:

Migrate to v4

Upgrading from Patrol 3.x to 4.x

Native to Platform API

Migrate from deprecated native API

From integration_test

Migrate from Flutter’s integration_test

Changelog

View all changes across versions

Need Help?

If you’re experiencing compatibility issues:

Check this compatibility matrix
Verify your versions with patrol doctor
Review the troubleshooting section
Ask on Discord
Open an issue on GitHub

Back to Getting Started

Return to the quickstart guide to set up Patrol

Getting Started

Core Concepts

Custom Finders

Native Automation

Platform Support

Current Requirements

patrol package

patrol_cli

patrol_finders

patrol_log

Package Compatibility Matrix

Platform Support

Android

Android Requirements

iOS

iOS Requirements

macOS

macOS Requirements

Web

Web Requirements

Checking Your Versions

Updating Patrol

Troubleshooting Version Issues

Using Older Versions

Example: Using Patrol with Flutter 3.24.0

Patrol Dependencies

Version Announcements

Migration Guides

Migrate to v4

Native to Platform API

From integration_test

Changelog

Need Help?

Back to Getting Started

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Custom Finders

Native Automation

Platform Support

​Current Requirements

patrol package

patrol_cli

patrol_finders

patrol_log

​Package Compatibility Matrix

​Platform Support

​Android

Android Requirements

​iOS

iOS Requirements

​macOS

macOS Requirements

​Web

Web Requirements

​Checking Your Versions

​Updating Patrol

​Troubleshooting Version Issues

​Using Older Versions

​Example: Using Patrol with Flutter 3.24.0

​Patrol Dependencies

​Version Announcements

​Migration Guides

Migrate to v4

Native to Platform API

From integration_test

Changelog

​Need Help?

Back to Getting Started

Build docs developers (and LLMs) love

Current Requirements

Package Compatibility Matrix

Platform Support

Android

iOS

macOS

Web

Checking Your Versions

Updating Patrol

Troubleshooting Version Issues

Using Older Versions

Example: Using Patrol with Flutter 3.24.0

Patrol Dependencies

Version Announcements

Migration Guides

Need Help?