leancodepl/patrol

Patrol is a cross-platform integration testing framework for Flutter that automates end-to-end interactions with native device features and UI elements across Android, iOS, macOS, and web. It provides a schema-driven code generation system to create type-safe contracts for communicating between Dart tests and native platform servers, enabling precise control over system settings, permissions, and hardware capabilities. The system includes a dedicated CLI for orchestrating test execution, video recording, and coverage collection, alongside a DevTools extension for inspecting native view hierarchies and an MCP server for AI-driven automation.

85 changes.

The project underwent a major architectural shift, migrating from a legacy monolithic structure to a modular monorepo with dedicated packages for CLI, finders, and native automation. This period focused on rebuilding the core infrastructure, including a schema-driven code generation engine and a rewritten Android server, while establishing comprehensive test coverage and cross-platform support for iOS, macOS, and web.

46 changes.

This period focused on expanding the framework to support Flutter web testing, including a new Playwright-based runner, multi-tab management, and web coverage collection. It also introduced the patrol\_mcp package to enable AI-driven test automation via the Model Context Protocol, alongside significant refactoring of native automators and logging infrastructure.

A new DevTools service extension has been added to allow users to fetch the native UI tree for both Android and iOS platforms. This feature enables deeper inspection of native views within the DevTools interface, supporting cross-platform debugging by exposing platform-specific UI hierarchies.

_packages/patrol/lib/src/devtools\_service\extensions · high confidence

The generator now produces Swift source files for Darwin platforms, including shared data contracts, HTTP server implementations using the Telegraph framework, and client implementations using URLSession. This enables developers to generate type-safe Swift code for their service schemas, supporting both server-side routing and client-side API calls on iOS and macOS.

_packages/patrol\gen/lib/src/generators/darwin · high confidence

The Patrol iOS implementation now includes a PrivacyInfo.xcprivacy manifest declaring no collected data types, alongside new localized string resources for German, English, French, Japanese, Korean, and Polish. These strings cover permission dialog buttons (e.g., Allow, Limit Access), settings navigation labels (e.g., Dark Appearance, Display & Brightness), location precision toggles, and gallery/uninstall actions, ensuring native OS interaction prompts appear in the user's preferred language.

packages/patrol/darwin/patrol/Sources/PatrolImpl/Resources · high confidence

The e2e\_app now includes a native macOS runner, enabling end-to-end testing on macOS. This change introduces the necessary macOS-specific configuration files, including an AppDelegate, Info.plist with URL scheme support for Patrol, and entitlements for sandboxing, JIT, and network access. The app bundle identifier has been updated to pl.leancode.patrol.macos.example, and the entry point has been adjusted to use the modern FlutterViewController initializer.

_dev/e2e\_app/macos/Flutter, dev/e2e\app/macos/Runner · high confidence

The Patrol iOS implementation now includes an Objective-C compatible client (ObjCPatrolAppServiceClient) that exposes Dart test listing and execution capabilities to native code, handling port configuration via environment variables. Additionally, a new PatrolTestManifest class allows reading a build-time generated test manifest file, enabling static test discovery that mirrors runtime behavior, which supports faster test execution and integration with tools like Marathon.

packages/patrol/darwin/patrol/Sources/PatrolImpl · high confidence

The e2e\_app iOS project now includes explicit Xcode scheme files (Runner.xcscheme and RunnerTests.xcscheme) in the xcshareddata directory. These schemes configure the build, test, and launch actions for the main Runner app and its UI tests, including the necessary pre-actions to prepare the Flutter framework and specific debugger settings, enabling direct building and testing of the example app within Xcode.

_dev/e2e\app/ios/Runner.xcodeproj/xcshareddata · high confidence

The example application now includes an AuthCubit that manages user authentication state using Firebase Auth and Google Sign-In. This component handles signing in with Google credentials, signing out, and emitting state changes (loading, authenticated, unauthenticated) to the UI, enabling the example app to demonstrate authenticated flows.

packages/patrol/example/lib/cubit · high confidence

The example application now includes dedicated screens to demonstrate and test various UI states: a loading screen that simulates a delayed state change, an overlay screen with stacked widgets, and a scrolling screen with specific keys for text elements. These additions provide concrete examples for users to verify finder behavior in common scenarios like overlays, scrolling lists, and asynchronous UI updates.

_packages/patrol\finders/example/lib · high confidence

An example Dart script has been added to the ADB package's binary directory, demonstrating how to initialize the ADB client and install an APK from a specified local path.

packages/adb/bin · high confidence

The e2e\app now includes a dedicated macOS platform setup. A new Matchfile has been added to configure code signing via a git-based storage mode using an SSH URL for the certificates repository, targeting the 'pl.leancode.patrol.\' app identifier. Additionally, the .gitignore file has been moved to this location and updated to exclude generated Flutter plugin registrant files.

_dev/e2e\app/macos · high confidence

The example application now includes the necessary macOS project files, enabling it to be built and run on macOS. This change adds the Flutter configuration files for debug and release builds, as well as the Xcode workspace structure that references the main project and CocoaPods dependencies.

packages/patrol/example/macos/Flutter, packages/patrol/example/macos/Runner.xcworkspace · high confidence

The Patrol example application now includes a native macOS target, allowing users to build and run the app on macOS. This change introduces the necessary Xcode project configuration, including build phases, entitlements, and CocoaPods integration, and configures the Xcode scheme to automatically include the RunnerUITests test bundle during the build process.

packages/patrol/example/macos/Runner.xcodeproj · high confidence

The example application now includes a native macOS Runner target, enabling users to build, run, and test the app on macOS. This change adds the necessary project configuration files, including the app icon set, main menu interface, build configurations (Debug/Release), entitlements for sandboxing and network access, and the Swift window and application delegate implementations.

packages/patrol/example/macos/Runner · high confidence

The example application now includes dedicated handlers for managing local and push notifications as well as runtime permissions. A new \NotificationHandler\ class initializes Firebase Cloud Messaging and local notification plugins, requests necessary permissions, and supports triggering both local alerts and remote push notifications via an HTTP endpoint. A companion \PermissionHandler\ class abstracts the logic for requesting and checking notification permissions, ensuring the app can properly handle user consent before attempting to display alerts.

packages/patrol/example/lib/handlers · high confidence

The Android automator server contracts have been defined in \AndroidAutomatorServer.kt\ and \MobileAutomatorServer.kt\, establishing the HTTP routes and request/response structures for device interaction. This includes endpoints for UI actions (tap, swipe, enter text), system controls (location, dark mode, connectivity), and new capabilities such as \sendKeyboardEnter\ and \stopMockLocation\, enabling the test framework to execute these commands on Android devices.

packages/patrol/android/src/main/kotlin/pl/leancode/patrol/contracts · high confidence

The Android test backend now supports build-time test discovery and static JUnit code generation, which creates a native test class for each Dart test file to enable per-test selection and cleaner report names. It also introduces Android-specific video recording for individual test cases, capturing screen recordings via ADB and pulling them to the local output directory upon test completion.

_packages/patrol\cli/lib/src/android · high confidence

The patrol\_gen tool now includes a Dart generator that produces Dart code from the service schema. This adds support for generating strongly-typed HTTP client classes (using the \http\ package) and Shelf-based server handler classes, alongside shared data contracts (enums and messages) that utilize \equatable\ for value equality and \json\_annotation\ for serialization. Users can now automatically generate the boilerplate required to interact with or implement Patrol services in Dart.

_packages/patrol\gen/lib/src/generators/dart · high confidence

The macOS configuration for the e2e\_app has been updated to support end-to-end testing using the Patrol framework. This change introduces a new RunnerUITests target that integrates with CocoaPods (adding Pods frameworks and build phases) and configures the necessary network entitlements for both debug and release builds, allowing the e2e tests to run on macOS.

_dev/e2e\app/macos/Runner.xcodeproj · high confidence

The Patrol example app has been updated to include Firebase capabilities, allowing users to test features like Google Sign-In and push notifications. This change introduces a new \firebase\_options.dart\ file for platform-specific Firebase configuration and updates \main.dart\ to conditionally initialize Firebase services based on the \FIREBASE\_ENABLED\ environment flag. Additionally, new UI pages have been added: a profile page that displays user information and triggers push notifications, and a notification success page that displays location data and confetti animations, providing a more comprehensive testing ground for mobile automation scenarios.

packages/patrol/example/lib · high confidence

The Darwin implementation now includes a bundled C-based HTTP parser (v2.9.4) and the Telegraph networking library, providing native HTTP and WebSocket client capabilities. This adds support for establishing WebSocket connections, handling HTTP request/response cycles, and managing network configuration directly within the patrol agent, enabling more robust communication with test servers on iOS, macOS, and other Apple platforms.

packages/patrol/darwin/patrol/Sources/HTTPParserC, packages/patrol/darwin/patrol/Sources/PatrolImpl/Telegraph · high confidence

Added Appfile and Fastfile to the macOS end-to-end app directory to automate code signing on CI. The configuration defines the macOS platform, retrieves App Store Connect API credentials and Match private keys from environment variables, and sets up a certificates lane that provisions development certificates and updates code signing settings for the Runner and RunnerUITests targets.

_dev/e2e\_app/ios/fastlane, dev/e2e\app/macos/fastlane · high confidence

The example application for the patrol\_finders package has been initialized with standard Flutter project configuration files. This includes a .gitignore file tailored for Flutter/Dart development, a .metadata file tracking the stable Flutter channel revision, an analysis\_options.yaml file integrating the leancode\_lint package with specific linter rules, and a README.md explaining the app's purpose as a demonstration for writing tests using patrol\_finders.

_packages/patrol\finders/example · high confidence

Added a new \MacOSTestBackend\ class that enables running Flutter UI tests on macOS. This implementation handles the build process using \xcodebuild build-for-testing\ and executes tests via \xcodebuild test-without-building\, passing the patrol server ports through environment variables (\TEST\_RUNNER\_PATROL\_TEST\_PORT\, \TEST\_RUNNER\_PATROL\_APP\_PORT\) to facilitate communication between the test runner and the app.

_packages/patrol\cli/lib/src/macos · high confidence

Establishes the foundational structure for the Patrol framework, introducing a schema-driven approach for native interactions. This includes the \schema.dart\ definition for cross-platform contracts, a \gen\_from\_schema\ script to generate Dart, Swift, and Kotlin code, and the initial \melos.yaml\ monorepo configuration. The entry also adds essential repository metadata such as the Apache 2.0 license, contributing guidelines, and code ownership rules.

(repo-wide) · high confidence

The \patrol\_log\ package is introduced as a standalone library for logging in the Patrol Flutter testing framework. This release establishes the core public API, exporting the main \PatrolLogWriter\ and \PatrolLogReader\ (via a separate barrel file to isolate \dart:io\ dependencies), along with entry models and ANSI code utilities. The package is licensed under Apache 2.0 and includes standard configuration files for linting and analysis.

_packages/patrol\log · high confidence

The \packages/adb/lib\ directory now contains the main entry point for the ADB package, exposing core ADB functionality and exception classes to consumers.

packages/adb/lib · high confidence

This change introduces the core Dart interface for the Android Debug Bridge (ADB) in the \packages/adb/lib/src\ directory. It provides an \Adb\ class that allows users to initialize the ADB daemon, install and uninstall APKs on attached devices, pull files, remove files, and manage port forwarding (including a cancel function for forwarded ports). The implementation includes robust error handling via specific exceptions (such as \AdbExecutableNotFound\ and \AdbDaemonNotRunning\) and ensures that required ADB services (package and activity) are running before performing installation or uninstallation tasks.

packages/adb/lib/src · high confidence

This change introduces the \patrol\_devtools\_extension\ as a standalone package, providing a DevTools extension for the Patrol integration testing framework. The package includes the necessary web assets (HTML, manifest), build configuration (build.yaml, analysis\_options.yaml), and a local development script to build and copy the extension into the main Patrol package. It also establishes the initial changelog and metadata, setting the baseline version at 0.4.1 with dependencies on \equatable\, \leancode\_lint\, and specific Dart/Flutter SDK versions.

_packages/patrol\_devtools\extension · high confidence

The \patrol\_mcp\ package now provides a Model Context Protocol (MCP) server that enables external tools to manage Flutter test sessions and interact with attached devices. This includes auto-detecting and listing attached Android and iOS devices, resolving the correct Flutter command (with FVM support), and managing the lifecycle of \patrol develop\ sessions. Users can now capture screenshots (with PNG validation and resizing) and retrieve the native UI tree for automation purposes. The server also handles log streaming to a local file and ensures robust session teardown, allowing MCP clients to programmatically drive and inspect Patrol test runs.

_packages/patrol\mcp/lib · high confidence

The DevTools extension now exposes a dedicated \PatrolServiceExtensionApi\ class that communicates with the Flutter isolate via service extensions (e.g., \ext.flutter.patrol.getNativeUITree\). This API wraps responses in a typed \ApiResult\ union (\ApiSuccess\/\ApiFailure\) and deserializes data using newly generated JSON contracts (\contracts.dart\/\contracts.g.dart\) and native view models (\native\_views.dart\). This provides a structured, type-safe interface for the DevTools UI to query native UI trees and other patrol capabilities, replacing ad-hoc communication patterns.

_packages/patrol\_devtools\extension/lib/api · high confidence

The Patrol library now exposes a \patrolNativeServerUri\ getter in the \patrol\_extension.dart\ module, providing a standardized URI for the native automation server (defaulting to localhost:8081). This change enables optional Patrol extension packages, such as \patrol\_axe\, to send custom native requests to the same server that backs core mobile automation, ensuring that port-forwarding and host resolution via environment variables (\PATROL\_HOST\, \PATROL\_TEST\_SERVER\_PORT\) work seamlessly for third-party integrations.

packages/patrol/lib · high confidence

The web runner location now includes a full Playwright test infrastructure, featuring a main configuration file that exposes numerous environment variables (such as PATROL\_WEB\_RETRIES, PATROL\_WEB\_TIMEOUT, PATROL\_WEB\_VIDEO, PATROL\_WEB\_GEOLOCATION, and PATROL\_WEB\_REPORTER) to control browser launch options, test execution settings, and reporting formats. Separate configuration files are provided for unit and integration tests to isolate test directories and matchers, alongside standard development tooling configurations for TypeScript, ESLint, Prettier, and Node version management.

_packages/patrol/web\runner · high confidence

A new executable entry point has been added to the patrol\_gen package, allowing users to generate platform-specific code (Dart, iOS/macOS, and Android) from a schema file via the command line. The tool accepts arguments for the schema path and output directories for each target platform, orchestrating the generation process through the PatrolGen class.

_packages/patrol\gen/bin · high confidence

A new WebTestBackend class has been added to handle the lifecycle of Flutter web applications during testing. This component manages starting the Flutter web server (either in 'web-server' or 'chrome' mode), waiting for the server to become ready with a configurable timeout, executing Playwright tests against the running application, and gracefully shutting down the server process. It also supports a development mode that integrates with Flutter's hot restart capabilities and interactive stdin handling, ensuring that test runs are properly isolated and cleaned up even if errors occur.

_packages/patrol\cli/lib/src/web · high confidence

The web platform implementation now supports interacting with multiple browser tabs. The \WebAutomator\ interface has been updated to include methods for managing pages, such as \openNewPage\, \closePage\, \switchToPage\, \switchToInitialPage\, \getPages\, \getCurrentPage\, and \getCurrentPageUrl\. Additionally, a \waitForPopup\ method allows tests to wait for new pages to open. The concept of the 'main page' has been renamed to 'initial page' to better reflect its role as the starting point hosting the Flutter app, and the \switchToMainPage\ action has been added to return focus to this initial page. These changes enable tests to navigate and interact across multiple browser contexts within a single session.

packages/patrol/lib/src/platform/web · high confidence

The DevTools extension now includes a native UI inspector that allows users to view and interact with the native view hierarchy of the connected application. This feature adds a new entry point and state management logic to fetch the native UI tree via the Patrol service extension API, distinguishing between Android and iOS roots, and renders the result using a dedicated NativeInspector widget.

_packages/patrol\_devtools\extension/lib · high confidence

Added the \patrol\_mcp\ executable (version 0.2.1) which runs an MCP server to allow AI agents to control Patrol test sessions. The tool manages the project root directory, initializes a \PatrolSession\ via \patrol\_cli\, and exposes tools for running tests (\run\), capturing screenshots (\screenshot\), inspecting the native UI tree (\native-tree\), and checking status (\status\). It supports configuration via environment variables like \PROJECT\_ROOT\ and \PATROL\_FLAGS\, and handles device selection and test timeouts.

_packages/patrol\mcp/bin · high confidence

This change extracts the custom finder and tester logic into a new \patrol\_finders\ package, providing a streamlined, high-level API on top of \flutter\_test\. Users can now use \patrolWidgetTest\ to run tests with a \PatrolTester\ (exposed as \$\), which supports custom finders for types, keys, symbols, strings, patterns, icons, and widgets. The package includes configuration options for timeouts, settling policies, and logging, along with specific exceptions for visibility and existence timeouts.

_packages/patrol\finders/lib · high confidence

Patrol now supports build-time test discovery, allowing the test tree to be registered and serialized into a manifest during compilation (driven by a host \flutter test\ run) without executing test bodies, which enables faster iteration and better integration with native automation. Additionally, a new hot restart mode is introduced (enabled via the \PATROL\_HOT\_RESTART\ environment variable), allowing developers to interact with the running app using a physical finger during tests and supporting live code reloading in \patrol develop\ without terminating the test session. The implementation includes a new \PatrolBinding\ to manage test lifecycle and reporting, \patrolSetUp\/\patrolTearDown\ hooks that respect these modes, and platform-specific manifest writers to handle file I/O safely across web and VM environments.

packages/patrol/lib/src · high confidence

The CLI now supports an experimental, opt-in feature that discovers Dart tests at build time by running a host \flutter test\ in discovery mode and serializing the test tree to a manifest. This manifest is consumed by platform-specific code generators to create static native test classes (one per Dart test file) for both iOS (XCTest) and Android (JUnit), ensuring that generated native test names remain byte-identical to runtime discovery. This change enables individually selectable native tests and allows running tests without a device during the build phase, while also introducing a \VideoRecordingManager\ to capture and report test execution videos in the CLI summary.

_packages/patrol\cli/lib/src/crossplatform · high confidence

The CLI now collects usage analytics via Google Analytics, but only when explicitly enabled by the user. Analytics are disabled by default on the first run and require the user to opt-in via the configuration file. The system respects the \PATROL\_ANALYTICS\_ENABLED\ environment variable to override settings, automatically disables collection when running in a CI environment, and suppresses analytics in nested Flutter invocations to prevent recursive data sending. Events sent include the command name, Flutter version, OS details, and a unique client ID, with graceful error handling if the network request fails.

_packages/patrol\cli/lib/src/analytics · high confidence

The Patrol documentation site is now live, providing a dedicated space for user guides and setup instructions. This update introduces deep-linkable navigation that correctly handles scroll offsets for setup steps and section anchors, ensuring content remains visible below the sticky header. It also includes a new search feature powered by Orama, dynamic metadata generation for social sharing, and a persistent webinar banner. Additionally, the site now serves a full-text LLM-readable version of the documentation and includes a fix to prevent cache poisoning from internal Next.js segment paths.

_docs\app/app · high confidence

The Patrol automation server for Apple platforms has been rewritten in Swift, introducing dedicated \IOSAutomator\ and \MacOSAutomator\ implementations that handle native UI interactions such as tapping, text entry, and system controls. This change adds support for Korean (ko) language localization in native OS interactions and includes generated contract definitions for the server's API. While iOS automation is fully implemented, macOS-specific actions like pressing the home button or swiping are currently stubbed as not implemented.

packages/patrol/darwin/patrol/Sources/PatrolImpl/AutomatorServer · high confidence

Added two new rule files to guide AI-assisted coding: \.cursor/rules/android-kotlin.mdc\ enforces centralizing automation constants in \AutomatorConstants.kt\ with proper KDoc and naming, and \.cursor/rules/github-workflows.mdc\ mandates updating \.github/WORKFLOWS.md\ whenever workflow files in \.github/workflows/\ are modified, and specifies exclusion patterns for physical device tests.

.cursor · high confidence

Added two new shell scripts to the tool directory to enforce quality standards in CI. check\_changelog.sh ensures that any pull request modifying source code within a package also updates that package's CHANGELOG.md, exempting tests, examples, and documentation. check\_skills.sh validates the agent-skills setup by verifying the .claude/skills symlink points correctly to .agents/skills and ensuring all SKILL.md files have valid frontmatter (name and description) that adheres to the open Agent Skills standard.

tool · high confidence

The coverage subsystem has been refactored into a modular structure with new files (bind\_unused\_port, coverage\_common, coverage\_mode, device\_to\_host\_port\_transformer, vm\_connection\_details) and a dedicated WebCoverageTool. This enables collecting coverage from web tests by mapping browser JavaScript coverage back to Dart via source maps, in addition to the existing VM-based collection for mobile. The tool now automatically finds and forwards an unused host port for device communication, resolves workspace member packages when the --coverage-workspace flag is used, and avoids collecting coverage from skipped tests to prevent duplicate entries.

_packages/patrol\cli/lib/src/coverage · high confidence

A new Flutter example application has been added to dev/e2e\_app to serve as a test harness for the Patrol framework. The app includes a comprehensive set of screens designed to exercise various native and Flutter capabilities, such as camera and gallery access, file picking, deep links, location services, local notifications, and permission handling. It also features specific UI patterns for testing Patrol's finder logic (like the at() method) and text input flows. The project is configured with Marathon for multi-device testing, includes an MCP server configuration for AI-assisted testing, and provides environment variable definition files to test build-time configuration injection.

_dev/e2e\app · high confidence

The example application now includes a new home page (home\_page.dart) that serves as the entry point for user interactions. This page provides buttons to sign in with Google, navigate to a quiz, and trigger push notifications, integrating with the app's authentication and notification handlers.

packages/patrol/example/lib/pages · high confidence

This change introduces the core mobile automation layer for Patrol. It adds the \MobileAutomator\ abstract interface and its \NativeMobileAutomator\ HTTP-based implementation, enabling programmatic control of device features such as pressing home/recent-apps buttons, opening apps, managing notifications, toggling system settings (Wi-Fi, Bluetooth, airplane mode, dark mode), and handling native permission dialogs. It also introduces \MobileAutomatorConfig\ for configuring connection timeouts and logging, and establishes a new runtime port injection mechanism (\PatrolRuntimePorts\) that reads HTTP server ports from the native side via method channels on iOS/macOS, with web stubs for compatibility. Additionally, it adds the \PatrolAppService\ HTTP server (using \http\_multi\_server\ on the loopback interface) to coordinate Dart test execution with the native runner.

packages/patrol/lib/src/platform/mobile · high confidence

A new \patrol\_cli.dart\ barrel file has been added to the \lib\ directory to expose a public API for driving a patrol develop session programmatically. This file re-exports specific types and services (such as \ConfigEntry\, \Device\, and \FlutterCommand\) from internal \src/\ paths, allowing external consumers like the patrol MCP server to access these components without importing implementation details directly.

_packages/patrol\cli/lib · high confidence

The example app now includes a complete quiz experience with dedicated pages for welcoming the user, collecting a nickname and color preferences, presenting three interactive questions, and displaying success or error states. These new UI components provide a more comprehensive demonstration of the Patrol testing framework's capabilities within the example application.

packages/patrol/example/lib/pages/quiz · high confidence

This change introduces the foundational Dart-side components for the Patrol CLI, replacing the previous implementation. It adds a PubspecReader to parse project configuration (test directories, file suffixes, native app identifiers) from pubspec.yaml, a DartDefinesReader to handle environment variables from CLI arguments and .patrol.env files, and a TestFinder to discover test files with support for custom suffixes and exclusion patterns. The TestBundler generates the Dart test entrypoint that bridges the native test runners (Android/iOS) with the Dart test framework, while the DeviceFinder manages device selection, including interactive prompts and CI-safe defaults. Finally, the TestRunner orchestrates the execution of tests across multiple targets and devices, handling build and run callbacks.

_packages/patrol\cli/lib/src · high confidence

The Xcode project for the e2e app has been updated to support Swift Package Manager by linking the FlutterGeneratedPluginSwiftPackage framework in both the main Runner and the UI test targets. Additionally, a new RunnerTests target has been added to the project structure, allowing for unit tests to be run alongside the existing UI tests (RunnerUITests).

_dev/e2e\app/ios/Runner.xcodeproj · high confidence

The iOS test backend now includes built-in video recording support for iOS simulators (using xcrun simctl) and a new static test code generation system that creates native XCTest classes from a build-time manifest, replacing the previous runtime discovery mechanism. This change improves test reliability by handling simulator recording state and enables better integration with Xcode's test navigator and sharding features.

_packages/patrol\cli/lib/src/ios · high confidence

The example application scaffolding has been removed, deleting the core Dart entry point, platform-specific native code for Android, Linux, macOS, and Windows, and associated build configurations. This change eliminates the default counter app demo, integration tests, and web assets, effectively stripping the project of its runnable example implementation.

example, example/android · high confidence

The \maestro\ package has been deleted and its contents removed from the \maestro/lib\ directory. This change eliminates the legacy command-line interface entry point (\maestro/bin/maestro.dart\) and the core implementation files (\automator.dart\, \flutter\_driver.dart\, \adb.dart\, and \version.dart\) that previously handled device instrumentation, port forwarding, and Flutter driver execution. Users relying on this specific package structure will need to migrate to the new location where the package was split and moved to \packages/\.

maestro/lib · high confidence

The AutomatorServer app module has been stripped of its default Android application structure, including the AndroidManifest, UI themes, launcher icons, ProGuard rules, and the Gradle wrapper scripts. Additionally, the instrumentation test classes and their associated build output logs have been deleted, indicating the server is no longer packaged or tested as a standalone Android application in this location.

AutomatorServer/app · high confidence

The iOS development environment for the e2e app now includes a Matchfile that configures code-signing certificate management via a Git repository ([e-mail redacted]:leancodepl/certificates.git) using wildcard app identifiers (pl.leancode.patrol.\*). Additionally, a .gitignore file was added to exclude Xcode build artifacts, derived data, Pods, and Flutter ephemeral files from version control, ensuring a cleaner repository state.

_dev/e2e\app/ios · high confidence

The Android automation layer has been reorganized into a new set of core components, introducing a dedicated \Automator\ class that manages UI interactions, timeouts, and native screenshot capture (including scoped-storage handling for API 29+). A new \PatrolServerExtension\ interface with \ServiceLoader\ discovery enables optional packages (like \patrol\_axe\) to mount custom HTTP routes on the automation server without modifying core code. To support cloud testing environments like BrowserStack and LambdaTest, new \BrowserstackPatrolJUnitRunner\ and \LambdaTestPatrolJUnitRunner\ classes implement a loopback-address workaround when the default localhost connection fails. The runner also now supports build-time test discovery via \PatrolGeneratedTests\, allowing generated test classes to stand in for the host runner. Additionally, \UITreeUtils\ provides a new method to extract the native Android view hierarchy via \AccessibilityNodeInfo\, and \Localization.kt\ adds support for retrieving UI strings in English, German, French, Polish, Japanese, and Korean based on the device's system language.

packages/patrol/android/src/main/kotlin/pl/leancode/patrol · high confidence

The Android automation logic has been restructured to separate the public API from the native HTTP client implementation. A new \AndroidAutomator\ abstract interface defines the contract for actions like opening apps, pressing buttons, and interacting with notifications, while \AndroidAutomatorNative\ provides the actual HTTP-based communication with the device. An empty stub implementation is now provided for unsupported platforms to prevent runtime errors. Additionally, the \AndroidAutomatorConfig\ now exposes a \dontSuppressAccessibilityServices\ setting (defaulting to true) to allow third-party accessibility services to remain active during tests, addressing compatibility issues with tools like screen readers.

packages/patrol/lib/src/platform/android · high confidence

The \patrol\_gen\ tool for Android now generates a complete set of Kotlin artifacts from the schema: a shared \Contracts.kt\ file containing data classes and enums, Ktor-based client implementations for each service, and HTTP4k-based server interfaces with routing logic. This replaces previous Android generation approaches, introducing a standardized client-server communication layer using Gson for serialization and Ktor's CIO engine for the client side.

_packages/patrol\gen/lib/src/generators/android · high confidence

The Android setup for the e2e\_app example has been updated to use Kotlin DSL syntax and includes a new AndroidManifest.xml that declares permissions for location, camera, audio, contacts, notifications, and other features required for end-to-end testing. The manifest also configures deep link support via the 'patrol' scheme and registers receivers for scheduled notifications, ensuring the example app can properly handle the various system interactions tested by the e2e suite.

_dev/e2e\_app/android, dev/e2e\app/ios/Runner · medium confidence

The Android automation server has been rewritten to use the HTTP4k framework for handling incoming requests, replacing the previous HTTP server implementation. This change introduces a new \AutomatorServer\ class that routes commands via HTTP4k and updates the \PatrolAppServiceClient\ to use Ktor with Gson serialization for outbound communication, ensuring consistent contract handling across the platform.

android · high confidence

The \.claude/skills\ path is now a symbolic link pointing to \../.agents/skills\, establishing the location where the agent retrieves its skill definitions.

.claude · high confidence

Setup steps and sections in the documentation are now deep-linkable via URL fragments. When a user navigates to a specific step or section (e.g., \#ios-setup), the page automatically scrolls to that target, ensuring it appears below the sticky header and promo banner rather than being hidden behind them. This is achieved by replacing native browser scrolling with custom logic that respects CSS-defined margins, and by controlling the accordion state to open the relevant section before scrolling. A copy-link button is also added to each step for easy sharing.

_docs\app/components · high confidence

The \NativeAutomator\ and \NativeAutomator2\ classes in the native automation layer are now deprecated and will be removed in a future release. Users should migrate to \PlatformAutomator\ for interacting with the OS. The \NativeAutomatorConfig\ is also deprecated, retained only for backward compatibility with \patrolTest\, and explicitly throws errors if legacy \host\ or \port\ parameters are provided. The \NativeView\ class now provides a unified representation of native UI elements across Android and iOS, mapping platform-specific properties (like Android's \className\ and iOS's \elementType\) to common fields.

packages/patrol/lib/src/native · high confidence

The macOS example app's UI test target now includes the necessary network client and server entitlements, allowing tests to communicate with the application. Additionally, the test implementation has been updated to import the Patrol plugin and utilize the new \PATROL\_INTEGRATION\_TEST\_MACOS\_RUNNER\ macro, ensuring the tests are properly initialized and integrated with the framework.

packages/patrol/example/macos/RunnerUITests · high confidence

The CLI now validates that the installed \patrol\_cli\ version is compatible with the \patrol\ package version in your project before running tests or builds. If a mismatch is detected, the process fails with a clear error message and provides specific resolution steps, such as downgrading \patrol\_cli\ to a compatible version or upgrading both packages. This check also includes a compatibility table generator to keep documentation in sync with the supported version ranges.

_packages/patrol\_cli/lib/src/compatibility\checker · high confidence

The Android configuration for the patrol\_finders example app has been updated to use Gradle 8.12 and migrated to the Flutter V2 embedding. This includes adding the INTERNET permission, updating the MainActivity to extend FlutterActivity, and applying standard V2 theme and launch background resources. These changes ensure the example app builds correctly with modern Gradle and Flutter tooling.

_packages/patrol\finders/example/android · high confidence

The Android example app's source files have been reorganized under the \packages/patrol/example\ directory, including the relocation of \MainActivity.kt\ and the creation of a new \AndroidManifest.xml\ that declares location permissions. The app's visual presentation has been updated with new splash screen assets and theme styles that support dark mode and modern Android splash screen APIs, while the application label has been changed to "Patrol example".

packages/patrol/example/android/app/src · high confidence

The example application's minimum supported iOS version has been raised from 9.0 to 14.0, as reflected in the AppFrameworkInfo.plist configuration. This change ensures the app requires a more modern iOS environment to run.

_dev/e2e\app/ios/Flutter · high confidence

The example application has been regenerated and renamed to 'patrol\_challenge', serving as a quiz app for Fluttercon that utilizes flavors and Google Sign-In. The project now includes a macOS target and is configured with the 'leancode\_lint' package and 'custom\_lint' plugin for static analysis. Additionally, a .gitignore file has been added to exclude build artifacts and Patrol-specific test bundles, while the .metadata file tracks the Flutter stable channel version for migration purposes.

packages/patrol/example · high confidence

The Gradle wrapper for the e2e\_app Android project has been updated from version 6.7 to 8.14.3. This change ensures the build environment uses a modern Gradle distribution, which is necessary to support newer Android Gradle Plugin versions and Kotlin metadata parsing.

_dev/e2e\app/android/gradle, packages/patrol/example/android/gradle · high confidence

The Patrol CLI now exposes a main entry point that initializes the command runner, enabling the new \patrol test --hot-restart\ flag for faster test iteration. This change also includes a refactored command runner structure to support these capabilities.

_packages/patrol\cli/bin · medium confidence

The Patrol CLI now includes a new set of base utilities in the \lib/src/base\ directory to improve logging, process handling, and user interaction. A new \Logger\ class wraps \mason\_logger\ to provide non-animated progress tasks and consistent warning output. Process output is now decoded using \Utf8Decoder\ with \allowMalformed: true\, ensuring that malformed UTF-8 sequences in stdout/stderr do not crash the CLI. An \InteractivePrompts\ utility has been added to support menu-based selections in terminal environments. Additionally, the CLI version constant has been updated to 4.8.0.

_packages/patrol\cli/lib/src/base · high confidence

The \patrol\_gen\ package now uses a completely rewritten generation engine. This new system parses Dart source files to automatically build a schema of enums, messages, and services, supporting complex types like lists and maps. It generates platform-specific code for Dart, Android, and Darwin (iOS/macOS) targets, allowing users to define their API contracts in Dart and have the corresponding client/server stubs generated automatically.

_packages/patrol\gen/lib/src · high confidence

The patrol\_log package now includes dedicated source files for enhanced log presentation and structure: \ansi\_codes.dart\ provides a centralized class for ANSI color codes (bold, reset, and various colors) to style console output; \duration\_extension.dart\ adds a \toFormattedString()\ extension on \Duration\ for human-readable time reporting (e.g., '1h 2m 3s'); \emojis.dart\ defines static emoji constants (like ⏳, 🧪, ✅, ❌) used in log entries; \patrol\_log\_reader.dart\ and \patrol\_log\_writer.dart\ implement the core stream-based reading and writing of structured \Entry\ objects (including Test, Step, Log, Error, Warning, and Config entries) via JSON serialization; and \patrol\_single\_test\_entry.dart\ groups related entries into a single test context, tracking opening/closing test entries, status, execution time, and name with path. This refactors the internal logging mechanism to support richer, styled, and structured test output.

_packages/patrol\log/lib/src · high confidence

The documentation site has been rebuilt as a Next.js application using the Fumadocs framework, replacing the previous static site generator. This migration introduces deep-linkable setup steps via custom MDX components (SetupAccordion, Step) and a declarative page-tree system that supports custom navigation metadata (previous/next, hide flags) and extra table-of-contents entries. The new site includes embedded social media components for YouTube and X (Twitter) with theme-aware rendering, a GitHub repository info component that fetches star counts with a 12-hour cache revalidation, and a structured navigation layout with tabs for Overview, Documentation, CLI commands, Feature Guide, Articles, Pricing, and Contact. URL redirects are configured to maintain compatibility with legacy paths, and the build environment is standardized with Node 24, Tailwind CSS, and LeanCode ESLint/Prettier configurations.

_docs\app · high confidence

The Native Inspector extension has been redesigned to provide a more detailed and interactive inspection experience. The view hierarchy now supports 2D scrolling (horizontal and vertical) and includes a button to fetch the native view hierarchy when it is not initially present. Selecting a node displays platform-specific properties in the details pane: Android nodes show properties like checkable, scrollable, and bounds; iOS nodes expose element type, identifier, and value. The UI also features row highlighting on hover, rounded corners, and a snackbar notification when copying property values to the clipboard.

_packages/patrol\_devtools\_extension/lib/native\inspector · high confidence

The native iOS and macOS integration test runners have been rewritten in Objective-C to support dynamic test generation, allowing each Dart test to be executed and reported as a native XCTest result. This change introduces a new \PatrolPlugin\ (Objective-C) to expose runtime ports to Dart, replaces runtime discovery with a \PatrolExtensionRegistry\ for explicit extension registration, and provides macro-based runner templates (\PATROL\_INTEGRATION\_TEST\_IOS\_RUNNER\ and \PATROL\_INTEGRATION\_TEST\_MACOS\_RUNNER\) that developers include in their UI test targets. The module structure is now pure Objective-C to ensure compatibility with Swift Package Manager and Flutter's generated registrants, with Swift implementation details linked separately.

packages/patrol/darwin/patrol/Sources/patrol · high confidence

A new PatrolIntegrationTester class has been introduced in the custom\_finders module, extending PatrolTester to provide direct access to native platform features via platformAutomator. It includes deprecated wrappers for NativeAutomator and NativeAutomator2 for backward compatibility, a shorthand 'platform' accessor, and a 'log' method that records actions to a local PatrolLogWriter. Additionally, it offers a takeNativeScreenshot method for capturing Android-only screenshots for device farms, with errors logged rather than thrown.

_packages/patrol/lib/src/custom\finders · high confidence

The example app's UI layer has been replaced with a new set of styled components and design tokens. This includes a custom scaffold with horizontal page transitions, themed elevated and text buttons, a styled text field with error handling, and utility widgets like a top bar and logo hero. The visual design is now driven by centralized color and typography styles (PTColors, PTTextStyles) and SVG asset management, providing a consistent look and feel for the patrol\_challenge demonstration.

packages/patrol/example/lib/ui · high confidence

This change introduces a new set of extension methods in the \packages/patrol\_cli/lib/src/base/extensions\ directory to support core CLI functionality. It adds \CommandRunnerX\ to handle command usage output formatting, \CompleterExt\ for safer async completion, and \MapX\/\StringX\ for common data manipulation. Additionally, it provides \FileSystemX\ to recursively search for files in directory hierarchies and \PlatformX\ to abstract file system styles and home directory paths across Windows, macOS, and Linux, laying the groundwork for improved project structure handling and hot restart support.

_packages/patrol\cli/lib/src/base/extensions · high confidence

The iOS platform layer has been restructured with a new \IOSAutomator\ interface and its native HTTP-based implementation (\IOSAutomatorNative\), replacing the previous approach. This change introduces a dedicated \IOSAutomatorConfig\ for managing iOS-specific settings such as bundle ID, installed apps, and keyboard behavior, and provides a stub implementation for unsupported platforms. Users interacting with iOS devices will now use this new automator structure for actions like opening apps, tapping notifications, and entering text, which communicates with the native automation server over HTTP.

packages/patrol/lib/src/platform/ios · high confidence

The platform communication layer has been updated with new generated Dart contracts and HTTP clients for Android, iOS, and mobile-wide automation. Users can now interact with a broader set of device controls, including sending keyboard enter events, managing mock locations (set and stop), toggling system settings (airplane mode, Wi-Fi, cellular, Bluetooth, dark mode), and handling permission dialogs. The Android client adds methods for pressing back, double-pressing recent apps, and taking camera photos, while the iOS client includes closing heads-up notifications, tapping the back-to-previous-app button, and checking for visible permission dialogs. These changes reflect a schema update that expands the available automation capabilities across both platforms.

packages/patrol/lib/src/platform/contracts · high confidence

The platform abstraction layer has been refactored to support WebAssembly (WASM) by replacing deprecated conditional imports with \dart.library.js\_interop\. This change introduces new platform-specific entry points (\current\_io.dart\ and \current\_web.dart\) that correctly expose runtime platform flags (e.g., \isWeb\, \isAndroid\) for both native and web environments. Consequently, the \PlatformAutomator\ and selector classes (\Selector\, \PlatformSelector\, \MobileSelector\) now utilize these updated imports to instantiate the correct native automators (Android, iOS, Web) or fallback implementations, ensuring that cross-platform test registration and UI element selection function correctly in WASM targets.

packages/patrol/lib/src/platform · high confidence

The CLI's command execution layer has been restructured to improve modularity and maintainability. A new \FlutterCommand\ class was introduced to parse and represent Flutter CLI invocations, separating executable paths from their arguments. The \PatrolCommand\ abstract class now serves as a centralized registry for common CLI flags (such as \--target\, \--device\, \--verbose\, and platform-specific options), allowing individual commands to inherit these options via helper methods like \usesTargetOption()\ and \usesPortOptions()\. Additionally, the \PatrolCommandRunner\ was refactored to explicitly instantiate and wire up platform-specific test backends (Android, iOS, macOS, Web) and the test bundler, ensuring that dependencies like the \TestBundler\ and \CompatibilityChecker\ are correctly scoped and passed to the relevant commands.

_packages/patrol\cli/lib/src/runner · high confidence

The log entry system in \packages/patrol\_log/lib/src/entries\ has been refactored to use a sealed \Entry\ class hierarchy with \Equatable\ support, introducing new entry types including \ConfigEntry\ for passing test configuration and \WarningEntry\ for warnings. For users, this brings a specific behavioral improvement to \TestEntry\: the logic for detecting file prefixes in test names now strictly requires the \\_test\ suffix, which prevents the accidental truncation of the first word of a test description when the name does not actually contain a file path prefix. Additionally, error messages are now printed in red and warning messages in yellow for better visual distinction in logs.

_packages/patrol\log/lib/src/entries · high confidence

The native inspector's internal node structure has been reorganized to use platform-specific node classes (AndroidNode, IOSNode) and a unified NativeViewNode, replacing the previous implementation. This change improves how UI elements are represented in the DevTools extension by separating Android and iOS view handling logic, ensuring more accurate node naming and hierarchy traversal for both platforms.

_packages/patrol\_devtools\_extension/lib/native\inspector/nodes · high confidence

The iOS example app in the Patrol package has been regenerated to support multiple build configurations (dev and prod) via dedicated Xcode schemes, enabling distinct settings for development and production testing. The project now includes a dedicated TestPlan for UI tests, and the test runner has been updated to use the \patrol\ framework directly via \@import patrol\ in the \RunnerUITests\ target. Additionally, the app bundle name has been set to \patrol\_challenge\, and the project structure has been adjusted to reflect the new package location.

packages/patrol/example/ios · high confidence

The CLI command implementations in \packages/patrol\_cli/lib/src/commands\ have been refactored to improve modularity and support for cross-platform development. The \build\ command is now split into dedicated subcommands (\build android\, \build ios\, \build macos\), each handling platform-specific test bundling, flavor configuration, and artifact generation. The \develop\ command has been decoupled from the CLI runner into a reusable \DevelopService\ and \DevelopSessionFactory\, enabling consistent hot-restart workflows across platforms and programmatic integration via the MCP server. Additionally, new utility files like \dart\_define\_utils.dart\ and \develop\_options.dart\ centralize argument parsing and Dart define merging logic used across these commands.

_packages/patrol\cli/lib/src/commands · high confidence

The iOS example app has been relocated from the example directory to dev/e2e\_app. This move includes setting up the Xcode workspace to reference the project and its Pods, and adding a new UI test target (RunnerUITests) that integrates the Patrol framework to enable end-to-end testing of the app.

_dev/e2e\_app/ios/Runner.xcodeproj/project.xcworkspace, dev/e2e\_app/ios/Runner.xcworkspace, dev/e2e\app/ios/RunnerUITests · high confidence

The iOS example project for \patrol\_finders\ has been restructured to include dedicated \RunnerTests\ (Swift) and \RunnerUITests\ (Objective-C) targets, which are now registered in the Xcode scheme for automatic execution. The project build file has been upgraded to object version 54, and the \AppDelegate\ now initializes the \UNUserNotificationCenter\ delegate. Additionally, the \Info.plist\ has been updated to include standard permission descriptions (camera, location, contacts, microphone) and modern iOS flags like \CADisableMinimumFrameDurationOnPhone\ and \UIApplicationSupportsIndirectInputEvents\.

_packages/patrol\finders/example/ios · high confidence

Add comprehensive Patrol e2e test suite for the e2e\_app; Add platform-specific camera and gallery e2e tests; Added Android instrumentation tests for Flutter integration; Added Patrol e2e tests for permissions and macOS app interactions; Added automated test for \patrol develop\ hot restart behavior; Added comprehensive test suite for PatrolFinder and PatrolTester; Added e2e tests for native permission handling and notification interactions; Added example test and updated example app test location; Added example tests for patrol\_finders; Added internal and example end-to-end tests for Patrol; Added native camera and gallery integration tests for the e2e app; Added native integration tests for device services and gestures; Added placeholder test to satisfy CI requirements; Added smoke test for MCP server startup and shutdown; Added test assets for e2e scenarios; Added test coverage for core CLI utilities and test infrastructure; Added test coverage for patrol CLI commands and services; Added test coverage for web runner multi-tab and page management features; Added test infrastructure and mocks for patrol\_cli; Added test infrastructure for Patrol Web runner; Added tests for analytics sending behavior and error handling; Added tests for cross-platform app options, Flutter tool interactions, and test manifest parsing; Added tests for device listing, selection, FVM resolution, and screenshot capture; Added tests for iOS test backend and Xcode test code generation; Added tests for version compatibility logic; Added tests for web runner action handlers; Added unit tests for ADB device listing and forward parsing; Added unit tests for Android test backend logic and code generation; Added unit tests for Android test contract flattening and generated test detection; Added unit tests for Patrol internal components and configuration; Added unit tests for PatrolLogReader and TestEntry behavior; Added unit tests for PubspecReader and TestBundler; Added unit tests for iOS selector-to-NSPredicate conversion; Expanded web test coverage for Patrol's web platform capabilities; Removed empty test file in maestro/test.

The e2e\_app and cli\_tests packages now include their pubspec.yaml and lockfile dependencies, with the e2e\_app targeting Dart SDK \>=3.10.0 and Flutter \>=3.38.0, and cli\_tests targeting Dart SDK \>=3.8.0. The e2e\_app also pins permission\_handler\_apple to 9.4.5 to work around a known issue.

(dependencies) · high confidence

Added clang-format and gitignore configurations for the Darwin package; Initial release of patrol\_cli package metadata and documentation.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 58.

• Code Health 93
• Architecture 96
• Maturity 56
• Readiness 54
• Security 55
• Domain Modelling 100
• Accessibility 61

• 300 commits — 203 feature/other, 97 fixes

• (repo) — 86 commits
• packages/patrol_cli — 85 commits
• packages/patrol — 45 commits
• docs/documentation — 20 commits
• .github/workflows — 19 commits
• packages/patrol_mcp — 16 commits
• dev/e2e_app — 11 commits
• docs/cli-commands — 4 commits
• screenshots/ko — 4 commits
• .github/WORKFLOWS.md — 3 commits
• packages/patrol_log — 2 commits
• (root) — 1 commit
• .agents/skills — 1 commit
• docs/index.mdx — 1 commit
• packages/adb — 1 commit
• packages/patrol_devtools_extension — 1 commit

• fix: Fix dart format in e2e_app tests
• fix: Fix klint
• fix: Fix patrol develop after marathon PR
• fix: Fix patrol_cli constraints in compatibility table
• fix: Fix readme lines ordering
• fix: Fix unused shown name in internals test
• fix: Fix web coverage tests on windows
• fix: Fix zero-height visibleBounds on Android
• fix: Fix/use ktor bom (#3187)
• fix: Hotfix/build ios xctestrun search not respecting current dir (#3250)
• fix: Merge branch 'master' into fix/develop-flavored-simulator-attach
• fix: Merge branch 'master' into fix/develop-stdin-modes
• fix: Merge branch 'master' into fix/macos-spm-objc-bridge
• fix: Merge branch 'master' into fix/patrol-mcp-session-robustness
• fix: Merge branch 'master' into fix/slash-description
• fix: Merge branch 'master' into fix/test-description-on-failure
• fix: Merge branch 'master' into fix/validate-android-env
• fix: Merge pull request #3158 from leancodepl/fix/develop-app-shutdown-hang
• fix: Merge pull request #3167 from leancodepl/fix/test-description-on-failure
• fix: Merge pull request #3168 from leancodepl/fix/validate-android-env
• …and 280 more

• 0 containers · 2 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

leancodepl/patrol was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.