Set up Flutter for iOS apps

When testing your Flutter application with Perfecto, the following assumptions apply:

  • You build your own application based on the iOS Device Testing instructions.

  • Running the Perfecto Gradle Plugin is best done outside of the source code folder. The application can reside in the cloud, in Git/NAS, and so on.

  • Running the Perfecto Gradle Plugin requires Gradle.

  • You reference the build.gradle file and the JSON config file through CLI params. The example in this article implies both files reside in the same directory. If they reside in different directories, some changes in the configuration are required.

Watch this video to see a demo of the Perfecto-Flutter integration setup for iOS. Detailed steps follow.

Important: This document includes references to a third-party product, Apple Xcode. The user interface and usage of third-party products are subject to change without notice. For the latest published information about Apple Xcode, see


Before you get started, make sure you have installed the following:

  • Gradle
  • Java
  • Flutter
  • Gradle plugin

    You can download the Gradle Plugin either automatically, after adding the required lines of code to the build.gradle file, as described in step 2 below, or, if your organization does not permit direct download, by pre-downloading it to a local libs folder (see also Install the Perfecto Gradle plugin manually).

  • A cloud device with iOS 14 or later

1 | Get started

To get started, you need to create an .ipa file following the iOS Device Testing instructions.

Flutter uses the 'hosted test module' XCTest architecture, which involves the application .ipa file that includes the integration tests.

In this step, you prepare this file.

To create the file and convert it to an .ipa file:

  1. In Apple Xcode, change the scheme destination to Generic iOS device.

  2. Click Product > Build For > Testing. When this is complete, open up the Organizer and select the latest version.

  3. Right-click the generated .app file in the Project Navigator (in the Products folder) and select Show in Finder.

    Finder displays the path to the Products folder and shows the package.

  4. To automatically convert the .app files to an.ipa file, supply the path to the appPath configuration parameters. The Gradle plugin will convert it to an .ipa file.

    Alternatively, you can also convert each file manually, as follows:

    1. Create an empty Payload (case sensitive) folder and copy the .app bundle to this folder.

      If the Payload folder already exists, delete it and create a new, empty folder.

    2. Right-click the Payload folder and compress it to a .zip file.
    3. Rename the .zip file to <testName>.ipa.

When you have the .ipa file, you can upload it to the Perfecto Repository or keep it on your local machine. Both scenarios will be covered in the following steps.

2 | Configure the Perfecto client environment

In this step, we prepare the following files:

  • A build.gradle file that specifies the required Perfecto dependencies

  • A JSON configuration file that holds all Perfecto configurations, including security information, the Perfecto cloud name, Smart Reporting settings, and test data

The following procedure walks you through the configuration. Expand a step to view its content.

3 | Run the plugin and view the report

In this step, you run the Perfecto Gradle plugin and viewing the test report in Perfecto.

Expand a step to view its content.

Proxy connection

If you run the Gradle plugin over a proxy connection, you can supply the proxy information as follows:

  • As Java parameters when activating the plugin. You can use the same Java Proxy parameters also for proxies supporting SSL encryption.

    http.proxyHost: The IP address of the proxy

    http.proxyPort: The IP port used for the connection

    http.proxyUser: The username for connecting to the proxy server

    http.proxyPassword: The password for connecting to the proxy server

    For example:

    gradlew perfecto-android-inst -DconfigFileLocation=configFile.json -Dhttp.proxyHost= -Dhttp.proxyPort=8800 -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword
  • As parameters defined explicitly in the file. For example: