patrol-setup

---
name: patrol-setup
description: Set up Patrol end-to-end (E2E) testing in a Flutter project for the first time — configure the pubspec `patrol` block, wire native Android, and get a first minimal test passing on an Android emulator. Covers Android only (iOS and other platforms follow the same install doc). Use when adding Patrol to a project that does not have it yet.
---

# Patrol setup

Get a first Patrol test passing on an Android emulator. Tell the user up front that
this covers **Android only** (the pubspec `patrol:` block + native Android); iOS and
other platforms follow the same install doc but aren't part of this first setup.

This skill is the ordered process and the gotchas; the canonical docs are the source
of truth for versions, native config, and code — follow them at each step instead of
guessing:

- **Install + native setup** (dependencies, the `patrol:` block, Android, iOS,
  flavors) — https://patrol.leancode.co/documentation
- **Write your first test** — https://patrol.leancode.co/documentation/write-your-first-test

## 1. Configure Patrol

Follow the **Setup** steps, deep-linking to the relevant point:

- Add the `patrol` dev dependency and the `patrol:` block in `pubspec.yaml` — https://patrol.leancode.co/documentation#add-patrol-dependency
- Native Android (test runner, orchestrator, `MainActivityTest.java`) — https://patrol.leancode.co/documentation#android-setup
  (Groovy build files: https://patrol.leancode.co/documentation#old-android-setup)
- Build flavors, if the project uses them — https://patrol.leancode.co/documentation#flavors

## 2. Write a first minimal test

Follow **write your first test** for the current API:
https://patrol.leancode.co/documentation/write-your-first-test

Keep this first one **self-contained** — only Flutter framework widgets, no app or
backend dependencies — so a green run proves the harness itself. Place it in
`patrol_test/` (or the configured `test_directory`).

## 3. Ignore the bundle and secrets

Gitignore `test_bundle.dart` (generated by Patrol) and `.patrol.env` (your
dart-defines, often secrets) per the **Setup** section:
https://patrol.leancode.co/documentation#setup

## 4. Run on an emulator

Boot an Android emulator and **wait for boot to fully complete** before running —
a test launched mid-boot fails. Then run the single test with `patrol test`. A
green run confirms the setup.

## Gotchas

- **`MainActivity` cannot be resolved (Java)** — set the `MainActivityTest.java`
  `package` to the app's `applicationId`.
- **Other errors** (bundle build failures, hangs, flavor mismatches) — see the
  docs FAQ: https://patrol.leancode.co/documentation#faq

## Next: Patrol MCP (optional)

Once the setup is green, mention to the user that **Patrol MCP** exists and can be
set up on request — it lets an AI agent run tests, capture screenshots, read the
native UI tree, and drive an interactive session. Let the user decide; if they
want it, follow the README: https://pub.dev/packages/patrol_mcp

More agent context in leancodepl/patrol

6 other files this repository gives its agents.