Summarize with:ChatGPTPerplexityGrokClaude

Last updated on : 16 May 2026

Integrating Maestro with Pcloudy

Overview

Maestro is a modern, open-source mobile UI testing framework developed by Mobile.dev. It is designed to be simple, fast, and reliable — enabling QA engineers, developers, and product teams to write end-to-end UI tests for iOS and Android applications using a human-readable YAML-based syntax, with zero boilerplate code.

Unlike traditional automation frameworks that require deep programming knowledge, Maestro allows testers to define user flows in plain English-like instructions. A test flow describing a login, navigation, and form submission can be written in under 10 lines of YAML and executed against any real device.

1. What Makes Maestro Different

Capability	Description
YAML-based flows	Test cases are written in human-readable YAML — no programming experience required.
Built-in waiting	Maestro automatically waits for elements to appear; no explicit waits or sleep() calls needed.
Resilient execution	Handles flaky UI states, animations, and loading spinners gracefully without test failures.
Fast iteration	Tests can be run, edited, and re-run instantly from the command line without rebuilding.
No instrumentation	Works with any app (native, React Native, Flutter, Xamarin) without modifying the app's code.
Visual output	Generates screenshots and video recordings at each step for easy debugging.
Multi-platform	Single flow syntax for both iOS and Android apps.

2. Key Features

2.1 Core Capabilities

• YAML Flow Syntax: Write test steps in plain YAML using commands like tapOn, inputText, assertVisible, and scrollUntilVisible.
• Element Matching: Locate UI elements by text, accessibility ID, index, or a combination of these without relying on XPath or complex selectors.
• Subflows: Reuse common sequences (e.g., login, navigation) as subflows across multiple test files.
• JavaScript Integration: Execute custom JavaScript for dynamic data generation, assertions, and conditional logic.
• Environment Variables: Pass runtime parameters (usernames, passwords, URLs) without hardcoding values.
• Screenshots & Recordings: Automatically capture screen state at each command step for debugging.
• Continuous Mode: Use maestro test --continuous to auto-re-run tests when flow files are saved.
• Maestro Cloud: Upload flows to Maestro Cloud or integrate with Pcloudy for execution on real device fleets.

2.2 Supported Actions

Category	Command	Description
Gestures	tapOn	Tap a UI element by text, id, or coordinates.
Gestures	longPressOn	Long press on an element for contextual menus.
Gestures	swipe	Swipe in a direction (UP, DOWN, LEFT, RIGHT).
Gestures	scroll	Scroll the current view.
Gestures	scrollUntilVisible	Scroll until a specific element comes into view.
Input	inputText	Type text into the focused field.
Input	pressKey	Simulate key presses (Enter, Back, Home).
Input	clearKeychain	Clear iOS keychain for clean test state.
Assertion	assertVisible	Assert that an element is visible on screen.
Assertion	assertNotVisible	Assert that an element is NOT visible.
Navigation	openLink	Open a URL or deep link.
Navigation	back	Simulate pressing the Back button.
App	launchApp	Launch the application under test.
App	stopApp	Stop the running application.
App	clearState	Clear app data / reset app to fresh state.
Flow	runFlow	Execute a subflow YAML file inline.
Flow	runScript	Execute a JavaScript file for custom logic.

3. Pre-Requisites

Before you can use Maestro with Pcloudy's real device infrastructure, the following requirements must be met. Please read this section carefully and ensure all conditions are satisfied before proceeding with setup.

warning

Important

• All users must have an active, registered account on the Pcloudy platform before attempting to run
• Maestro flows on real devices.
• Limitation:Supported on Android only

3.1 Pcloudy Platform Registration

User must be registered on the Pcloudy platform. This is a mandatory prerequisite — without a valid account, you cannot access real devices, generate API tokens, or execute Maestro flows remotely.

1. Visit https://www.pcloudy.com and click Sign Up.
2. Complete the registration form with your work email address, name, and organization.
3. Verify your email address by clicking the confirmation link sent to your inbox.
4. Log in to the Pcloudy dashboard and confirm your account is active.
5. Navigate to your Profile → API Token and generate or copy your API access token. This token is required for all Maestro CLI integrations.
6. Navigate to Tool section and click on Maestro

3.2 Pcloudy Account Privileges Required

• Device Booking access: Permission to book iOS and Android devices on Pcloudy.
• App Management: Permission to upload and manage .ipa / .apk files in the Pcloudy App Store.
• API Access: Enabled API token in your profile for CLI-based test execution.
• Maestro Feature Flag: Maestro integration must be enabled on your Pcloudy subscription plan. Contact support@Pcloudy.com if not visible in your dashboard.

4. Getting Started with Pcloudy + Maestro

4.1 Step 1 — Log In and Get Your API Token

1. Log in to https://www.pcloudy.com
2. Click on your Profile icon (top-right corner) → select API Token.
3. Copy the API token. You will use this in the Maestro CLI configuration.

4.2 Step 2 — Upload Your App to Pcloudy

1. In the Pcloudy dashboard, to MyData(left sidebar).
2. Click Upload App.navigate
3. Select your (.apk (Android) file and upload it.
4. Once uploaded, appname will be shown — you will need this when writing Maestro flows.
5. On the uploaded app you can perform below action
   1. Download
   2. Duplicate
   3. Delete
6. You can copy the script also if required

4.3 Step 3 — Book a Real Device

1. Choose the app
2. Write the script
3. Click on Execute ,a pop up will appear
4. Choose the cloud, Device, app and select the required setting as per your requiremnet
5. Confirm the booking. You will see live view execution

5. Writing Your First Maestro Flow

5.1 Flow File Structure

A Maestro flow is a YAML file with a .yaml extension. It begins with an appId declaration followed by a list of commands. Below is the structure of a minimal flow:

appId: com.example.myapp 

--- 

- launchApp 

- tapOn: 

    text: "Login" 

- inputText: "user@example.com" 

- tapOn: 

    text: "Password" 

- inputText: "mysecretpassword" 

- tapOn: 

    text: "Sign In" 

- assertVisible: 

    text: "Welcome" 

5.2 Common Flow Commands

Command	Example Usage
launchApp	- launchApp (launches the app defined in appId)
tapOn (by text)	- tapOn:\n text: "Submit"
tapOn (by id)	- tapOn:\n id: "btn_submit"
inputText	- inputText: "Hello World"
assertVisible	- assertVisible:\n text: "Dashboard"
scrollUntilVisible	- scrollUntilVisible:\n text: "Load More"
runFlow (subflow)	- runFlow: ./login.yaml
takeScreenshot	- takeScreenshot: step_01_home

5.3 Using Environment Variables

Never hardcode credentials or environment-specific values. Pass them as environment variables:

appId: ${APP_ID} 

--- 

- launchApp 

- tapOn: 

    text: "Username" 

- inputText: ${TEST_USERNAME} 

Run the flow with injected variables:

maestro test --env APP_ID=com.example.app --env TEST_USERNAME=qa@test.com login_flow.yaml 

5.4 Viewing Results

• Maestro generates a detailed test report after execution.
• Screenshots are captured at each step and stored and you can see it in the generated report.
• On Pcloudy, test reports and session recordings are also accessible in the Maestro ->View Reports

5.5 Troubleshooting Common Errors

Error	Likely Cause	Resolution
App not found	appId mismatch	Verify appId matches the exact bundle ID / package name of the uploaded app.
Element not found	UI not loaded yet	Add assertVisible before interacting; Maestro auto-waits but verify element text matches exactly.
Connection refused	Device not booked	Ensure you have an active device booking on Pcloudy before running.
API tk=oken invalid	Wrong or expired token	Re-generate your API token from Pcloudy Profile → API Token.
Timeout waiting for app	App launch too slow	Add - launchApp:\n stopApp: true to kill previous sessions before launching.
Subflow not found	Incorrect relative path	Use paths relative to the root flow file location; avoid absolute paths.

6. Best Practices

6.1 Flow Design

• Keep each flow focused on a single user journey (e.g., login, checkout, profile update). Do not combine unrelated scenarios in one file.
• Use run Flow to extract reusable sequences (e.g., login steps) as subflows and reference them across test files.
• Use assertVisible after every critical navigation step to guard against silent failures.
• Avoid using coordinates (tapOn: point: [x,y]) — they break on different screen sizes. Prefer text or accessibility ID.

6.2 Credentials & Environment

• Always use environment variables for usernames, passwords, API keys, and base URLs — never commit credentials to source control.
• Create a .env.test file locally and use a secrets manager (AWS Secrets Manager, GitHub Secrets) in CI.

7. Support & Resources

7.1 Pcloudy Support

Email - support@pcloudy.com

Documentation - Pcloudy/Docs

7.2 Maestro Resources

Resource	URL
Official Documentation	https://maestro.mobile.dev/docs
GitHub Repository	https://github.com/mobile-dev-inc/maestro
YAML Flow Reference	https://maestro.mobile.dev/api-reference/commands
Sample Flows	https://github.com/mobile-dev-inc/maestro/tree/main/examples

info

Info - Need Help Getting Started? If this is your first time using Maestro on Pcloudy, contact support@Pcloudy.com to schedule a free onboarding call. Our team will walk you through account setup, device booking, and running your first Maestro flow on a real device.

8. Glossary

Term	Definition
Flow	A YAML file containing a sequence of Maestro commands that represent a user journey.
Subflow	A reusable flow file referenced from another flow using the runFlow command.
appID	The bundle identifier (iOS) or package name (Android) of the app under test.
Accessibility ID	A unique identifier assigned to UI elements by developers for testing purposes.
Pcloudy API Token	A personal authentication token used to authenticate Maestro CLI with Pcloudy's device farm.
Device Booking	Reserving a specific physical device on the Pcloudy platform for a test session.
Test Report	Automatically generated HTML/JSON report containing step screenshots and pass/fail status.