Skip to content

evanca/flutter-ai-rules / skills/patrol-e2e-testing

patrol-e2e-testing

Unverified

Use when writing E2E/integration tests, testing native interactions like permissions or system dialogs, capturing UI regressions, or validating cross-platform behavior (Patrol 4.x).

Patrol E2E Testing Skill

Design, implement, and run end-to-end (E2E) tests using Patrol 4.x in Flutter projects.

When to Use

Use this skill when:

  • A new screen or user flow needs E2E test coverage.
  • A feature interacts with native components (permissions, notifications, system dialogs, deep links).
  • A UI bug should be captured as a regression test.
  • Cross-platform behavior (Android / iOS / Web) must be validated.
  • Setting up Patrol in a new or existing Flutter project.

Setup

Follow the official Patrol documentation for installation and project initialization: https://patrol.leancode.co/documentation#setup

Key Patrol conventions:

  • Add patrol as a dev dependency.
  • Place tests in patrol_test/.
  • Name test files with a _test.dart suffix.
  • Execute tests with patrol test.

Workflow

Follow these steps when implementing or updating Patrol tests.

1. Identify the user journey

Break the feature into:

  • Actions: taps, scrolls, input, navigation, deep links.
  • Observable outcomes: visible text, screen changes, enabled buttons, dialogs.

Rules:

  • One test per primary (happy-path) journey.
  • Separate tests for critical edge cases.
  • Avoid combining unrelated flows in a single test.

2. Structure the Patrol test

Basic Patrol structure:

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

void main() {
  patrolTest(
    'user can log in successfully',
    ($) async {
      await $.pumpWidgetAndSettle(const MyApp());

      const email = String.fromEnvironment('E2E_EMAIL');
      const password = String.fromEnvironment('E2E_PASSWORD');

      await $(#emailField).enterText(email);
      await $(#passwordField).enterText(password);
      await $(#loginButton).tap();

      await $.waitUntilVisible($(#homeScreenTitle));

      expect($(#homeScreenTitle).text, equals('Welcome'));
    },
  );
}

Key concepts:

  • Use patrolTest() instead of testWidgets().
  • $ is the Patrol tester.
  • Use $(#keyName) to find widgets by Key.
  • Use explicit wait conditions (e.g., waitUntilVisible).

3. Handle native dialogs

For OS-level permission dialogs:

patrolTest('grants camera permission', ($) async {
  await $.pumpWidgetAndSettle(const MyApp());

  await $(#openCameraButton).tap();

  if (await $.native.isPermissionDialogVisible()) {
    await $.native.grantPermission();
  }

  await $.waitUntilVisible($(#cameraPreview));
});

Use native automation only when required by the feature.

4. Selector & interaction quick reference

Finding widgets:

$('some text')        // by text
$(TextField)          // by type
$(Icons.arrow_back)   // by icon

Tapping:

// Tap a widget containing a specific text label
await $(Container).$('click').tap();

// Tap a container that contains an ElevatedButton
await $(Container).containing(ElevatedButton).tap();

// Tap only the enabled ElevatedButton
await $(ElevatedButton)
    .which<ElevatedButton>(
      (b) => b.enabled,
    )
    .tap();

Entering text:

// Enter text into the second TextField on screen
await $(TextField).at(1).enterText('your input');

Scrolling:

await $(widget_you_want_to_scroll_to).scrollTo();

Native interactions:

// Grant permission while app is in use
await $.native.grantPermissionWhenInUse();

// Open notification shade and tap a notification by text
await $.native.openNotifications();
await $.native.tapOnNotificationBySelector(
  Selector(textContains: 'text'),
);

5. Running Patrol tests

Run all tests:

patrol test

Run a specific file with live reload (development mode):

patrol develop -t integration_test/my_test.dart

Run a specific file:

patrol test --target patrol_test/login_test.dart

Run on web:

patrol test --device chrome

Headless web (CI):

patrol test --device chrome --web-headless true

Filter by tags:

patrol test --tags android

6. Stabilization patterns

Flaky tests undermine confidence. Apply these patterns:

// AVOID — arbitrary delay
await Future.delayed(Duration(seconds: 3));

// PREFER — explicit wait condition
await $.waitUntilVisible($(#targetWidget));

// For animations, pump until settled
await $.pumpAndSettle();
  • Never use Future.delayed as a synchronization mechanism.
  • Use waitUntilVisible or waitUntilExists to wait for UI state.
  • Set settleTimeout in PatrolTesterConfig for slow CI environments.

Output requirements

When applied, this skill produces:

  1. Patrol test(s) covering the specified feature.
  2. Any required widget Key additions to production code.
  3. Exact patrol test command(s) to execute locally.
  4. Notes explaining stabilization or timing decisions.

Checkpoint: Run patrol test --target <file> locally to confirm the test passes before committing.

Quality bar

A valid Patrol test must be:

  • Deterministic — no arbitrary delays; uses explicit wait conditions.
  • Readable — clear test name describing the user journey.
  • Minimal but complete — one assertion chain per journey.
  • Secret-safe — credentials loaded from String.fromEnvironment, never hardcoded.
  • CI-ready — passes headless with --web-headless true or on emulator.
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
webapp-testinganthropics/skillsToolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
browser-testing-with-devtoolsaddyosmani/agent-skillsTests in real browsers via Chrome DevTools MCP. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data. Requires the chrome-devtools MCP server to be configured.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
ci-cd-and-automationaddyosmani/agent-skillsAutomates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.Stars: 118kUpdated Claude CodeCodexVerifiedInstall