Skip to content

Commit cd375e1

Browse files
eduardoborgeseduardoborges
authored
feat: add Maestro Flow JSON Schema (SchemaStore#5482)
Add schema for Maestro UI test YAML flows (app config + command list). Includes positive tests for flow header and command sequence. Docs: https://docs.maestro.dev/ Made-with: Cursor
1 parent 87da135 commit cd375e1

5 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎src/api/json/catalog.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4083,6 +4083,17 @@
40834083
"fileMatch": [".mado.toml", "mado.toml"],
40844084
"url": "https://raw.githubusercontent.com/akiomik/mado/refs/heads/main/pkg/json-schema/mado.json"
40854085
},
4086+
{
4087+
"name": "Maestro Flow",
4088+
"description": "Maestro mobile and web UI test flow (YAML)",
4089+
"fileMatch": [
4090+
"**/.maestro/**/*.yaml",
4091+
"**/.maestro/**/*.yml",
4092+
"**/*.flow.yaml",
4093+
"**/*.flow.yml"
4094+
],
4095+
"url": "https://www.schemastore.org/maestro-flow.json"
4096+
},
40864097
{
40874098
"name": "MapEHR Mapping",
40884099
"description": "Mapping for MapEHR.com",

‎src/schema-validation.jsonc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,7 @@
306306
// JSON schema 2019-09 and 2020-12 are not well supported by many IDEs and should not be used
307307
"jsone.json",
308308
"license-report-config.json",
309+
"maestro-flow.json",
309310
"openweather.current.json",
310311
"openweather.roadrisk.json",
311312
"openhab-5.1.json",

‎src/schemas/json/maestro-flow.json‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://json.schemastore.org/maestro-flow.json",
4+
"$defs": {
5+
"flowConfiguration": {
6+
"type": "object",
7+
"additionalProperties": true,
8+
"properties": {
9+
"appId": {
10+
"type": "string",
11+
"title": "Application ID",
12+
"description": "Android package name or iOS bundle ID under test. May use ${ENV_VAR} interpolation.",
13+
"examples": ["com.example.app", "${APP_ID}"]
14+
},
15+
"url": {
16+
"type": "string",
17+
"title": "Web URL under test",
18+
"description": "For web flows, the starting URL (see Maestro web testing docs).",
19+
"format": "uri"
20+
},
21+
"name": {
22+
"type": "string",
23+
"description": "Human-readable flow name for reports."
24+
},
25+
"tags": {
26+
"type": "array",
27+
"items": { "type": "string" },
28+
"description": "Tags for filtering and organization."
29+
},
30+
"env": {
31+
"type": "object",
32+
"additionalProperties": { "type": "string" },
33+
"description": "Default environment variables for this flow (${VAR_NAME} in commands)."
34+
},
35+
"onFlowStart": {
36+
"$ref": "#/$defs/commandList",
37+
"description": "Commands run before the main flow body; failure fails the flow."
38+
},
39+
"onFlowComplete": {
40+
"$ref": "#/$defs/commandList",
41+
"description": "Commands run after the main flow (e.g. teardown)."
42+
}
43+
}
44+
},
45+
"commandList": {
46+
"type": "array",
47+
"items": { "$ref": "#/$defs/commandStep" },
48+
"description": "Sequence of Maestro commands executed in order."
49+
},
50+
"commandStep": {
51+
"oneOf": [
52+
{
53+
"$ref": "#/$defs/bareCommandName",
54+
"description": "Shorthand step with no parameters (YAML scalar list item)."
55+
},
56+
{
57+
"$ref": "#/$defs/commandObject",
58+
"description": "Single-key object: command name -> arguments map, string, or null."
59+
}
60+
]
61+
},
62+
"bareCommandName": {
63+
"type": "string",
64+
"title": "Bare command",
65+
"description": "Commands that need no argument object. Maestro accepts many more; list is indicative.",
66+
"examples": [
67+
"launchApp",
68+
"hideKeyboard",
69+
"back",
70+
"stopApp",
71+
"clearState",
72+
"clearKeychain",
73+
"waitForAnimationToEnd",
74+
"takeScreenshot",
75+
"startRecording",
76+
"stopRecording"
77+
]
78+
},
79+
"commandObject": {
80+
"type": "object",
81+
"minProperties": 1,
82+
"maxProperties": 1,
83+
"additionalProperties": {
84+
"$ref": "#/$defs/commandValue"
85+
},
86+
"propertyNames": {
87+
"type": "string",
88+
"description": "Maestro command name (typically camelCase, e.g. tapOn, runFlow)."
89+
}
90+
},
91+
"commandValue": {
92+
"title": "Command arguments",
93+
"description": "Depends on the command: omitted/null, boolean, string selector, number, array of nested steps, or parameter object.",
94+
"oneOf": [
95+
{ "type": "null" },
96+
{ "type": "boolean" },
97+
{ "type": "number" },
98+
{ "type": "string" },
99+
{ "type": "array", "items": { "$ref": "#/$defs/commandStep" } },
100+
{ "$ref": "#/$defs/argumentMap" }
101+
]
102+
},
103+
"argumentMap": {
104+
"type": "object",
105+
"additionalProperties": true,
106+
"description": "Command-specific parameters. Commands: https://docs.maestro.dev/reference/commands-available/ — Selectors: https://docs.maestro.dev/reference/selectors — Conditions (when): https://docs.maestro.dev/maestro-flows/flow-control-and-logic/conditions — runFlow: https://docs.maestro.dev/reference/commands-available/runflow — launchApp: https://docs.maestro.dev/reference/commands-available/launchapp — extendedWaitUntil: https://docs.maestro.dev/reference/commands-available/extendedwaituntil"
107+
}
108+
},
109+
"title": "Maestro Flow",
110+
"description": "YAML flow file for Maestro (mobile & web UI automation). A single file is usually two YAML documents separated by ---: (1) flow configuration, (2) command list. Assign this schema to *.flow.yaml or **/.maestro/**/*.yaml. Official docs: https://docs.maestro.dev/",
111+
"oneOf": [
112+
{
113+
"$ref": "#/$defs/flowConfiguration",
114+
"description": "First document: app/url, env, tags, hooks."
115+
},
116+
{
117+
"$ref": "#/$defs/commandList",
118+
"description": "Second document: ordered list of Maestro commands."
119+
}
120+
]
121+
}

‎src/test/maestro-flow/flow-commands.yaml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# yaml-language-server: $schema=../../schemas/json/maestro-flow.json
2+
- launchApp:
3+
clearState: true
4+
- extendedWaitUntil:
5+
visible:
6+
id: sign_in
7+
timeout: 30000
8+
- tapOn:
9+
id: sign_in
10+
- inputText: user@example.test
11+
- hideKeyboard
12+
- assertVisible: Home
13+
- runFlow:
14+
label: dismiss onboarding
15+
when:
16+
visible: Skip
17+
commands:
18+
- tapOn: Skip

‎src/test/maestro-flow/flow-header.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# yaml-language-server: $schema=../../schemas/json/maestro-flow.json
2+
appId: com.example.maestro
3+
name: sample flow
4+
tags:
5+
- e2e
6+
env:
7+
API_URL: https://api.example.test

0 commit comments

Comments
 (0)