Repository navigation
Conversation
|
End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator ( REST Endpoint Evidence — Driver: `devicelab` (Android default)
1. Server readinessGET /statusHTTP/1.1 200 OK
{"sessions":0,"status":"ok"}2. Create session (device: DeviceLab driver starts on demand)POST /session
Content-Type: application/json
{"platformName":"android","deviceId":"emulator-5554","appId":"com.google.android.contacts"}HTTP/1.1 200 OK
{"sessionId":"cb86147ba156d7f801ebe4c5f8025620"}Server trace: Server-side driver log: 3. Launch the Contacts appPOST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"launchApp","appId":"com.google.android.contacts"}HTTP/1.1 200 OK
{"success":true,"duration":434246334,"message":"Launched app: com.google.android.contacts"}4. Assert the app's main screenPOST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Search"}HTTP/1.1 200 OK
{"success":true,"duration":3191309833,"message":"Element is visible","element":{"bounds":{"x":53,"y":84,"width":126,"height":126},"visible":true,"enabled":true}}5. Fetch UI hierarchyGET /session/cb86147ba156d7f801ebe4c5f8025620/sourceHTTP/1.1 200 OK
Content-Type: application/json
<?xml version='1.0' encoding='UTF-8' ?><hierarchy rotation="0"><node class="android.widget.FrameLayout" bounds="[0,0][1080,63]" displayed="true" ... >…(full XML hierarchy returned; excerpt shown — element scan confirmed 6. Open the "Create contact" formPOST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"tapOn","selector":"Create contact"}HTTP/1.1 200 OK
{"success":true,"duration":1055722959,"message":"Tapped on element","element":{"bounds":{"x":870,"y":1962,"width":147,"height":147},"visible":true,"enabled":true}}POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"assertVisible","selector":"First name"}HTTP/1.1 200 OK
{"success":true,"duration":162598666,"message":"Element is visible","element":{"text":"First name","bounds":{"x":137,"y":793,"width":796,"height":154},"visible":true,"enabled":true}}7. Type the contact name (object-form selector + step payload)POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"inputText","selector":{"text":"First name"},"text":"REST API"}HTTP/1.1 200 OK
{"success":true,"duration":114291250,"message":"Entered text: REST API"}POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Save"}HTTP/1.1 200 OK
{"success":true,"duration":262799834,"message":"Element is visible","element":{"text":"Save","bounds":{"x":723,"y":83,"width":231,"height":126},"visible":true,"enabled":true}}8. Save the contactPOST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json
{"type":"tapOn","selector":"Save"}HTTP/1.1 200 OK
{"success":true,"duration":745340667,"message":"Tapped on element","element":{"text":"Save","bounds":{"x":723,"y":83,"width":231,"height":126},"visible":true,"enabled":true}}9. Failure path: step returns
|
|
End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator ( REST Endpoint Evidence — Driver: `uiautomator2`
1. Server readinessGET /statusHTTP/1.1 200 OK
{"sessions":0,"status":"ok"}2. Create session with the UIAutomator2 driver flagPOST /session
Content-Type: application/json
{"platformName":"android","deviceId":"emulator-5554","driver":"uiautomator2"}HTTP/1.1 200 OK
{"sessionId":"de5f6f545f98fe7fec4b9ebb0a71be05"}Server trace: Server-side driver log: 3. Launch the Contacts appPOST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"launchApp","appId":"com.google.android.contacts"}HTTP/1.1 200 OK
{"success":true,"duration":1859973750,"message":"Launched app: com.google.android.contacts"}4. Assert the app's main screenPOST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Search"}HTTP/1.1 200 OK
{"success":true,"duration":143110375,"message":"Element is visible","element":{"id":"00000000-0000-0025-ffff-ffff0000002e","bounds":{"x":0,"y":0,"width":0,"height":0},"visible":true,"enabled":true}}5. Open the "Create contact" formPOST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"tapOn","selector":"Create contact"}HTTP/1.1 200 OK
{"success":true,"duration":3074978500,"message":"Tapped on element","element":{"id":"00000000-0000-0025-ffff-ffff0000000b","bounds":{"x":870,"y":1962,"width":147,"height":147},"visible":true,"enabled":true}}POST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"assertVisible","selector":"First name"}HTTP/1.1 200 OK
{"success":true,"duration":35708667,"message":"Element is visible","element":{"id":"00000000-0000-0029-ffff-ffff000000ec","bounds":{"x":0,"y":0,"width":0,"height":0},"visible":true,"enabled":true}}6. Type the contact name (object-form selector + step payload)POST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"inputText","selector":{"text":"First name"},"text":"UIA2 Driver"}HTTP/1.1 200 OK
{"success":true,"duration":10073268292,"message":"Entered text: UIA2 Driver"}POST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Save"}HTTP/1.1 200 OK
{"success":true,"duration":100836458,"message":"Element is visible","element":{"id":"00000000-0000-0029-ffff-ffff0000029d","bounds":{"x":0,"y":0,"width":0,"height":0},"visible":true,"enabled":true}}7. Save the contactPOST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"tapOn","selector":"Save"}HTTP/1.1 200 OK
{"success":true,"duration":98777584,"message":"Tapped on element","element":{"id":"00000000-0000-0029-ffff-ffff0000029d","text":"Save","bounds":{"x":723,"y":83,"width":231,"height":126},"visible":true,"enabled":true}}8. Verify the created contactPOST /session/de5f6f545f98fe7fec4b9ebb0a71be05/execute
Content-Type: application/json
{"type":"assertVisible","selector":"UIA2 Driver"}HTTP/1.1 200 OK
{"success":true,"duration":42746833,"message":"Element is visible","element":{"id":"00000000-0000-0025-ffff-ffff000002be","bounds":{"x":0,"y":0,"width":0,"height":0},"visible":true,"enabled":true}}Server traces for the execute sequence: 9. Device infoGET /session/de5f6f545f98fe7fec4b9ebb0a71be05/device-infoHTTP/1.1 200 OK
{"platform":"android","osVersion":"35","deviceName":"google sdk_gphone64_arm64","deviceId":"emulator-5554","isSimulator":true,"screenWidth":1080,"screenHeight":2424}10. Session teardownDELETE /session/de5f6f545f98fe7fec4b9ebb0a71be05HTTP/1.1 204 No ContentServer trace: Result✅ Full create → 9-step create-contact flow (100% |
|
End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator ( REST Endpoint Evidence — Driver: `appium`
1. Server readiness (runner + Appium)GET /status (runner, :9999)HTTP/1.1 200 OK
{"sessions":0,"status":"ok"}GET /status (Appium, :4723 — dependency check, not part of the runner API)HTTP/1.1 200 OK
{"value":{"ready":true,"message":"The server is ready to accept new connections","build":{"version":"3.5.2"}}}2. Create session with the Appium driver flagPOST /session
Content-Type: application/json
{"platformName":"android","deviceId":"emulator-5554","appId":"com.google.android.contacts","driver":"appium"}HTTP/1.1 200 OK
{"sessionId":"264715c12d32b7c438e7ebe34c32eb79"}Server trace: Server-side driver log: 3. Launch the Contacts appPOST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"launchApp","appId":"com.google.android.contacts"}HTTP/1.1 200 OK
{"success":true,"duration":1179341666,"message":"Launched app: com.google.android.contacts"}4. Assert the app's main screenPOST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Search"}HTTP/1.1 200 OK
{"success":true,"duration":1759043958,"message":"Element is visible: Search","element":{"text":"Search","bounds":{"x":53,"y":84,"width":126,"height":126},"visible":true,"enabled":true,"class":"android.widget.ImageButton"}}5. Open the "Create contact" formPOST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"tapOn","selector":"Create contact"}HTTP/1.1 200 OK
{"success":true,"duration":181943750,"message":"Tapped on element at (943, 2035)","element":{"id":"00000000-0000-0036-ffff-ffff0000000b","bounds":{"x":870,"y":1962,"width":147,"height":147},"visible":true,"enabled":false}}POST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"assertVisible","selector":"First name"}HTTP/1.1 200 OK
{"success":true,"duration":861872750,"message":"Element is visible: First name","element":{"id":"00000000-0000-0037-ffff-ffff000000a9","text":"First name","bounds":{"x":137,"y":793,"width":796,"height":154},"visible":true,"enabled":false}}6. Type the contact name (object-form selector + step payload)POST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"inputText","selector":{"text":"First name"},"text":"Appium Driver"}HTTP/1.1 200 OK
{"success":true,"duration":234679000,"message":"Input text: Appium Driver","element":{"id":"00000000-0000-0037-ffff-ffff000000a9","text":"First name","bounds":{"x":137,"y":793,"width":796,"height":154},"visible":true,"enabled":false}}Appium server-side log for this step (shows the runner → Appium → device chain): 7. Save the contactPOST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"tapOn","selector":"Save"}HTTP/1.1 200 OK
{"success":true,"duration":132053458,"message":"Tapped on element at (838, 146)","element":{"id":"00000000-0000-0037-ffff-ffff0000025a","text":"Save","bounds":{"x":723,"y":83,"width":231,"height":126},"visible":true,"enabled":false}}8. Verify the created contactPOST /session/264715c12d32b7c438e7ebe34c32eb79/execute
Content-Type: application/json
{"type":"assertVisible","selector":"Appium Driver"}HTTP/1.1 200 OK
{"success":true,"duration":65181125,"message":"Element is visible: Appium Driver","element":{"id":"00000000-0000-0036-ffff-ffff0000027b","text":"Appium Driver","bounds":{"x":53,"y":804,"width":974,"height":108},"visible":true,"enabled":false}}Server traces for the execute sequence: 9. Device infoGET /session/264715c12d32b7c438e7ebe34c32eb79/device-infoHTTP/1.1 200 OK
{"platform":"android","osVersion":"15","deviceName":"emulator-5554","deviceId":"emulator-5554","isSimulator":false,"screenWidth":1080,"screenHeight":2424,"appVersion":"4.32.50.633180122","appBuild":"3176399"}(note: 10. Session count and teardownGET /statusHTTP/1.1 200 OK
{"sessions":1,"status":"ok"}DELETE /session/264715c12d32b7c438e7ebe34c32eb79HTTP/1.1 204 No ContentThe Appium log confirms the teardown was proxied through: Result✅ Full create → 8-step create-contact flow (100% |
|
End-to-end verification transcript for the new REST Endpoint Evidence — Platform: `web` (Chrome over CDP)
1. Server readinessGET /statusHTTP/1.1 200 OK
{"sessions":0,"status":"ok"}2. Create a web session (
|
…O_RUNNER_DEBUG_ADDR) With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails (not optional, not inside a retry that has attempts left) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
07d12b5 to
69f092e
Compare
69f092e to
58b5624
Compare
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
(cherry picked from commit 054d239)
(cherry picked from commit ad3e226)
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
(cherry picked from commit 054d239)
(cherry picked from commit ad3e226)
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
(cherry picked from commit 054d239)
(cherry picked from commit ad3e226)
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Simector-only until upstream wants it (see the issue relating it to devicelab-dev#230).
(cherry picked from commit 054d239)
(cherry picked from commit ad3e226)
…O_RUNNER_DEBUG_ADDR)
With MAESTRO_RUNNER_DEBUG_ADDR set, a step that fails the flow (not optional, unless its ${...} threw; not inside a retry that has attempts left; a runFlow, retry or repeat only on its own ${...} that threw) pauses the flow and serves on that address: GET /debug/state, /debug/screenshot, /debug/hierarchy; POST /debug/exec runs YAML steps in the paused flow's context; POST /debug/retry, /debug/skip and /debug/fail end the pause. Without the variable nothing changes. Carried by this fork only, until upstream wants it (see the issue relating it to devicelab-dev#230).
(cherry picked from commit 054d239)
(cherry picked from commit ad3e226)
# Conflicts: # pkg/cli/cli.go # pkg/flow/step.go
|
I have moved for review, @omnarayan Please have look. |
Summary
Ports the session-based REST API and JSON step protocol from origin pr4bh4sh/maestro-runner: adds
maestro-runner server, an in-memory session manager, and JSON decoding that reuses the sameflow.Steptypes as YAML. Source: pr4bh4sh#2This is the base for creating language bindings. e.g. python, typescript to start with.
Why reviewers should care: today maestro-runner can only be driven by a YAML flow file on disk. This PR makes the binary controllable over HTTP — an external client can create a driver session, execute individual Maestro steps sent as JSON, fetch screenshots/UI hierarchy/device info, and tear the session down. Sessions cover Android (
devicelab,uiautomator2,appium), iOS (devicelab,wda,devicelab-legacy,appium), and desktop Chrome/Chromium over CDP (web). The JSON protocol deliberately does not introduce a second step model:UnmarshalStepdecodes atypediscriminator into the sameflow.Stepstructs YAML produces, so both paths run through onecore.Driver.Execute.Type of Change
Changes Made
pkg/serverwithServer,SessionState, route handlers for status/create/execute/screenshot/source/device-info/delete,ShutdownAll, and concurrency-safe session map.pkg/flow/json.gowithUnmarshalStep, type dispatch, andSelectorJSON marshal/unmarshal (text-only or object forms).pkg/cli/server.goand registerserverCommandinpkg/cli/cli.go.platformName: "web"to the existing Rod/CDP browser driver, with--browser,--headed,--window-size, and--user-data-diron theservercommand.docs/rest-api.md(endpoint reference, JSON step protocol, error contracts) and link it fromREADME.md,llms.txt, anddocs/go-library.md.Review guide, in reading order:
pkg/server/server.go— session lifecycle, locking, error shapes.pkg/flow/json.go— type-dispatch contract;TestUnmarshalStep_SupportedStepTypesinjson_test.gopins "every advertised step type must decode".pkg/cli/server.go— flag/env handling (--port,MAESTRO_SERVER_PORT) and graceful shutdown.step.go/selector.go— mechanicaljson:tag additions; each tag mirrors itsyaml:key, so YAML decoding is unchanged.REST API Endpoints
GET/statusPOST/sessionandroid,ios, orweb(platformName,deviceId,appId,driver)POST/session/{id}/executeGET/session/{id}/screenshotGET/session/{id}/sourceapplication/xmlorapplication/json, including the browser accessibility tree)GET/session/{id}/device-infoDELETE/session/{id}driveris chosen per session in thePOST /sessionbody —devicelab(default),uiautomator2,appiumon Android;devicelab(default),wda,devicelab-legacy,appiumon iOS;cdpon web — so one server can hold sessions across drivers. Forweb,appIdis the start URL and the server flags select the browser (--browser chrome), headless/headed, and viewport. Execute returns HTTP200withsuccess:falsefor a step that ran and failed; malformed or unsupported step JSON returns400, an unknown session404. Full reference, including the step protocol and error table: docs/rest-api.md.Related Issues
pr4bh4sh#2
Testing
go test ./pkg/server ./pkg/flow; full suitego test ./... -p 8green, CDP package excluded by agreement)make fmt-check+golangci-lint v2.13.2, the CI-pinned version — 0 issues)pkg/server, 22 inpkg/flow/json_test.go, 5 inpkg/cli)devicelab,uiautomator2,appium— and Chrome over CDP forweb, covering session create, step execution, device-info, screenshot, source, delete, and the 400/404 error contracts; request/response transcripts attached as PR comments)Checklist
Additional Notes
Sessions are in-memory and lost on restart; clients must create a new session after reconnecting.
MAESTRO_SERVER_PORTmaps to the default--port. Source branch: https://github.com/pr4bh4sh/maestro-runner/tree/feat/session-rest-api2Known limitations (deliberate scope): JSON protocol covers 36 step types — unsupported ones fail loudly naming the step, and the contract test makes each addition explicit. On
web, browser-script steps the driver already implements (evalBrowserScript,getConsoleLogs, cookies/auth state) are not exposed by the JSON protocol yet. No auth layer; intended for localhost/CI use behind the binding that spawns the server.