Skip to main content
Patrol CLI is a powerful command-line tool for running Flutter integration tests on Android, iOS, macOS, and web platforms. It provides advanced features like Hot Restart for rapid test development, comprehensive test bundling, and native test execution.

​
Installation

Install Patrol CLI globally using Dart’s pub: 
dart pub global activate patrol_cli
Verify the installation: 
patrol --version
Make sure the Dart pub global bin directory is in your PATH. On macOS/Linux, this is typically ~/.pub-cache/bin.

​
Quick Start

After installing the CLI, you can start using Patrol in your Flutter project:
1

Add Patrol to your project

Add the required dependencies to your pubspec.yaml:
dev_dependencies:
  patrol: ^3.0.0
  patrol_finders: ^2.0.0
2

Complete native setup

Follow the native setup guide to configure Android and iOS.
3

Write your first test

Create a test file in patrol_test/app_test.dart:
import 'package:patrol/patrol.dart';

void main() {
  patrol('counter app test', (\$) async {
    await \$.pumpWidgetAndSettle(MyApp());
    await \$(FloatingActionButton).tap();
    expect(\$(#counterText).text, '1');
  });
}
4

Run your tests

Execute your tests with Patrol CLI:
patrol test

​
Core Commands

Patrol CLI provides several commands to help you throughout the testing lifecycle:

​
Testing Commands

​
Utility Commands

​
Key Features

​
Advanced Test Bundling

Patrol automatically bundles all your tests into a single app binary, which means:
  • Only one build is required for all tests
  • Faster CI/CD pipelines
  • Better isolation between test runs
  • Support for parallel test execution

​
Hot Restart Support

With patrol develop, you can iterate quickly on your tests:
  • No need to rebuild after code changes
  • Press ‘R’ to restart tests instantly
  • Works on Android and iOS simulators

​
Multi-Platform Support

Run your tests across platforms:
  • Android devices and emulators
  • iOS devices and simulators
  • macOS desktop
  • Web browsers (via Playwright)

​
Native Integration

Patrol deeply integrates with native testing frameworks:
  • Uses Gradle and Android Test Orchestrator on Android
  • Uses XCTest and xcodebuild on iOS
  • Proper native test output and reporting

​
Common Workflows

​
Running all tests

patrol test

​
Running a specific test file

patrol test --target patrol_test/login_test.dart

​
Running tests with tags

patrol test --tags "smoke && !flaky"

​
Developing with Hot Restart

patrol develop --target patrol_test/login_test.dart

​
Building for CI/CD

patrol build android --release
patrol build ios --release

​
Getting Help

For detailed information about any command, use the --help flag: 
patrol --help
patrol test --help
patrol build android --help

​
Environment Configuration

​
Flutter Command

By default, Patrol uses the flutter command from your PATH. You can customize this: 
# Using environment variable
export PATROL_FLUTTER_COMMAND="fvm flutter"
patrol test

# Using command-line flag
patrol test --flutter-command "fvm flutter"

​
Configuration in pubspec.yaml

You can configure Patrol’s behavior in your pubspec.yaml: 
patrol:
  app_name: MyApp
  test_directory: patrol_test
  android:
    package_name: com.example.myapp
  ios:
    bundle_id: com.example.MyApp

​
Next Steps

Test Command

Learn how to run tests with patrol test

Develop Command

Speed up test development with Hot Restart

Build Command

Build test binaries for CI/CD

Full Documentation

Read the complete Patrol documentation

​
Troubleshooting

If you encounter issues:
  1. Run patrol doctor to check your environment
  2. Check the documentation for setup guides
  3. Search or create issues on GitHub
  4. Join the discussion on Discord
Make sure you’ve completed the native setup before running tests. Patrol requires native configuration for Android and iOS.

Build docs developers (and LLMs) love

Get started for freeTalk to us