Order of actions when writing new tests

1. Read the key files directly (modules aggregator, test wrapper, main keys.dart, and the specific app feature files for the scenario). These are known paths — don't search for them, open them directly
2. Inspect existing modules for functions that can be reused
3. Also think if one of existing functions can be adjusted to match its existing usage and new test
4. Assign test keys to required elements if they are not assigned yet
5. Start writing test: reuse existing modules/functions + put new test steps in new test file
6. Write patrol actions directly in the test file, do not create new methods in modules
7. Run the test frequently during development — don't wait until the full test is written. Run after completing each logical group of steps to catch failures early
8. After full test passes, reorganize new code into existing/new modules. This is mandatory — the test file must only call module methods, not use Patrol APIs directly
9. Rerun the test after reorganizing to confirm it still passes

Patrol MCP Usage

• Use

  patrol-run({ "testFile": "patrol_test/your_test.dart" })

  to run tests and wait for completion
• If no session running: starts new session with specified test file
• If session already running: automatically restarts current tests
• Use

  patrol-screenshot({ "platform": "android" })

  or

  patrol-screenshot({ "platform": "ios" })

  to capture screenshots for debugging test failures
• Use

  patrol-quit({})

  to quit the session gracefully
• Use

  patrol-status({})

  to check current status and recent output
• Use

  patrol-native-tree({})

  to fetch the current native UI tree hierarchy for writing native interactions and interactions with apps other than the app under test.

Patrol Test Architecture

Structure

• Use custom

  testApp

  wrapper for all tests
• Each test file should contain only ONE test
• Organize tests using

  Modules

  ,

  System

  , and

  ApiClients

  pattern
• Each module represents a feature from user perspective (eg. Auth, Home screen, Downloads, Player)
• System is a class for native interactions, specifically for actions that we need to perform by using $.platform that are not part of our app, eg. enabling airplane mode to test offline mode. Do not put methods here unless they don't fit any module of the app
• ApiClients - a class aggregating api clients for api communication. There will be separate clients for different apis we need to communicate with - eg. email server for testing, our test backend, or some third-party services

Method organization in modules

• Do not write comments in all methods, use descriptive names instead
• Split long methods in modules when the method is hard to read and navigate due to its length and it represents multiple logical steps that can be descriptively named
• If there is a series of steps which is reused in many tests as a whole (e.g., long onboarding flow) create a wrapper method in the module which will call private methods for each step

Patrol Tests Rules

Patrol API

• Any file that directly uses Patrol APIs (

  $()

  ,

  .scrollTo()

  ,

  .tap()

  ,

  .enterText()

  ,

  .waitUntilVisible()

  , etc.) should

  import 'package:patrol/patrol.dart';

• ALWAYS inspect Patrol API before implementing test actions:
  • Search codebase for existing Patrol API usage patterns
  • Check $.platform APIs for the specific action
  • If method not found in codebase, check: https://patrol.leancode.co/
  • Only implement after confirming the correct API method
• ALWAYS inspect

  $.platform

  methods before implementing test actions
• Don't use flutter_test package. Use only patrol api
• Only run tests with Patrol MCP server for single test and

  patrol test

  for all tests. Never use

  flutter test

  command
• Do not write patrolSetUp and patrolTearDown methods on your own

Action Rules

• Don't use

  $.pump

  ,

  waitUntilVisible

  or

  waitUntilExists

  and other wait methods after or before tap, scrollTo and enterText. Patrol handles it automatically. Do this only at the end of the test
• To find widgets, use only keys
• Don't write try catch blocks unless absolutely necessary
• After writing test check if it works by running it with MCP server, fix it if it fails
• If test fails because element was not found, check if it need to be scrolled to in the app code and adjust the test if needed

Assertion Rules

• Don't write assertions after actions, but do write them at the end of the test
• Prefer using

  waitUntilVisible

  as assertion at the end of the test
• Use

  expect()

  for assertions only when

  waitUntilVisible

  is not enough

Native Dialog Handling

• ALWAYS handle native dialogs that appear during the flow:
  • Handle dialogs immediately after the action that triggers them
  • For native permissions prefer

    $.platform.mobile.grantPermissionWhenInUse

    over

    $.platform.mobile.tap

Test Keys

• Assign a key ONLY to widgets involved in testing
• ONLY add the

  key

  parameter to existing widgets
• Create new keys.dart files if needed
• Always have a maximum of one keys.dart file per feature directory, but the file can contain multiple classes
• Add imports for keys.dart files
• Update main keys.dart aggregator
• NEVER change widget signatures
• NEVER refactor existing code structure
• NEVER hardcode keys in the app, you must use keys from the keys.dart file
• NEVER create new widgets in the app
• NEVER create a key that is not assigned to a widget
• Always make sure that each key value is unique
• ALWAYS create keys.dart to store keys for the feature/widget they belong to, NOT in the main lib directory
• ALWAYS sort keys alphabetically
• The main

  Keys

  class in

  lib/keys.dart

  should only import and aggregate keys from feature-specific keys.dart files
• ALWAYS assign keys using this exact pattern:

  key: keys.feature.widgetName

  (unless you are using parameterized keys)
• Add keys as first parameter to the widget constructor
• Group related keys in a class named after the screen (e.g.

  HomeKeys

  ). Use a private subclass of

  ValueKey<String>

  to prefix all key values with the page or widget name
• For common widgets store them in WidgetKeys class. File containing this class should be placed in the directory that the common widget is defined
• For widgets located in separate package (e.g. widgetbook) follow this pattern: in

  widgetbook

  directory create

  keys.dart

  file with

  WidgetKeys

  class. Those keys are assigned with

  widgetKeys.tile

  . Then, in keys.dart lib/ add it to the list of pages with

  final widgetKeys = ds.widgetKeys;

  (ds being the imported package, e.g.

  import 'package:common_ui/widgets/keys.dart' as ds;

  )
• If widget is not unique (for example generated from a list) use a parameterized key
  • ALWAYS prefer using enums or DTOs as the parameter if they already exist
  • Use existing widget properties for parameterized keys
  • NEVER assign a parameterized key in the app and then use fixed values for it in the keys file (and vice versa)
  • NEVER create helper methods, use parameterized keys instead
  • When widgets are generated from existing enums or DTOs, always use parameterized keys with the those enum/DTO values as the parameter
  Use individual keys when:
  • Widgets are hardcoded and known at compile time
  • Widgets have distinct, meaningful names
  Use parameterized keys when:
  • Widgets are generated from dynamic data
  • Widgets are generated from a DTO or enums
  • Number of widgets is variable or large
  • Widgets are generated in loops or from lists

1. Identify widget that is needed for testing
2. Create key assignment:

   key: keys.feature.widgetName

3. Define key in keys.dart file
4. Verify key is assigned to widget

lib/features/home/keys.dart
lib/features/profile/keys.dart
lib/features/auth/keys.dart
lib/common/widgets/keys.dart

lib/keys.dart (imports and aggregates all feature keys)

// lib/features/home/keys.dart
import 'package:flutter/widgets.dart';

class _HomeKey extends ValueKey<String> {
  const _HomeKey(String value) : super('home_$value');
}
class HomeKeys {
  final menuIconButton = const _HomeKey('menuIconButton');
  _HomeKey navbarItem(String label) => _HomeKey('navbarItem_$label');
}

// lib/keys.dart
import 'common/widgets/keys.dart';
import 'features/home/keys.dart';
import 'features/profile/keys.dart';

final keys = Keys();

class Keys {
   final home = HomeKeys();
   final profile = ProfileKeys();
   final widgets = WidgetKeys();
}

import 'package:flutter/widgets.dart';

class _ProductPageKey extends ValueKey<String> {
  const _ProductPageKey(String value) : super('productPage_$value');
}
class ProductPageKeys {
  final menuIconButton = const _ProductPageKey('menuIconButton');
  final productImage = const _ProductPageKey('productImage');
  final productName = const _ProductPageKey('productName');
}
class _ProductConnectingPageKey extends ValueKey<String> {
  const _ProductConnectingPageKey(String value)
    : super('productConnectingPage_$value');
}
class ProductConnectingPageKeys {
  final productImage = const _ProductConnectingPageKey('productImage');
  final productName = const _ProductConnectingPageKey('productName');
}

import 'package:flutter/widgets.dart';

class _WidgetKey extends ValueKey<String> {
  const _WidgetKey(String value) : super('widget_$value');
}
class WidgetKeys {
  final addButton = const _WidgetKey('addButton');
  _WidgetKey assetRow(String coinTitle) => _WidgetKey('assetRow_$coinTitle');
  _WidgetKey assetSlider(SelectAssetType type) =>
      _WidgetKey('assetSlider_$type');
  final cancelButton = const _WidgetKey('cancelButton');
  final pickCurrencyButton = const _WidgetKey('pickCurrencyButton');
  final saveButton = const _WidgetKey('saveButton');
  final searchBar = const _WidgetKey('searchBar');
  final topBarHeaderMiddleText = const _WidgetKey('topBarHeaderMiddleText');
}

import 'package:flutter/widgets.dart';
final widgetKeys = WidgetBookKeys();
class _WidgetBookKey extends ValueKey<String> {
  const _WidgetBookKey(String value) : super('widgetBook_$value');
}
class WidgetBookKeys {
  final tile = const _WidgetBookKey('tile');
}

import 'package:common_ui/widgets/keys.dart' as ds;
final keys = Keys();
class Keys {
  final widgetKeys = ds.widgetKeys;
}

enum SizeDTO {
  small,
  medium,
  large,
}

class PickSizeWidget extends StatelessWidget {
  Widget _sizeButton(SizeDTO size) {
    return _Button(
      key: keys.pickSize.sizeButton(size),
      value: size,
      currentValue: value,
      onPressed: onPressed,
    );
  }

  @override
  Widget build(BuildContext context) {
    return Row(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        _sizeButton(SizeDTO.small),
        _sizeButton(SizeDTO.medium),
        _sizeButton(SizeDTO.large),
      ].spaced(24),
    );
  }
}

  _PickSizeKey sizeButton(SizeDTO size) => _PickSizeKey('sizeButton_${size.name}');

Code Examples

Module Structure

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

final class Home extends Module {
  Home(super.$);

  Future<void> navigateToSettings() async {
    await $(keys.home.settingsButton).scrollTo().tap();
  }

  Future<void> searchForItem(String searchPhrase) async {
    await $(keys.home.searchButton).scrollTo().tap();
    await $(keys.home.searchInput).enterText(searchPhrase);
    await $(keys.home.searchSubmitButton).tap();
  }
}

final class Modules {
  Modules(this._$);
  final PatrolIntegrationTester _$;

  late final home = Home(_$);
  late final auth = Auth(_$);
}

System Class

final class System extends PlatformAutomator {
  System({required super.config});

  Future<void> checkIfNativePlayerIsVisible() async {
    // Implementation
  }
}

ApiClients Class

final class ApiClients {
  final backend = BackendClient();
  final mailpitClient = MailpitClient();
}

Complete Test Example

testApp('Download a chapter and play it offline', ($, modules, system, apiClients) async {
    await modules.auth.getAuthToken();
    await apiClients.backend.addFavourites();
    await openApp($);
    await modules.home.goToOldTestament();
    await modules.testament.expandBook(bookName: 'Book of Revelation');
    await modules.testament.chooseChapterOfBook(
      bookName: 'Book of Revelation',
      chapterIndex: 0,
    );
    await modules.player.expandChapters();
    await modules.player.downloadChapter(chapterIndex: 9);
    await modules.player.waitUntilDownloaded();
    // usage of a method from $.platform Equivalent of await $.platform.mobile.enableAirplaneMode();
    await system.enableAirplaneMode();
    await modules.player.rollDownChapters();
    await modules.player.closeChapterPlayer();
    await modules.testament.closeTestament();
    await modules.bottomNavigation.goToLibrary();
    await modules.library.goToDownloads();
    await modules.downloads.expandOldTestament();
    await modules.downloads.goToBook(bookName: 'Book of Revelation');
    await modules.player.checkIfChapterIsCorrect(chapterIndex: 0);
    await modules.player.playCurrentTrack();
    // usage of our method, which calls many methods from $.platform
    await system.checkIfNativePlayerIsVisible();
  });