Patrol

https://patrol.leancode.co/
Admin
Patrol is a powerful, open-source UI testing framework for Flutter apps that extends Flutter's core...
Tokens:71,170
Snippets:655
Trust Score:8.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example .patrol.env file

Source: https://patrol.leancode.co/documentation/other/tips-and-tricks

Shows an example .patrol.env file with comments. Comments are supported using # and can be inline or on their own line.

```bash
$ cat .patrol.env
# Add your username here
EMAIL=user@example.com
PASSWORD=ny4ncat # The password for the API
```

--------------------------------

### Install Marathon CLI

Source: https://patrol.leancode.co/documentation/integrations/marathon

Install Marathon CLI version 0.10+ using Homebrew.

```bash
brew tap malinskiy/tap
brew install malinskiy/tap/marathon
```

--------------------------------

### Serve Allure report

Source: https://patrol.leancode.co/documentation/integrations/allure

Serve the Allure report from the retrieved results. If using Homebrew, install Allure with 'brew install allure'.

```bash
allure serve ./build/reports/allure-results
```

--------------------------------

### Using key-based finder

Source: https://patrol.leancode.co/documentation/other/effective-patrol

Simplifies the previous example by using a key to tap the login button directly.

```dart
await $(#loginButton).tap();
```

--------------------------------

### Discovery output example

Source: https://patrol.leancode.co/documentation/ci/build-time-test-discovery

Example output showing discovered tests grouped by source file and where generated code landed. The printed names are exact Dart test names usable with --only.

```text
✓ Discovered Dart tests → build/patrol/patrol_test_manifest.json (9.0s)
Discovered 3 Dart test(s) (1 skipped) in 1 file(s):

  patrol_test/example_test.dart  (3 test(s), 1 skipped)
    • example_test counter state is the same after going to Home and switching apps
    • example_test short test with two tags  [skip]
    • example_test short test with tag

Generated 3 static XCTest method(s) → ios/RunnerUITests/PatrolGeneratedTests.inc
```

--------------------------------

### Upload APKs and start test execution on LambdaTest

Source: https://patrol.leancode.co/documentation/integrations/lambdatest

Run the Patrol CLI command to upload the app and instrumentation APKs to LambdaTest and start test execution. Optional environment variables LAMBDATEST_PROJECT and LAMBDATEST_DEVICES can be set. The output shows the upload progress and the resulting app IDs and build ID.

```bash
$ export LAMBDATEST_PROJECT=AwesomeApp # optional
$ export LAMBDATEST_DEVICES="[\"Pixel 7 Pro-13\"]" # optional
• Building apk with entrypoint test_bundle.dart...
✓ Completed building apk with entrypoint test_bundle.dart (11.0s)
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 82.4M  100   255  100 82.4M      7  2897k  0:00:31  0:00:36  0:00:02 2051k
Uploaded app, "app_id": "lt://APP1016047291733313441063634",
Uploaded testsuite, "app_id": "lt://APP1016047291733312896265135",
{
    "status": [
        "Success"
    ],
    "buildId": [
        "5875687"
    ],
    "message": [
        ""
    ]
}
```

--------------------------------

### Install patrol_cli

Source: https://patrol.leancode.co/documentation

Install the Patrol CLI globally using Flutter's pub global activate command. This is required to run Patrol UI tests.

```bash
  flutter pub global activate patrol_cli

```

--------------------------------

### patrol build synopsis

Source: https://patrol.leancode.co/cli-commands/build

Basic usage of `patrol build` for Android and iOS. Requires native setup to be completed.

```bash
patrol build android
patrol build ios
```

--------------------------------

### Build Android Patrol test APKs

Source: https://patrol.leancode.co/documentation/integrations/firebase-test-lab

Builds the app under test and the test instrumentation APK for Android using the Patrol CLI. Requires the native setup guide to be completed first.

```bash
patrol build android --target patrol_test/example_test.dart
```

--------------------------------

### Run patrol develop

Source: https://patrol.leancode.co/cli-commands/develop

Starts the development mode for integration tests with Hot Restart. Use `patrol develop --help` to see all options.

```bash
patrol develop
```

--------------------------------

### Example output of patrol build ios

Source: https://patrol.leancode.co/documentation/integrations/firebase-test-lab

Shows the output of the patrol build ios command, including the paths to the built app binaries and the xctestrun file.

```bash
$ patrol build ios -t patrol_test/example_test.dart --release
• Building app with entrypoint example_test.dart for iOS device (release)...
✓ Completed building app with entrypoint example_test.dart for iOS device (31.5s)
build/ios_integ/Build/Products/Release-iphoneos/Runner.app (app under test)
build/ios_integ/Build/Products/Release-iphoneos/RunnerUITests-Runner.app (test instrumentation app)
build/ios_integ/Build/Products/Runner_iphoneos16.2-arm64.xctestrun (xctestrun file)
```

--------------------------------

### Example: open external page, check URL, and clean up

Source: https://patrol.leancode.co/documentation/web

A complete Patrol test that opens a new page, switches to it, verifies the URL contains 'example.com', closes the page, and returns to the initial page.

```dart
patrol('opens an external page in a new tab', ($) async {
  await $.pumpWidgetAndSettle(const MyApp());

  final pageId = await $.platform.web.openNewPage(url: 'https://example.com');
  await $.platform.web.switchToPage(pageId: pageId);

  final url = await $.platform.web.getCurrentPageUrl();
  expect(url, contains('example.com'));

  await $.platform.web.closePage(pageId: pageId);
  await $.platform.web.switchToInitialPage();
});
```

--------------------------------

### Launch app in Patrol development mode

Source: https://patrol.leancode.co/documentation/other/patrol-devtools-extension

Starts the app in Patrol development mode, launching the test on the connected device/simulator, starting the Flutter DevTools server, and printing a clickable link to the DevTools interface.

```bash
patrol develop -t patrol_test/example_test.dart
```

--------------------------------

### Web platform automation example (patrol_test/web_demo_test.dart)

Source: https://patrol.leancode.co/documentation/native/overview

Demonstrates using Patrol's browser-specific automation for web apps, including granting permissions, managing cookies, and handling browser dialogs within a patrolTest.

```dart
void main() {
  patrolTest('web demo', (PatrolIntegrationTester $) async {
    await $.pumpWidgetAndSettle(AwesomeWebApp());

    // grant browser permissions
    await $.platform.web.grantPermissions(permissions: ['clipboard-read']);

    // manage cookies
    await $.platform.web.addCookie(name: 'session', value: 'abc123');

    // handle browser dialogs
    await $.platform.web.acceptNextDialog();
  });
}
```

--------------------------------

### Launch app with --open-devtools flag

Source: https://patrol.leancode.co/documentation/other/patrol-devtools-extension

Automatically opens DevTools when starting Patrol development mode, useful when terminal logs clutter the output.

```bash
patrol develop -t patrol_test/example_test.dart  --open-devtools
```

--------------------------------

### Open DevTools extension link output

Source: https://patrol.leancode.co/documentation/other/patrol-devtools-extension

Example terminal output when running 'patrol develop -t', showing the clickable link to the Patrol DevTools extension.

```text
Patrol DevTools extension is available at:
http://127.0.0.1:9102/patrol_ext?uri=http://127.0.0.1:58463/MOAGppLU9BU=/

```

--------------------------------

### Mobile platform automation example (patrol_test/demo_test.dart)

Source: https://patrol.leancode.co/documentation/native/overview

Demonstrates using Patrol's platform automation to control mobile network conditions, system theme, permissions, and notifications within a patrolTest. It shows enabling cellular, disabling Wi-Fi, enabling dark mode, handling location permission, and tapping a notification.

```dart
void main() {
  patrolTest('demo', (PatrolIntegrationTester $) async {
    await $.pumpWidgetAndSettle(AwesomeApp());
    // prepare network conditions
    await $.platform.mobile.enableCellular();
    await $.platform.mobile.disableWifi();

    // toggle system theme
    await $.platform.mobile.enableDarkMode();

    // handle native location permission request dialog
    await $.platform.mobile.selectFineLocation();
    await $.platform.mobile.grantPermissionWhenInUse();

    // tap on the first notification
    await $.platform.mobile.openNotifications();
    await $.platform.mobile.tapOnNotificationByIndex(0);
  });
}
```

--------------------------------

### Build with custom build name and number

Source: https://patrol.leancode.co/cli-commands/build

Builds with custom build name and number using `--build-name` and `--build-number` flags. The iOS example includes `--release`.

```bash
patrol build android --build-name=1.2.3 --build-number=123
patrol build ios --build-name=1.2.3 --build-number=123  --release
```

--------------------------------

### Run patrol test command

Source: https://patrol.leancode.co/documentation

Run this command to execute the integration test on a connected Android, iOS, or macOS device. If setup is successful, a summary with total, successful, failed, skipped, report path, and duration is shown.

```bash
patrol test -t patrol_test/example_test.dart
```

--------------------------------

### SauceLabs iOS config (.sauce/ios.yml)

Source: https://patrol.leancode.co/documentation/integrations/saucelabs

SauceLabs xcuitest config pointing at the two bundles built by `patrol build ios`. For real devices, you must first do the setup for physical iOS devices; the test runner is a separate app from the one under test, so it needs its own identifier, certificate and profile.

```yaml
apiVersion: v1alpha
kind: xcuitest
sauce:
  region: us-west-1
xcuitest:
  app: build/ios_integ/Build/Products/Debug-iphonesimulator/Runner.app
  testApp: build/ios_integ/Build/Products/Debug-iphonesimulator/RunnerUITests-Runner.app
suites:
  - name: "iOS"
    simulators:
      - name: "iPhone 15 Simulator"
        platformVersions:
          - "17.0"
```

--------------------------------

### Run iOS tests on Firebase Test Lab with gcloud

Source: https://patrol.leancode.co/documentation/integrations/firebase-test-lab

Uploads the iOS test zip to Firebase Test Lab for execution. Requires gcloud to be installed. If the .xctestrun file has a different iOS version than the device, rename it to match.

```bash
gcloud firebase test ios run \
  --test build/ios_integ/Build/Products/ios_tests.zip \
  --device model=iphone8,version=16.2,locale=en_US,orientation=portrait
```

--------------------------------

### Get device info with $.platform.mobile

Source: https://patrol.leancode.co/documentation/native/usage

Get device information: check if running on an emulator/simulator and get the OS version (e.g., 30 for Android 11).

```dart
// Check if running on an emulator/simulator
final isVirtual = await $.platform.mobile.isVirtualDevice();

// Get OS version (e.g., 30 for Android 11)
final osVersion = await $.platform.mobile.getOsVersion();
if (osVersion >= 30) {
  // Android 11+ specific behavior
}
```

--------------------------------

### Create AllurePatrolJUnitRunner.kt

Source: https://patrol.leancode.co/documentation/integrations/allure

Create a Kotlin file in the same directory as MainActivityTest.java. Replace the package line with your app's package. This runner sets up Allure lifecycle and listeners.

```kotlin
package pl.leancode.patrol.example // replace "pl.leancode.patrol.example" with your app's package

import android.os.Bundle
import io.qameta.allure.android.AllureAndroidLifecycle
import io.qameta.allure.android.listeners.ExternalStoragePermissionsListener
import io.qameta.allure.android.writer.TestStorageResultsWriter
import io.qameta.allure.kotlin.Allure
import io.qameta.allure.kotlin.junit4.AllureJunit4
import io.qameta.allure.kotlin.util.PropertiesUtils
import pl.leancode.patrol.PatrolJUnitRunner

class AllurePatrolJUnitRunner : PatrolJUnitRunner() {
    override fun onCreate(arguments: Bundle) {
        Allure.lifecycle = createAllureAndroidLifecycle()
        val listenerArg = listOfNotNull(
            arguments.getCharSequence("listener"),
            AllureJunit4::class.java.name,
            ExternalStoragePermissionsListener::class.java.name.takeIf { useTestStorage }
        ).joinToString(separator = ",")
        arguments.putCharSequence("listener", listenerArg)
        super.onCreate(arguments)
    }

    private fun createAllureAndroidLifecycle() : AllureAndroidLifecycle {
      return createDefaultAllureAndroidLifecycle()
    }

    private fun createDefaultAllureAndroidLifecycle() : AllureAndroidLifecycle {
        if (useTestStorage) {
            return AllureAndroidLifecycle(TestStorageResultsWriter())
        }

        return AllureAndroidLifecycle()
    }

    private val useTestStorage: Boolean
        get() = PropertiesUtils.loadAllureProperties()
            .getProperty("allure.results.useTestStorage", "true")
            .toBoolean()
}
```

--------------------------------

### Specify build name and number

Source: https://patrol.leancode.co/cli-commands/test

Shows how to set custom build name and build number using `--build-name` and `--build-number`.

```bash
patrol test --build-name=1.2.3 --build-number=123
patrol test --target patrol_test/login_test.dart --build-name=1.2.3 --build-number=123
```

--------------------------------

### Install specific patrol_cli version

Source: https://patrol.leancode.co/documentation/native/advanced

Installs a specific version of Patrol CLI, e.g., the latest v1.x. Recommended for CI systems to avoid unexpected breakages.

```bash
dart pub global activate patrol_cli ^1.0.0
```

--------------------------------

### Build and run all tests

Source: https://patrol.leancode.co/cli-commands/test-without-building

First builds the iOS app with test manifest emission, then runs all built tests without rebuilding.

```bash
patrol build ios --emit-test-manifest
patrol test-without-building
```

--------------------------------

### Create Marathondevices

Source: https://patrol.leancode.co/documentation/integrations/marathon

Create a Marathondevices file with local simulator profiles for iOS.

```yaml
workers:
  - transport:
      type: local
    devices:
      - type: simulatorProfile
        deviceType: com.apple.CoreSimulator.SimDeviceType.iPhone-17
      - type: simulatorProfile
        deviceType: com.apple.CoreSimulator.SimDeviceType.iPhone-17-Pro
```

--------------------------------

### Tag expression syntax examples

Source: https://patrol.leancode.co/documentation/other/patrol-tags

Patrol supports complex tag expressions using logical operators `||`, `&&`, and `!`. These examples show various combinations, including OR, AND, NOT, and combining `--tags` with `--exclude-tags`.

```bash
# Run tests that have either 'smoke' OR 'regression' tag
patrol test --tags='smoke||regression'

# Run tests that have BOTH 'login' AND 'smoke' tags
patrol test --tags='(login && smoke)'

# Run tests with 'payment' OR 'navigation' tag, but NOT 'regression'
patrol test --tags='(payment || navigation) && !regression'

# Combine --tags with --exclude-tags
patrol test --tags='smoke||regression' --exclude-tags='slow'

# Complex expression: (login OR payment) AND (smoke OR regression)
patrol test --tags='((login || payment) && (smoke || regression))'
```

--------------------------------

### Verify Patrol installation with patrol doctor

Source: https://patrol.leancode.co/documentation

Run patrol doctor to verify that the installation was successful and the environment is set up properly. The output shows the Patrol CLI version and checks for Android, iOS/macOS, and Web tools.

```bash
patrol doctor

```

```text
Patrol CLI version: 2.3.1+1
Android:
• Program adb found in /Users/username/Library/Android/sdk/platform-tools/adb
• Env var $ANDROID_HOME set to /Users/username/Library/Android/sdk
iOS / macOS:
• Program xcodebuild found in /usr/bin/xcodebuild
• Program ideviceinstaller found in /opt/homebrew/bin/ideviceinstaller
Web:
• Program node found in /usr/bin/node
• Program npm found in /usr/bin/npm

```

--------------------------------

### Bad patrolTest description example

Source: https://patrol.leancode.co/documentation/other/effective-patrol

Avoid using a generic description like 'test' as the first argument to `patrolTest`. This example shows a poor description that does not explain the test's purpose, making it hard to understand later.

```dart
// BAD
void main() {
  patrolTest(
    'test',
    ($) async {
      await $.pumpWidgetAndSettle(AwesomeApp());

      await $(#phoneNumber).enterText('800-555-0199');
      await $(#loginButton).tap();

      // more code
    },
  );
}
```

--------------------------------

### Create report directory

Source: https://patrol.leancode.co/documentation/integrations/allure

Create a directory for the Allure report before retrieving results from the device.

```bash
mkdir -p ./build/reports
```

--------------------------------

### $.platform.web.getClipboard

Source: https://patrol.leancode.co/documentation/native/usage

Gets the current clipboard content from the browser.

```APIDOC
## $.platform.web.getClipboard

### Description
Gets the current clipboard content from the browser.

### Method
Web action

### Returns
- **String** - The clipboard content.

### Example
```dart
final clipboardContent = await $.platform.web.getClipboard();
```
```

--------------------------------

### Good patrolTest description example

Source: https://patrol.leancode.co/documentation/other/effective-patrol

Use a descriptive test description as the first argument to `patrolTest` to explain the test's purpose. This example shows a clear description: 'signs up for the newsletter and receives a reward'. Includes imports and a sample test body.

```dart
// GOOD
import 'package:awesome_app/main.dart';
import 'package:patrol/patrol.dart';

void main() {
  patrolTest(
    'signs up for the newsletter and receives a reward',
    ($) async {
      await $.pumpWidgetAndSettle(AwesomeApp());

      await $(#phoneNumber).enterText('800-555-0199');
      await $(#loginButton).tap();

      // more code
    },
  );
}
```

--------------------------------

### $.platform.mobile.getOsVersion

Source: https://patrol.leancode.co/documentation/native/usage

Gets the OS version of the device running the test.

```APIDOC
## $.platform.mobile.getOsVersion

### Description
Gets the OS version of the device running the test.

### Method
Mobile action

### Returns
- **int** - The OS version (e.g., 30 for Android 11).

### Example
```dart
final osVersion = await $.platform.mobile.getOsVersion();
if (osVersion >= 30) {
  // Android 11+ specific behavior
}
```
```

--------------------------------

### Build for patrol develop session on another machine

Source: https://patrol.leancode.co/cli-commands/build

Builds APKs for a `patrol develop` session on another machine using `--develop`. The second command points `patrol develop` at the prebuilt APKs with `--use-prebuilt-apks`.

```bash
patrol build android --develop --target patrol_test/example_test.dart
```

```bash
patrol develop --use-prebuilt-apks path/to/apks --target patrol_test/example_test.dart
```

--------------------------------

### Horizontal pull to refresh

Source: https://patrol.leancode.co/feature-guide/pull-to-refresh

Performs a horizontal pull-to-refresh gesture by specifying start and end offsets.

```dart
// Pull to refresh horizontally (swipe left)
await $.platform.mobile.pullToRefresh(
  start: Offset(0.5, 0.5),
  end: Offset(0.1, 0.5),
);
```

--------------------------------

### Use patrolWidgetTest wrapper

Source: https://patrol.leancode.co/documentation/finders/finders-setup

Shows how to use the `patrolWidgetTest` wrapper, which initializes `PatrolTester` automatically.

```dart
void main() {
  patrolWidgetTest(
    'counter is incremented when plus button is tapped',
    (PatrolTester $) async {
      await $.pumpWidget(const MyApp());

      expect($('0'), findsOneWidget);
      expect($('-1'), findsNothing);

      await $(Icons.remove).tap();

      expect($('0'), findsNothing);
      expect($('-1'), findsOneWidget);
    },
  );
}
```

--------------------------------

### Install patrol_finders as dev dependency

Source: https://patrol.leancode.co/documentation/finders/finders-setup

Adds the `patrol_finders` package as a dev dependency to the app's `pubspec.yaml`.

```bash
flutter pub add patrol_finders --dev
```

--------------------------------

### Build and run iOS tests

Source: https://patrol.leancode.co/documentation/integrations/marathon

Build the iOS test artifacts and run Marathon with the Marathonfile.ios.

```bash
patrol build ios --debug --simulator
marathon run -m Marathonfile.ios
```

--------------------------------

### Specify flavor in pubspec.yaml

Source: https://patrol.leancode.co/documentation

Recommended way to configure the app name, flavor, and platform-specific package/bundle identifiers in pubspec.yaml.

```yaml
patrol:
  app_name: My App
  flavor: development
  android:
    package_name: com.example.myapp
  ios:
    bundle_id: com.example.MyApp
    app_name: The Awesome App
  macos:
    bundle_id: com.example.macos.MyApp
```

--------------------------------

### Request permission before pumping the main app widget

Source: https://patrol.leancode.co/documentation/other/tips-and-tricks

Request permission and get position before pumping the app widget, using geolocator.

```dart
final permission = await Geolocator.requestPermission();
final position = await Geolocator.getCurrentPosition();
await $.pumpWidgetAndSettle(MyApp(position: position));
```

--------------------------------

### Run Patrol test on Chrome

Source: https://patrol.leancode.co/documentation/web

Use the `--device` flag with `chrome` to run Patrol tests on web. Requires Node.js installed.

```bash
patrol test --device chrome --target patrol_test/login_test.dart
```

--------------------------------

### Run patrol doctor

Source: https://patrol.leancode.co/cli-commands/doctor

Displays information about installed tooling. Use `patrol doctor --help` to see all available options and flags.

```bash
patrol doctor
```

--------------------------------

### Create Marathonfile.ios

Source: https://patrol.leancode.co/documentation/integrations/marathon

Create a Marathonfile.ios with xctest parser and fixed-size batching strategy.

```yaml
name: "My app iOS"
outputDir: "build/reports/marathon/ios"
batchingStrategy:
  type: "fixed-size"
  size: 10
vendorConfiguration:
  type: "iOS"
  testParserConfiguration:
    type: "xctest"
  bundle:
    application: "build/ios_integ/Build/Products/Debug-iphonesimulator/Runner.app"
    testApplication: "build/ios_integ/Build/Products/Debug-iphonesimulator/RunnerUITests-Runner.app/PlugIns/RunnerUITests.xctest"
    testType: "xcuitest"
```

--------------------------------

### Build and run Android tests

Source: https://patrol.leancode.co/documentation/integrations/marathon

Build the Android test artifacts and run Marathon with the Marathonfile.android.

```bash
patrol build android
marathon run -m Marathonfile.android
```

--------------------------------

### Add meta package as dev dependency

Source: https://patrol.leancode.co/documentation/other/patrol-vs-code-extension

Run this command to add the meta package as a dev dependency if it is not already in pubspec.yaml.

```bash
flutter pub add meta --dev
```

--------------------------------

### iOS: Dump native view hierarchy with idb

Source: https://patrol.leancode.co/documentation/other/tips-and-tricks

Performs a native view hierarchy dump on iOS using the idb tool. Requires idb to be installed.

```bash
idb ui describe-all
```

--------------------------------

### Record video with patrol test --record-video

Source: https://patrol.leancode.co/cli-commands/test

Use `patrol test --record-video` to record a video of each test case. Videos are saved as .mp4 files in <test-directory>/videos, overridable with --video-output-dir. Supported on Android emulators and iOS simulators; physical iOS devices are not supported. Recording is skipped on unsupported devices.

```bash
patrol test --record-video
```

--------------------------------

### $.platform.web.goForward

Source: https://patrol.leancode.co/documentation/native/usage

Navigates the browser forward.

```APIDOC
## $.platform.web.goForward

### Description
Navigates the browser forward.

### Method
Web action

### Example
```dart
await $.platform.web.goForward();
```
```

--------------------------------

### Expected test summary output

Source: https://patrol.leancode.co/documentation

Example output after a successful patrol test run. Shows total, successful, failed, skipped, report path, and duration.

```text
Test summary:
📝 Total: 1
✅ Successful: 1
❌ Failed: 0
⏩ Skipped: 0
📊 Report: <some path>
⏱️  Duration: 4s
```

--------------------------------

### Create patrol section in pubspec.yaml

Source: https://patrol.leancode.co/documentation

Add a patrol section to pubspec.yaml with the app name and platform-specific package names and bundle IDs. Replace the example values with your own.

```yaml
dependencies:
  # ...

dev_dependencies:
  # ...

patrol:
  app_name: My App
  android:
    package_name: com.example.myapp
  ios:
    bundle_id: com.example.MyApp
  macos:
    bundle_id: com.example.macos.MyApp

```

--------------------------------

### Retrieve Allure results from device

Source: https://patrol.leancode.co/documentation/integrations/allure

Retrieve the allure-results directory from the device using adb and extract it to the local build/reports directory.

```bash
adb exec-out sh -c 'cd /sdcard/googletest/test_outputfiles && tar cf - allure-results' | tar xvf - -C build/reports
```

--------------------------------

### $.platform.web.goBack

Source: https://patrol.leancode.co/documentation/native/usage

Navigates the browser back.

```APIDOC
## $.platform.web.goBack

### Description
Navigates the browser back.

### Method
Web action

### Example
```dart
await $.platform.web.goBack();
```
```

--------------------------------

### Create example_test.dart with patrolTest

Source: https://patrol.leancode.co/documentation

Paste this code into patrol_test/example_test.dart. It creates a patrolTest that pumps a MaterialApp, expects a text 'app', and presses home on mobile platforms. Replace the widget with your app's main widget later.

```dart
import 'dart:io';

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:patrol/patrol.dart';

void main() {
  patrolTest(
    'counter state is the same after going to home and switching apps',
    ($) async {
      // Replace later with your app's main widget
      await $.pumpWidgetAndSettle(
        MaterialApp(
          home: Scaffold(
            appBar: AppBar(title: const Text('app')),
            backgroundColor: Colors.blue,
          ),
        ),
      );

      expect($('app'), findsOneWidget);
      if (!Platform.isMacOS) {
        await $.platform.mobile.pressHome();
      }
    },
  );
}

```

--------------------------------

### Use platform-specific selectors with MobileSelector

Source: https://patrol.leancode.co/documentation/native/usage

Use `MobileSelector` to specify different selectors for Android and iOS. The example taps a button using `AndroidSelector` with `resourceName` and `IOSSelector` with `identifier`.

```dart
await $.platform.mobile.tap(
  MobileSelector(
    android: AndroidSelector(resourceName: 'com.example:id/button'),
    ios: IOSSelector(identifier: 'myButton'),
  ),
);
```

--------------------------------

### Switch RunnerUITests.m to static runner

Source: https://patrol.leancode.co/documentation/ci/build-time-test-discovery

Replace the runtime macro with the static base macro and include the generated .inc file. Required for iOS build-time discovery; without it the build fails to compile.

```objectivec
@import XCTest;
@import patrol;
@import ObjectiveC.runtime;

PATROL_INTEGRATION_TEST_IOS_RUNNER_STATIC_BASE(RunnerUITests)
#include "PatrolGeneratedTests.inc"
```

--------------------------------

### Enter text by index with Patrol

Source: https://patrol.leancode.co/documentation/native/usage

Use `$.platform.mobile.enterTextByIndex` to enter text into the n-th currently visible text field, counting from 0. The example enters a username and password.

```dart
await $.platform.mobile.enterTextByIndex('charlie_root', index: 0); // enter username
await $.platform.mobile.enterTextByIndex('ny4ncat', index: 1); // enter password
```

--------------------------------

### iOS-specific actions with Patrol

Source: https://patrol.leancode.co/documentation/native/usage

Use `$.platform.ios` for iOS-only actions. The example shows tapping with an iOS-specific selector, closing a heads-up notification, swiping back, and opening a specific iOS app.

```dart
// Tap on a native view using iOS-specific selector
await $.platform.ios.tap(
  IOSSelector(identifier: 'submitButton'),
);

// Close a heads-up notification
await $.platform.ios.closeHeadsUpNotification();

// Swipe back gesture (iOS edge swipe)
await $.platform.ios.swipeBack();

// Open a specific iOS app
await $.platform.ios.openPlatformApp(iosAppId: 'com.apple.Preferences');
```

--------------------------------

### Build iOS test artifacts

Source: https://patrol.leancode.co/documentation/integrations/saucelabs

Build the iOS app and test runner for the simulator, or with `--release` for real devices. For real devices, XCUITest wants `.ipa` files rather than the `.app` bundles the build produces; pack each into an `.ipa` (a zip with the `.app` inside a `Payload/` directory) and point your config at the results.

```bash
patrol build ios --simulator   # or --release, for real devices
```

--------------------------------

### Create Marathonfile.android

Source: https://patrol.leancode.co/documentation/integrations/marathon

Create a Marathonfile.android in your app root with remote test parser for Android.

```yaml
name: "My app Android"
outputDir: "build/reports/marathon/android"
vendorConfiguration:
  type: "Android"
  applicationApk: "build/app/outputs/apk/debug/app-debug.apk"
  testApplicationApk: "build/app/outputs/apk/androidTest/debug/app-debug-androidTest.apk"
  testParserConfiguration:
    type: "remote"
```
Tokens:
Raw