patrol test

The patrol test command is the primary way to run your integration tests. It builds your app, installs it on the target device, and executes tests using native test runners.

Synopsis

patrol test [options]

Description

This command performs the following steps:

Bundles tests - Creates a single test bundle from all test files
Builds apps - Compiles both the app under test and instrumentation app
Installs apps - Deploys to the selected device or simulator
Runs tests - Executes tests natively via Gradle (Android) or xcodebuild (iOS)
Reports results - Displays test output in native format

By default, patrol test runs all test files ending with _test.dart in the patrol_test directory.

Basic Usage

Run all tests

patrol test

Run a specific test file

patrol test --target patrol_test/login_test.dart

Run multiple test files

patrol test \
  --target patrol_test/login_test.dart \
  --target patrol_test/signup_test.dart

Or using comma-separated values:

patrol test --targets patrol_test/login_test.dart,patrol_test/signup_test.dart

There’s no difference between --target and --targets. Use whichever feels more natural.

Test Selection

Target Options

--target

string

default:"all tests"

Specify integration test file(s) to run. Can be used multiple times.

patrol test --target patrol_test/app_test.dart

--exclude

string

Exclude specific test files from execution.

patrol test --exclude patrol_test/flaky_test.dart

Device Selection

--device

string

default:"first device"

Specify which device to run tests on. Accepts device ID, emulator name, or “all”.

patrol test --device emulator-5554
patrol test --device "iPhone 15 Pro"

To see available devices:

patrol devices

Build Configuration

Build Mode

--debug

flag

default:"true"

Build in debug mode (default).

patrol test --debug

--profile

flag

Build in profile mode for performance testing.

patrol test --profile

--release

flag

Build in release mode. Required for physical iOS devices on device farms.

patrol test --release

Only one build mode can be specified at a time.

Flavors

--flavor

string

Build a specific flavor of your app.

patrol test --flavor staging
patrol test --flavor production --release

Flavors are not supported on the web platform.

Build Versioning

--build-name

string

Set the version name (e.g., “1.2.3”).

patrol test --build-name 1.2.3

--build-number

string

Set the version code (e.g., “123”).

patrol test --build-number 123

Dart Defines

--dart-define

string

Pass environment variables to your app. Can be used multiple times.

patrol test --dart-define API_URL=https://api.example.com
patrol test \
  --dart-define API_KEY=secret123 \
  --dart-define ENV=staging

--dart-define-from-file

string

Load environment variables from a file.

patrol test --dart-define-from-file config/test.json

Platform-Specific Options

Android

--package-name

string

Override the Android package name.

patrol test --package-name com.example.myapp

iOS

--bundle-id

string

Override the iOS bundle identifier.

patrol test --bundle-id com.example.MyApp

--ios

string

default:"latest"

Specify iOS version for simulators.

patrol test --ios 17.5

--full-isolation

flag

Uninstall the app between test runs on iOS Simulator for full isolation.

patrol test --full-isolation

The --full-isolation flag is experimental and might be removed in future releases.

--clear-permissions

flag

Clear permissions before running each test on iOS.

patrol test --clear-permissions

Coverage

--coverage

flag

Collect code coverage during test execution.

patrol test --coverage

The LCOV report will be saved to coverage/patrol_lcov.info.

Coverage collection is currently not supported on macOS.

--coverage-ignore

string

Exclude files from coverage using glob patterns.

patrol test --coverage --coverage-ignore "**/*.g.dart"
patrol test --coverage --coverage-ignore "**/*.freezed.dart" --coverage-ignore "**/*.gr.dart"

--coverage-package

string

Specify package name regex for coverage (defaults to current package).

patrol test --coverage --coverage-package "my_package"

Test Execution Options

--uninstall

flag

default:"true"

Uninstall the app before and after testing.

patrol test --uninstall
patrol test --no-uninstall

--show-flutter-logs

flag

default:"false"

Display Flutter framework logs during test execution.

patrol test --show-flutter-logs

--hide-test-steps

flag

default:"false"

Hide individual test steps from output.

patrol test --hide-test-steps

--clear-test-steps

flag

default:"true"

Clear test steps after each test completes.

patrol test --clear-test-steps

--label

flag

default:"true"

Display label overlay on the app during testing.

patrol test --label
patrol test --no-label

Web Platform

Patrol supports running tests on Flutter web using Playwright:

patrol test --device chrome

When running on web:

Tests execute in Chromium browser via Playwright
Test results are generated in test-results/
Configure Playwright using web-specific flags

Web-Specific Options

--web-reporter

string

Playwright reporters to use (JSON array).

patrol test --device chrome --web-reporter '["html", "json"]'

--web-retries

number

Number of times to retry failed tests.

patrol test --device chrome --web-retries 2

--web-workers

number

Maximum number of parallel workers.

patrol test --device chrome --web-workers 4

--web-timeout

number

Test timeout in milliseconds.

patrol test --device chrome --web-timeout 60000

--web-headless

string

Run browser in headless mode.

patrol test --device chrome --web-headless true

--web-video

string

Video recording mode: off, on, retain-on-failure, on-first-retry.

patrol test --device chrome --web-video retain-on-failure

Web tests don’t support --flavor, --uninstall, --clear-permissions, or --full-isolation flags.

Advanced Options

--test-server-port

number

default:"8081"

Port for the test instrumentation server.

patrol test --test-server-port 9001

--app-server-port

number

default:"8082"

Port for the app under test server.

patrol test --app-server-port 9002

--check-compatibility

flag

default:"true"

Verify dependency compatibility before running tests.

patrol test --no-check-compatibility

--generate-bundle

flag

default:"true"

Generate test bundle file.

patrol test --no-generate-bundle

--no-tree-shake-icons

flag

Disable icon tree shaking during build.

patrol test --no-tree-shake-icons

Examples

# Run all tests
patrol test

# Run specific test
patrol test --target patrol_test/login_test.dart

Output

The command outputs test results in native format:

✓ patrol_test/login_test.dart (5.2s)
  ✓ user can log in (3.1s)
  ✓ invalid credentials show error (2.1s)
  
✓ patrol_test/signup_test.dart (4.8s)
  ✓ user can create account (4.8s)
  
All tests passed! (10.0s)

Under the Hood

patrol test essentially calls patrol build and then runs the built app binaries. It leverages:

Gradle and Android Test Orchestrator on Android
xcodebuild and XCTest on iOS/macOS
Playwright on web

This provides deep native integration and proper test reporting.

Troubleshooting

Build Failures

If the build fails:

Ensure you’ve completed native setup
Check that your Flutter and Dart versions are compatible
Run patrol doctor to verify your environment
Try cleaning: flutter clean && flutter pub get

Test Failures

If tests fail unexpectedly:

Use --show-flutter-logs to see detailed logs
Check device logs with flutter logs
Verify network connectivity for API calls
Ensure proper test isolation (use --full-isolation on iOS)

Port Conflicts

If you see port conflict errors:

patrol test --test-server-port 9001 --app-server-port 9002

patrol develop - Develop tests with Hot Restart
patrol build - Build test binaries without running
patrol devices - List available devices

Commands

Synopsis

Description

Basic Usage

Run all tests

Run a specific test file

Run multiple test files

Test Selection

Target Options

Tags

Device Selection

Build Configuration

Build Mode

Flavors

Build Versioning

Dart Defines

Platform-Specific Options

Android

iOS

Coverage

Test Execution Options

Web Platform

Web-Specific Options

Advanced Options

Examples

Output

Under the Hood

Troubleshooting

Build Failures

Test Failures

Port Conflicts

Build docs developers (and LLMs) love

Commands

​Synopsis

​Description

​Basic Usage

​Run all tests

​Run a specific test file

​Run multiple test files

​Test Selection

​Target Options

​Tags

​Device Selection

​Build Configuration

​Build Mode

​Flavors

​Build Versioning

​Dart Defines

​Platform-Specific Options

​Android

​iOS

​Coverage

​Test Execution Options

​Web Platform

​Web-Specific Options

​Advanced Options

​Examples

​Output

​Under the Hood

​Troubleshooting

​Build Failures

​Test Failures

​Port Conflicts

​Related Commands

Build docs developers (and LLMs) love

Synopsis

Description

Basic Usage

Run all tests

Run a specific test file

Run multiple test files

Test Selection

Target Options

Tags

Device Selection

Build Configuration

Build Mode

Flavors

Build Versioning

Dart Defines

Platform-Specific Options

Android

iOS

Coverage

Test Execution Options

Web Platform

Web-Specific Options

Advanced Options

Examples

Output

Under the Hood

Troubleshooting

Build Failures

Test Failures

Port Conflicts

Related Commands