Patrol

Patrol is a multiplatform E2E (End-to-End) UI testing framework for Flutter applications. It is designed to overcome the limitations of the standard integration_test plugin by providing native platform interaction capabilities.

Key features include:

• Native Access: Interact with permission dialogs, notifications, WebViews, and device settings (like Wi-Fi) using plain Dart code.
• Improved Test Writing: Uses a custom finder system for more readable code and supports Hot Restart for faster development cycles.
• Production-Ready Features: Provides full test isolation between tests, sharding support, and real-time console logs during execution.
• Device Farm Compatibility: Works with major providers such as Firebase Test Lab, BrowserStack, LambdaTest, Marathon, emulator.wtf, and AWS Device Farm.

Patrol MCP is a Model Context Protocol (MCP) server designed to enable AI assistants (such as Claude, Cursor, Copilot, and Gemini) to interact directly with your Flutter projects via Patrol.

When integrated, an AI assistant can perform the following tasks:

• Run and re-run specific Patrol tests.
• Capture screenshots using auto-detected platforms.
• Read the native UI tree during active test sessions to understand the state of the application.

Patrol supports the following platforms:

• Android: version 5.0 (API 21) and newer.
• iOS: version 13 and newer.
• macOS: version 10.14 and newer (currently in alpha support).

Note on devices: On mobile platforms (Android and iOS), Patrol works on both physical devices and virtual devices (emulators/simulators).

Unsupported platforms:

• Windows
• Linux

Patrol MCP (Model Context Protocol) is an optional extension that allows an AI agent to interact with your testing environment. When set up, an AI agent can:

• Run tests.
• Capture screenshots.
• Read the native UI tree.
• Drive an interactive session.

For setup instructions, refer to the package on pub.dev: https://pub.dev/packages/patrol_mcp

Patrol uses a logical expression syntax for filtering tests via the CLI.

Constraints:

• Tags must be valid Dart identifiers (though hyphens are permitted).
• Expressions can be grouped using parentheses () to control operator precedence.

The native2 API allows you to perform native automation using platform-specific selectors within a single method call. This solves the issue where Android and iOS require different identification arguments (e.g., Android's resourceName vs iOS's label or identifier).

Instead of using flaky text-based selectors or writing manual if (Platform.isAndroid) checks, you use a NativeSelector that contains both android and ios configurations.

// Single method call with platform-specific selectors
await $.native2.tap(
  NativeSelector(
    android: AndroidSelector(
      resourceName: 'com.android.camera2:id/shutter_button',
    ),
    ios: IOSSelector(label: 'Take Picture'),
  ),
);

Patrol tests should be organized using a Module pattern to encapsulate feature-specific interactions. A Module is a class that extends Module and receives the PatrolIntegrationTester (represented by $ in examples) via its constructor. This allows you to group related actions (like navigation or searching) into reusable methods that use keys to find elements.

To manage multiple modules, use a Modules aggregator class that holds instances of your feature modules, initialized with the tester instance.

import 'package:patrol/patrol.dart';

// Feature module implementation
final class Home extends Module {
  Home(super.$);

  Future<void> navigateToSettings() async {
    await $(keys.home.settingsButton).scrollTo().tap();
  }
}

// Modules aggregator
final class Modules {
  Modules(this._$);
  final PatrolIntegrationTester _$;

  late final home = Home(_$);
}