patrol-e2e-testing

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).