Skip to main content

Execute Maestro Framework Tests on HyperExecute

This page outlines how to execute your Maestro tests on HyperExecute with YAML 0.2

Prerequisites​

To run the Tests on HyperExecute from your Local System, you are required:

Step 1: Setup Your Test Suite​

You can use your own project to configure and test it. For demo purposes, we are using the sample repository.

Sample repo

Download or Clone the code sample for the Maestro framework from the LambdaTest GitHub repository to run the tests on the HyperExecute. Image View on GitHub

Step 2: Setup the CLI in your Test Suite​

After cloning / downloading the sample repo, you need to setup the CLI and the environment variables.

Download the HyperExecute CLI​

The CLI is used for triggering the tests on HyperExecute. It is recommend to download the CLI binary on the host system and keep it in the root directory of the suite to perform the tests on HyperExecute.

You can download the CLI for your desired platform from the below mentioned links:

PlatformHyperExecute CLI
Windowshttps://downloads.lambdatest.com/hyperexecute/windows/hyperexecute.exe
MacOShttps://downloads.lambdatest.com/hyperexecute/darwin/hyperexecute
Linuxhttps://downloads.lambdatest.com/hyperexecute/linux/hyperexecute

Step 3: Upload your Application​

Upload your android application (.apk file) or iOS application (.ipa file) to the LambdaTest servers using our REST API. You need to provide your Username and AccessKey in the format Username:AccessKey in the cURL command for authentication.

info

Enter your local path of the code repository instead of <YOUR_LOCAL_APP_PATH> in the below cURL command.

curl -u "undefined:undefined" -X POST "https://manual-api.lambdatest.com/app/upload/realDevice" -F "appFile=@"<YOUR_LOCAL_APP_PATH>"" -F "name="sampleApp""

Response of above cURL will be a JSON object containing the App ID of the format - <APP123456789012345678901234567> and will be used in the next step.

Step 4: Configure YAML in your Test Suite​

Enter your APP_ID in the YAML file that you have fetched in the above step.

hyperexecute.yaml
loading...

Step 5: Generate JUnit XML Report​

  1. Update the runTest.sh file to include the --format junit flag in the maestro test command:
/home/ltuser/.maestro/bin/maestro test $1 --debug-output ./MaestroLogs --format junit

The above command will generate a report.xml file in the root directory after each test execution. Here is the complete reference of the runTest.sh file:

maestro-test/runTest.sh
loading...
  1. Update your HyperExecute YAML file to enable the native reporting in HyperExecute using the generated JUnit XML files.
hyperexecute.yaml
report: true
partialReports:
  - location: .
    type: xml
    frameworkName: junit

📘 Use Cases​

Use Case 1: One Test per Task​

If you're executing one test per task, a single report.xml will be generated per job. These individual reports can then be merged later for a consolidated result.

Use Case 2: Multiple Tests on the same Task​

In this case, the report.xml file gets overwritten after each test execution. This results in only the last test's results being preserved. To prevent overwriting, update your testRunnerCommand in the hyperexecute.yaml file to rename the report after each test:

hyperexecute.yaml
testRunnerCommand: ./maestro-test/runTest.sh $test && mv report.xml $test.xml

This ensures that each test result is saved with a unique name like test1.xml, test2.xml, etc.

Step 6: Execute your Test Suite​

NOTE : In case of MacOS, if you get a permission denied warning while executing CLI, simply run chmod u+x ./hyperexecute to allow permission. In case you get a security popup, allow it from your System Preferences → Security & Privacy → General tab.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE
JUnit HyperExecute Terminal Logs

Step 7: Monitor the Test Execution​

Visit the HyperExecute Dashboard and check your Job status.

automation-dashboard

Additional Information: Launching Pre-Installed Apps with Maestro​

In some cases, you may want to test against a pre-installed application on the device (instead of uploading and installing a new APK/IPA). Maestro supports this by allowing you to specify the app’s package identifier (Android) or bundle identifier (iOS) in your test configuration.

Step 1: Identify the App ID (Package Name / Bundle ID)​

For Android:​

  • Visit the app’s page on the Google Play Store.
  • The id parameter in the URL is the package name.
  • Example: For the Wikipedia app → org.wikipedia.

For iOS:​

  • Identify the bundle identifier (e.g., com.apple.Preferences for Settings).

Step 2: Update Your HyperExecute Configuration​

You can configure your YAML files to launch the pre-installed app instead of uploading a new one.

hyperexecute.yaml
...//
framework:
  name: raw
  args:
    appId: stock

and the launcher yaml file to tells maestro to use the pre-installed Wikipedia app.

android-launch.yaml
loading...

Step 3: Execute your Test Suite​

NOTE : In case of MacOS, if you get a permission denied warning while executing CLI, simply run chmod u+x ./hyperexecute to allow permission. In case you get a security popup, allow it from your System Preferences → Security & Privacy → General tab.

./hyperexecute --user undefined --key undefined --config RELATIVE_PATH_OF_YOUR_YAML_FILE

The Wikipedia app will open directly on the device, and your Maestro test steps will execute against it.

Example: Wikipedia Search Flow

android-launch.yaml
appId: org.wikipedia
----
launchApp

tapOn: "Search Wikipedia"
inputText: "Maestro framework"
pressKey: Enter
assertVisible: "Mobile UI testing"
Image

Explanation:

  • launchApp: Opens the Wikipedia app.
  • tapOn: "Search Wikipedia" → Focuses the search bar.
  • inputText: "Maestro framework" → Enters the text.
  • pressKey: Enter → Submits the search.
  • assertVisible: "Mobile UI testing" → Validates results.

Best Practices​

  • Make sure the app is already installed on the device; otherwise, Maestro cannot launch it.
  • The same approach works for iOS using the bundle identifier.
  • You can also switch between multiple apps in a single flow by providing different appId values in separate steps.
Last updated on

Test across 3000+ combinations of browsers, real devices & OS.

Book Demo

Help and Support

Related Articles