Maestro Navigator

Maestro Navigator is a VS Code extension that improves YAML-based Maestro flow authoring and is especially useful for navigating parent flows and subflows while running tests on both iOS and Android with a single editor workflow.

It is built to help QA and mobile teams move faster with clear flow intent, reliable path navigation, and one-click execution across platforms.

Core capabilities:

• Path link support (Cmd+Click)
• Go to Definition for local path references
• Hover previews for referenced files
• Diagnostics for broken file paths
• CodeLens run actions for Maestro flows
• Optional doctor checks before running tests
• Environment variable loading from env files

Features

1) YAML path intelligence

For configured YAML keys, the extension treats values as file paths.

• Click a path to open the target file
• Use Go to Definition on a path value
• Hover a path to see existence status and preview
• Get warnings when referenced files are missing

Default path keys:

• runFlow
• runScript
• evalScript
• loadEnv
• file
• image

2) Run Maestro directly from editor

On recognized Maestro flow YAML files, CodeLens actions appear at the top:

• Run Maestro Flow
• Run iOS
• Run Android
• Run Folder
• Run Workspace Flows
• Doctor

You can also run these from the Command Palette:

• Maestro: Run Current Flow
• Maestro: Run Current Flow (iOS)
• Maestro: Run Current Flow (Android)
• Maestro: Run Current Folder
• Maestro: Run Workspace Flows
• Maestro: Run Doctor Checks

3) Doctor checks

Before running flows, doctor checks can validate your local environment.

Supported checks:

• maestro
• java
• adb
• xcode
• androidDevice
• iosSimulator

Required checks failing can optionally stop test execution.

4) Env file support

When enabled, env files are read from workspace root and exported to Maestro command as -e key=value pairs.

• Files are loaded in order
• Later files override earlier files

Requirements

Install and configure these tools as needed by your platform:

• Maestro CLI
• Java (Java 17+ recommended)
• Android ADB tools (for Android runs)
• Xcode Command Line Tools (for iOS runs)
• Booted simulator/device when running platform-specific flows

Installation

Option A: Development install (local extension repo)

1. Open this extension folder in VS Code.
2. Press F5 to launch an Extension Development Host.
3. Open your Maestro test workspace in the new window.
4. Open a YAML flow file and use CodeLens or Command Palette actions.

Option B: Pack and install VSIX

1. Install vsce globally:

npm install -g @vscode/vsce

2. From this extension folder, create a VSIX:

vsce package

3. In VS Code, run command:

Extensions: Install from VSIX...

4. Select the generated VSIX file.

Quick Example

Example flow file:

appId: ${APP_BUNDLE_ID}
name: V2 Account Entry Scenarios
tags:
  - v2
  - onboarding
  - auth
---
- runFlow:
    file: flows/onboarding/account-entry.yaml
- tapOn:
  image: assets/onboarding/continue.png
- runScript: scripts/setup.js
- evalScript: scripts/assertions.js
- loadEnv: env/test.env

What you get:

• Path values are clickable
• Missing paths show warnings
• Hover shows target preview
• CodeLens run actions appear at top if file looks like a Maestro flow

Why Teams Use This

• Navigate nested subflows quickly with file and runFlow references
• Keep flow intent visible with hover previews and diagnostics
• Run the same flow on iOS and Android from one place
• Reduce context switching between YAML editing and terminal execution

Discoverability Keywords

Use these keywords in project descriptions, release notes, and social posts:

• maestro
• maestro flows
• maestro subflow
• mobile test automation
• ios automation
• android automation
• cross platform testing
• yaml flow navigation
• vscode extension
• qa productivity
• shift left testing
• ci friendly mobile tests

Add Images And Videos To README

Recommended media folders:

• assets/onboarding for images used by flow YAML
• docs/media for README videos and gifs

Settings

All settings are under the Maestro Navigator namespace.

Minimal settings example

Put this in your user or workspace settings.json:

{
  "maestroNavigator.pathKeys": [
    "runFlow",
    "runScript",
    "evalScript",
    "loadEnv",
    "file",
    "image"
  ],
  "maestroNavigator.flowIndicators": [
    "appId",
    "runFlow",
    "runScript",
    "onFlowStart",
    "onFlowComplete",
    "evalScript",
    "loadEnv"
  ],
  "maestroNavigator.terminalName": "Maestro Test"
}

Full settings example

{
  "maestroNavigator.pathKeys": [
    "runFlow",
    "runScript",
    "evalScript",
    "loadEnv",
    "file",
    "image"
  ],
  "maestroNavigator.flowIndicators": [
    "appId",
    "runFlow",
    "runScript",
    "onFlowStart",
    "onFlowComplete",
    "evalScript",
    "loadEnv"
  ],
  "maestroNavigator.terminalName": "Maestro Test",

  "maestroNavigator.run.currentFlowTemplate": "maestro test ${envArgs} \"${targetRelative}\"",
  "maestroNavigator.run.currentFlowIosTemplate": "maestro test ${envArgs} --platform ios \"${targetRelative}\"",
  "maestroNavigator.run.currentFlowAndroidTemplate": "maestro test ${envArgs} --platform android \"${targetRelative}\"",
  "maestroNavigator.run.currentFolderTemplate": "maestro test ${envArgs} \"${targetRelative}\"",
  "maestroNavigator.run.workspaceTemplate": "maestro test ${envArgs} .",

  "maestroNavigator.env.enabled": true,
  "maestroNavigator.env.files": [".env", ".env.local"],
  "maestroNavigator.env.fileEncoding": "utf8",

  "maestroNavigator.doctor.enabled": true,
  "maestroNavigator.doctor.runOnFirstRun": true,
  "maestroNavigator.doctor.stopRunOnFailure": false,
  "maestroNavigator.doctor.checks": [
    "maestro",
    "java",
    "adb",
    "xcode",
    "androidDevice",
    "iosSimulator"
  ],
  "maestroNavigator.doctor.showOutput": true
}

Run template variables

You can use these variables inside run templates:

• ${workspaceRoot}
• ${cwd}
• ${target}
• ${targetRelative}
• ${targetDir}
• ${targetDirRelative}
• ${envArgs}

Recommended settings pattern

Use workspace settings for project-specific run templates and env files:

• .vscode/settings.json for team defaults
• user settings for personal overrides

Example workspace-level command customization:

{
  "maestroNavigator.run.currentFlowTemplate": "maestro test ${envArgs} --format junit --output reports/junit.xml \"${targetRelative}\"",
  "maestroNavigator.run.workspaceTemplate": "maestro test ${envArgs} flows"
}

Troubleshooting

CodeLens does not appear

• Ensure the file is YAML
• Ensure it contains at least one configured flow indicator key
• Verify flowIndicators in settings

Path links do not work

• Ensure key is included in pathKeys
• Ensure the target path exists relative to the current YAML file

Doctor reports failures

• Install missing tools shown in doctor output
• For runtime checks, connect Android device/emulator or boot iOS simulator

Env values not applied

• Enable maestroNavigator.env.enabled
• Confirm env files exist in workspace root
• Check file encoding setting

Repository Structure

• extension.js: Extension runtime logic
• package.json: VS Code contribution points and settings schema
• README.md: Usage, settings, and media examples
• assets/onboarding: Image assets referenced by flows and docs
• docs/media: README demo media (mp4 and gif)

Governance

The project includes enterprise-ready governance and collaboration files:

• LICENSE
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• SECURITY.md
• CHANGELOG.md
• .github/ISSUE_TEMPLATE/bug_report.md
• .github/ISSUE_TEMPLATE/feature_request.md
• .github/pull_request_template.md

License

This project is licensed under the MIT License. See LICENSE for details.