Getting started

1. Go to android/app/src/androidTest/java/com/example/myapp/ in your project directory. If there are no such folders, create them. Remember to replace /com/example/myapp/ with the path created by your app's package name.

2. Create a file named MainActivityTest.java and copy there the code below.

package com.example.myapp; // replace "com.example.myapp" with your app's package

import androidx.test.platform.app.InstrumentationRegistry;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.junit.runners.Parameterized;
import org.junit.runners.Parameterized.Parameters;
import pl.leancode.patrol.PatrolJUnitRunner;

@RunWith(Parameterized.class)
public class MainActivityTest {
    @Parameters(name = "{0}")
    public static Object[] testCases() {
        PatrolJUnitRunner instrumentation = (PatrolJUnitRunner) InstrumentationRegistry.getInstrumentation();
        // replace "MainActivity.class" with "io.flutter.embedding.android.FlutterActivity.class" 
        // if your AndroidManifest is using: android:name="io.flutter.embedding.android.FlutterActivity"
        instrumentation.setUp(MainActivity.class);
        instrumentation.waitForPatrolAppService();
        return instrumentation.listDartTests();
    }

    public MainActivityTest(String dartTestName) {
        this.dartTestName = dartTestName;
    }

    private final String dartTestName;

    @Test
    public void runDartTest() {
        PatrolJUnitRunner instrumentation = (PatrolJUnitRunner) InstrumentationRegistry.getInstrumentation();
        instrumentation.runDartTest(dartTestName);
    }
}

3. Go to the build.gradle file, located in android/app folder in your project directory.

4. Add these 2 lines to the defaultConfig section:

  testInstrumentationRunner "pl.leancode.patrol.PatrolJUnitRunner"
  testInstrumentationRunnerArguments clearPackageData: "true"

5. Add this section to the android section:

  testOptions {
    execution "ANDROIDX_TEST_ORCHESTRATOR"
  }

6. Add this line to dependencies section:

  androidTestUtil "androidx.test:orchestrator:1.4.2"

1. Open ios/Runner.xcworkspace in Xcode.

2. Create a test target if you do not already have one (see the screenshot below for the reference). Select File > New > Target... and select UI Testing Bundle. Change the Product Name to RunnerUITests. Set the Organization Identifier to be the same as for the Runner (no matter if you app has flavors or not). For our example app, it's com.example.MyApp just as in the pubspec.yaml file. Make sure Target to be Tested is set to Runner and language is set to Objective-C. Select Finish.

3. 2 files are created: RunnerUITests.m and RunnerUITestsLaunchTests.m. Delete RunnerUITestsLaunchTests.m through Xcode by clicking on it and selecting Move to Trash.

4. Make sure that the iOS Deployment Target of RunnerUITests within the Build Settings section is the same as Runner. The minimum supported iOS Deployment Target is 11.0. For the example app, we set it to 13.0 because it's required by the app dependencies.

5. Replace contents of RunnerUITests.m file with the following:

@import XCTest;
@import patrol;
@import ObjectiveC.runtime;

PATROL_INTEGRATION_TEST_IOS_RUNNER(RunnerUITests)

Add the newly created target to ios/Podfile by embedding in the existing Runner target.

target 'Runner' do
  # Do not change existing lines.
  ...

  target 'RunnerUITests' do
    inherit! :complete
  end
end

6. Create an empty file integration_test/example_test.dart in the root of your Flutter project. From the command line, run the following command and make sure it completes with no errors:

$ flutter build ios --config-only integration_test/example_test.dart

7. Go to your ios directory and run:

$ pod install --repo-update

8. Open your Xcode project and Make sure that for each build configuration, the RunnerUITests have the same Configuration Set selected as the Runner:

9. Go to RunnerUITests -> Build Phases and add 2 new "Run Script Phase" Build Phases. Name them xcode_backend build and xcode_backend embed_and_thin.

10. Arrange the newly created Build Phases in the order shown in the screenshot below.

11. Paste this code into the xcode_backend build Build Phase:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" build

12. Paste this code into the xcode_backend embed_and_thin Build Phase:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/xcode_backend.sh" embed_and_thin

13. Xcode by default also enables a "parallel execution" setting, which breaks Patrol. Disable it for all schemes (if you have more than one):

14. Go to RunnerUITests -> Build Settings, search for User Script Sandboxing and make sure it's set to No.

1. Open macos/Runner.xcworkspace in Xcode.

2. Create a test target if you do not already have one via File > New > Target... and select UI Testing Bundle. Change the Product Name to RunnerUITests. Make sure Target to be Tested is set to Runner and language is set to Objective-C. Select Finish.

3. 2 files are created: RunnerUITests.m and RunnerUITestsLaunchTests.m. Delete RunnerUITestsLaunchTests.m through Xcode.

4. Make sure that the macOS Deployment Target of RunnerUITests within the Build Settings section is the same as Runner. The minimum supported macOS Deployment Target is 10.14.

5. Replace contents of RunnerUITests.m file with the following:

@import XCTest;
@import patrol;
@import ObjectiveC.runtime;

PATROL_INTEGRATION_TEST_MACOS_RUNNER(RunnerUITests)

Add the newly created target to macos/Podfile by embedding in the existing Runner target.

target 'Runner' do
  # Do not change existing lines.
  ...

  target 'RunnerUITests' do
    inherit! :complete
  end
end

6. Create an empty file integration_test/example_test.dart in the root of your Flutter project. From the command line, run:

$ flutter build macos --config-only integration_test/example_test.dart

7. Go to your macos directory and run:

$ pod install --repo-update

8. Go to RunnerUITests -> Build Phases and add 2 new "Run Script Phase" Build Phases. Rename them to xcode_backend build and xcode_backend embed_and_thin by double clicking on their names.

9. Arrange the newly created Build Phases in the order shown in the screenshot below.

10. Paste this code into the first macos_assemble build Build Phase:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/macos_assemble.sh" build

11. Paste this code into the second macos_assemble embed Build Phase:

/bin/sh "$FLUTTER_ROOT/packages/flutter_tools/bin/macos_assemble.sh" embed

12. Xcode by default also enables a "parallel execution" setting, which breaks Patrol. Disable it for all schemes (if you have more than one):

13. Go to RunnerUITests -> Build Settings, search for User Script Sandboxing and make sure it's set to No.

14. Go to Runner -> Signing & Capabilities. Make sure that in all App Sandbox sections, Incoming Connections (Server) and Outgoing Connections (Client) checkboxes are checked.

15. Copy DebugProfile.entitlements and Release.entitlements files from macos/Runner to macos/RunnerUITests directory.

16. Go to RunnerUITests -> Build Settings and set Code Signing Entitlements to RunnerUITests/DebugProfile.entitlements for Debug and Profile configuration and to RunnerUITests/Release.entitlements for Release configuration.

The reason is probably a mismatch of patrol and patrol_cli versions. Go to Compatibility table and make sure that the versions of patrol and patrol_cli you are using are compatible.

To run your application within the patrol test, you need to call $.pumpWidgetAndSettle(), and pass your application's main widget to it. Be sure that you registered all the necessary services before calling $.pumpWidgetAndSettle(). Here's the example of running an app within the patrol test:

void main() {
  patrolTest('real app test', ($) async {

  // Do all the necessary setup here (DI, services, etc.)

  await $.pumpWidgetAndSettle(const MyApp()); // Your's app main widget

  // Start testing your app here

  });
}

It's a good practice to create a setup wrapper function for your tests, so you don't have to repeat the same code in every test. Look at the example of a wrapper function.

Go to android/app/build.gradle and look for applicationId in defaultConfig section.

It's most likely caused by using incompatible JDK version. Run javac -version to check your JDK version. Patrol officially works on JDK 17, so unexpected errors may occur on other versions. If you have AndroidStudio or Intellij IDEA installed, you can find the path to JDK by opening your project's android directory in AS/Intellij and going to Settings -> Build, Execution, Deployment -> Build Tools -> Gradle -> Gradle JDK. Learn more

For iOS go to ios/Runner.xcodeproj/project.pbxproj and look for PRODUCT_BUNDLE_IDENTIFIER. For macOS go to macos/Runner.xcodeproj/project.pbxproj and look for PRODUCT_BUNDLE_IDENTIFIER.

Make sure that you disabled "Paralell execution" for all schemes in Xcode. See this video for details.

Open your XCode project, go to Runner target -> Build Settings, search for FLUTTER_TARGET and remove set path to targets for all configurations. Alternatively, you can search for a FLUTTER_TARGET in your project files and remove it (both value and key) from *.xcconfig and *.pbxproj files.

Open your XCode project, go to Runner target -> Build Settings, search for FLUTTER_TARGET and remove set path to targets for all configurations. Alternatively, you can search for a FLUTTER_TARGET in your project files and remove it (both value and key) from *.xcconfig and *.pbxproj files.

Check if this line in Podfile is present and uncommented.

platform :ios, '11.0'

If yes, then check if iOS deployment version in Xcode project's Build Settings section for all targets (Runner and RunnerUITests) are set to the same value as in Podfile (in case presented in snippet above, all should be set to 11.0).