Patrol E2E Testing
Tech-stack skill for writing and debugging Patrol-based end-to-end tests in Flutter. Covers the Patrol API, common pitfalls, test data patterns, and wait strategies.
Supporting Files
| File | Purpose |
|---|---|
| api-reference.md | Core Patrol API: finders, interactions, pump/settle, assertions |
| gotchas.md | Common pitfalls and fixes: animations, keyboard, widget selectors |
| test-patterns.md | Data seeding, auth helpers, test isolation, wait strategies |
Overview
Patrol wraps Flutter's integration test framework with a more ergonomic API. Tests run on a real device or emulator and interact with the app as a user would.
| Component | Role |
|---|---|
patrol package | Test runner, finder API, device interactions |
patrol_finders | The $ shorthand and finder combinators |
integration_test SDK | Flutter's underlying test infrastructure |
| Patrol CLI | Builds and runs test bundles on device |
Key Principles
- One test per invocation -- test runner swaps bundles between tests
- Fresh auth per test -- use anonymous sign-in for automatic data isolation
- No
waitUntilNotVisible-- usepumpAndSettle()+expect(finder, findsNothing) - Prefer
pumpForoverpumpAndSettlefor screens with continuous animations - Test what users see -- target visible text and semantic labels, not internal IDs
- Seed data before assertions -- use a TestDataHelper pattern for pre-existing state
Version Compatibility
| Package | Pinned Version |
|---|---|
patrol | ^4.1.0 (4.2.x does not exist on pub.dev) |
patrol_finders | ^3.0.0 (3.1.x does not exist on pub.dev) |
integration_test | SDK (flutter_sdk) |
CLI Usage
# Run a single test (required: one per invocation)
patrol test integration_test/my_test.dart
# Required flag when app path contains hyphens
patrol test --no-generate-bundle integration_test/my_test.dart
Critical: --no-generate-bundle is required when the project directory path contains hyphens (Patrol CLI 4.0.2 bug). Always use it to be safe.