Skip to content

feat: port session-based REST API and JSON step protocol - #230

Open
pr4bh4sh wants to merge 9 commits into
devicelab-dev:mainfrom
pr4bh4sh:feat/session-rest-api2
Open

pr4bh4sh wants to merge 9 commits into
devicelab-dev:mainfrom
pr4bh4sh:feat/session-rest-api2

Conversation

@pr4bh4sh

@pr4bh4sh pr4bh4sh commented Oct 19, 2026 •

Copy link
Copy Markdown

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 same flow.Step types as YAML. Source: pr4bh4sh#2

This 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: UnmarshalStep decodes a type discriminator into the same flow.Step structs YAML produces, so both paths run through one core.Driver.Execute.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Refactoring (no functional changes)

Changes Made

  • Add pkg/server with Server, SessionState, route handlers for status/create/execute/screenshot/source/device-info/delete, ShutdownAll, and concurrency-safe session map.
  • Add pkg/flow/json.go with UnmarshalStep, type dispatch, and Selector JSON marshal/unmarshal (text-only or object forms).
  • Add pkg/cli/server.go and register serverCommand in pkg/cli/cli.go.
  • Dispatch platformName: "web" to the existing Rod/CDP browser driver, with --browser, --headed, --window-size, and --user-data-dir on the server command.
  • Add JSON tags to step/selector fields without changing YAML decoding.
  • Add docs/rest-api.md (endpoint reference, JSON step protocol, error contracts) and link it from README.md, llms.txt, and docs/go-library.md.
  • Worker-aware trace helper with credential/payload redaction.

Review guide, in reading order:

  1. pkg/server/server.go — session lifecycle, locking, error shapes.
  2. pkg/flow/json.go — type-dispatch contract; TestUnmarshalStep_SupportedStepTypes in json_test.go pins "every advertised step type must decode".
  3. pkg/cli/server.go — flag/env handling (--port, MAESTRO_SERVER_PORT) and graceful shutdown.
  4. step.go / selector.go — mechanical json: tag additions; each tag mirrors its yaml: key, so YAML decoding is unchanged.

REST API Endpoints

Method Path Description
GET /status Server status and live session count
POST /session Create a session for android, ios, or web (platformName, deviceId, appId, driver)
POST /session/{id}/execute Execute one step as JSON (36 supported step types)
GET /session/{id}/screenshot PNG screenshot
GET /session/{id}/source UI hierarchy (application/xml or application/json, including the browser accessibility tree)
GET /session/{id}/device-info Platform/device metadata
DELETE /session/{id} Delete the session and run cleanup (204)

driver is chosen per session in the POST /session body — devicelab (default), uiautomator2, appium on Android; devicelab (default), wda, devicelab-legacy, appium on iOS; cdp on web — so one server can hold sessions across drivers. For web, appId is the start URL and the server flags select the browser (--browser chrome), headless/headed, and viewport. Execute returns HTTP 200 with success:false for a step that ran and failed; malformed or unsupported step JSON returns 400, an unknown session 404. Full reference, including the step protocol and error table: docs/rest-api.md.

Related Issues

pr4bh4sh#2

Testing

  • Tests pass locally (go test ./pkg/server ./pkg/flow; full suite go test ./... -p 8 green, CDP package excluded by agreement)
  • Linting passes (make fmt-check + golangci-lint v2.13.2, the CI-pinned version — 0 issues)
  • Added tests for new functionality (53 new test functions: 26 in pkg/server, 22 in pkg/flow/json_test.go, 5 in pkg/cli)
  • Tested manually with sample flows (end-to-end against a live Android emulator through all three Android drivers — devicelab, uiautomator2, appium — and Chrome over CDP for web, covering session create, step execution, device-info, screenshot, source, delete, and the 400/404 error contracts; request/response transcripts attached as PR comments)

Checklist

  • Code follows project style guidelines
  • Self-reviewed the code
  • Added/updated documentation as needed
  • No breaking changes (or documented if breaking)
  • CHANGELOG.md updated (for notable changes)

Additional Notes

Sessions are in-memory and lost on restart; clients must create a new session after reconnecting. MAESTRO_SERVER_PORT maps to the default --port. Source branch: https://github.com/pr4bh4sh/maestro-runner/tree/feat/session-rest-api2

Known 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.

@pr4bh4sh
pr4bh4sh marked this pull request as draft October 19, 2026 13:01
@pr4bh4sh

pr4bh4sh commented Oct 19, 2026 •

Copy link
Copy Markdown
Author

End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator (emulator-5554, Android 15 / API 35) driving the Google Contacts app.

REST Endpoint Evidence — Driver: `devicelab` (Android default)
  • Endpoint under test: http://127.0.0.1:9999 (maestro-runner server, PR feat: port session-based REST API and JSON step protocol #230 build at 62ca478)
  • Device: emulator-5554 — Google SDK emulator, Android 15 (API 35), 1080×2424
  • App under control: com.google.android.contacts (Google Contacts 4.32.50.633180122)
  • Driver: devicelab (platform default — no driver field sent in POST /session)
  • Date: 2026-10-19, traces 20:23:16 – 20:26:23 (IST)
  • All duration fields inside step responses are nanoseconds (Go time.Duration JSON encoding); server traces carry duration_ms.

1. Server readiness

GET /status
HTTP/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:

20:23:16 [TRACE] server request worker=master method=POST path=/session status=200 duration_ms=9576 session=cb86147ba156d7f801ebe4c5f8025620 platform=android deviceId=emulator-5554

Server-side driver log: Connecting to device → Starting DeviceLab driver → Socket: /tmp/devicelab-driver-emulator-5554.sock → WebSocket connected → Session created.


3. Launch the Contacts app

POST /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 screen

POST /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 hierarchy

GET /session/cb86147ba156d7f801ebe4c5f8025620/source
HTTP/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 content-desc="Create contact", content-desc="Search", text="No contacts yet")


6. Open the "Create contact" form

POST /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 contact

POST /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 success:false (system notification covered the UI)

POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json

{"type":"assertVisible","selector":"REST API"}
HTTP/1.1 200 OK
{"success":false,"duration":17105648792,"message":"Element not visible: element 'REST API' not found"}

Server trace:

20:24:41 [TRACE] server execute response … step="assertVisible" status=failed duration_ms=17105 message="Element not visible: element 'REST API' not found"

10. Screenshot while the popup was up

GET /session/cb86147ba156d7f801ebe4c5f8025620/screenshot
HTTP/1.1 200 OK
Content-Type: image/png
<binary PNG, saved as contacts_after_save.png during the test>

11. Dismiss the overlay (element-not-found path)

POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json

{"type":"tapOn","selector":"Close Popup Window"}
HTTP/1.1 200 OK
{"success":false,"duration":17053399416,"message":"Element not found: handler_error: Element not found in any of 10 strategies"}

12. Re-assert: contact is visible after the overlay cleared

POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json

{"type":"assertVisible","selector":"REST API"}
HTTP/1.1 200 OK
{"success":true,"duration":55576708,"message":"Element is visible","element":{"text":"REST API","bounds":{"x":53,"y":804,"width":974,"height":108},"visible":true,"enabled":true}}

13. Device info

GET /session/cb86147ba156d7f801ebe4c5f8025620/device-info
HTTP/1.1 200 OK
{"platform":"android","osVersion":"35","deviceName":"google sdk_gphone64_arm64","deviceId":"emulator-5554","isSimulator":true,"screenWidth":1080,"screenHeight":2424,"appId":"com.google.android.contacts","appVersion":"4.32.50.633180122","appBuild":"3176399"}

14. Session count around deletion

GET /status
HTTP/1.1 200 OK
{"sessions":1,"status":"ok"}
DELETE /session/cb86147ba156d7f801ebe4c5f8025620
HTTP/1.1 204 No Content
GET /status
HTTP/1.1 200 OK
{"sessions":0,"status":"ok"}

15. Execute against a deleted session → 404

POST /session/cb86147ba156d7f801ebe4c5f8025620/execute
Content-Type: application/json

{"type":"back"}
HTTP/1.1 404 Not Found
{"error":"session cb86147ba156d7f801ebe4c5f8025620 not found"}

16. Error contracts (second session dc846c0ef30c0b22013cfd502fc09f04)

Missing type:

POST /session/dc846c0ef30c0b22013cfd502fc09f04/execute
{"selector":"x"}
HTTP/1.1 400 Bad Request
{"error":"invalid step: missing \"type\" field in step JSON"}

Unsupported step type (names the offending type):

POST /session/dc846c0ef30c0b22013cfd502fc09f04/execute
{"type":"openNotifications"}
HTTP/1.1 400 Bad Request
{"error":"invalid step: unsupported step type: openNotifications"}

Malformed JSON:

POST /session/dc846c0ef30c0b22013cfd502fc09f04/execute
{nope
HTTP/1.1 400 Bad Request
{"error":"invalid step: unmarshal step type: invalid character 'n' looking for beginning of object key string"}

Unknown session:

POST /session/deadbeef/execute
{"type":"back"}
HTTP/1.1 404 Not Found
{"error":"session deadbeef not found"}

Cleanup:

DELETE /session/dc846c0ef30c0b22013cfd502fc09f04
HTTP/1.1 204 No Content

Result

✅ Full create → execute (9 steps incl. 2 honest failure responses) → screenshot/source/device-info → delete → error contracts, all through the REST endpoint on the DeviceLab driver.

@pr4bh4sh

pr4bh4sh commented Oct 19, 2026 •

Copy link
Copy Markdown
Author

End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator (emulator-5554, Android 15 / API 35) driving the Google Contacts app.

REST Endpoint Evidence — Driver: `uiautomator2`
  • Endpoint under test: http://127.0.0.1:9999 (maestro-runner server, PR feat: port session-based REST API and JSON step protocol #230 build at 62ca478)
  • Device: emulator-5554 — Google SDK emulator, Android 15 (API 35), 1080×2424
  • App under control: com.google.android.contacts (Google Contacts 4.32.50.633180122)
  • Driver selection: "driver":"uiautomator2" field in POST /session
  • Date: 2026-10-19, traces 20:31:03 – 20:31:52 (IST)
  • All duration fields inside step responses are nanoseconds (Go time.Duration JSON encoding); server traces carry duration_ms.

1. Server readiness

GET /status
HTTP/1.1 200 OK
{"sessions":0,"status":"ok"}

2. Create session with the UIAutomator2 driver flag

POST /session
Content-Type: application/json

{"platformName":"android","deviceId":"emulator-5554","driver":"uiautomator2"}
HTTP/1.1 200 OK
{"sessionId":"de5f6f545f98fe7fec4b9ebb0a71be05"}

Server trace:

20:31:03 [TRACE] server request worker=master method=POST path=/session status=200 duration_ms=5770 session=de5f6f545f98fe7fec4b9ebb0a71be05 platform=android deviceId=emulator-5554

Server-side driver log:

⏳ Connecting to device emulator-5554...
✓ Connected to google sdk_gphone64_arm64 (SDK 35)
⏳ Installing UIAutomator2 APKs...
✓ UIAutomator2 installed
⏳ Starting UIAutomator2 server...
  → Socket: /tmp/uia2-emulator-5554.sock
✓ UIAutomator2 server started
⏳ Creating session...
✓ Session created

3. Launch the Contacts app

POST /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 screen

POST /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" form

POST /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 contact

POST /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 contact

POST /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:

20:31:03 execute request  step="launchApp"      payload={"type":"launchApp","appId":"com.google.android.contacts"}
20:31:05 execute response step="launchApp"      status=passed duration_ms=1860
20:31:08 execute response step="assertVisible"  status=passed duration_ms=196
20:31:24 execute response step="tapOn"          status=passed duration_ms=3075
20:31:26 execute response step="assertVisible"  status=passed duration_ms=35
20:31:37 execute response step="inputText"      status=passed duration_ms=10073 message="Entered text: UIA2 Driver"
20:31:38 execute response step="assertVisible"  status=passed duration_ms=100
20:31:48 execute response step="tapOn"          status=passed duration_ms=98
20:31:51 execute response step="assertVisible"  status=passed duration_ms=42

9. Device info

GET /session/de5f6f545f98fe7fec4b9ebb0a71be05/device-info
HTTP/1.1 200 OK
{"platform":"android","osVersion":"35","deviceName":"google sdk_gphone64_arm64","deviceId":"emulator-5554","isSimulator":true,"screenWidth":1080,"screenHeight":2424}

10. Session teardown

DELETE /session/de5f6f545f98fe7fec4b9ebb0a71be05
HTTP/1.1 204 No Content

Server trace:

20:31:52 [TRACE] server request worker=master method=DELETE path=/session/de5f6f545f98fe7fec4b9ebb0a71be05 status=204 duration_ms=455 session=de5f6f545f98fe7fec4b9ebb0a71be05

Result

✅ Full create → 9-step create-contact flow (100% status=passed) → device-info → 204 delete, all through the REST endpoint on the UIAutomator2 driver. Contact UIA2 Driver persisted to the device.

@pr4bh4sh

pr4bh4sh commented Oct 19, 2026 •

Copy link
Copy Markdown
Author

End-to-end verification transcript for this PR (request → response for every call), captured against a live Android emulator (emulator-5554, Android 15 / API 35) driving the Google Contacts app.

REST Endpoint Evidence — Driver: `appium`
  • Endpoint under test: http://127.0.0.1:9999 (maestro-runner server, PR feat: port session-based REST API and JSON step protocol #230 build at 62ca478)
  • Appium server: http://127.0.0.1:4723 — Appium 3.5.2 + uiautomator2@6.7.3 (the runner's --appium-url default; external dependency by design)
  • Device: emulator-5554 — Google SDK emulator, Android 15 (API 35), 1080×2424
  • App under control: com.google.android.contacts (Google Contacts 4.32.50.633180122)
  • Driver selection: "driver":"appium" field in POST /session
  • Date: 2026-10-19, traces 20:32:10 – 20:32:45 (IST)
  • All duration fields inside step responses are nanoseconds (Go time.Duration JSON encoding); server traces carry duration_ms.

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 flag

POST /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:

20:32:10 [TRACE] server request worker=master method=POST path=/session status=200 duration_ms=6602 session=264715c12d32b7c438e7ebe34c32eb79 platform=android deviceId=emulator-5554

Server-side driver log:

⏳ Connecting to device emulator-5554...
✓ Connected to google sdk_gphone64_arm64 (SDK 35)
⏳ Connecting to Appium server: http://127.0.0.1:4723
⏳ Creating Appium session...
✓ Appium session created (session: f84d2cf7-dc3a-4124-8086-0ad998073d3e, device: emulator-5554, OS: android 15)

3. Launch the Contacts app

POST /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 screen

POST /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" form

POST /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):

15:02:32 [HTTP] --> POST /session/f84d2cf7…/element {"using":"-android uiautomator","value":"new UiSelector().text(\"First name\")"}
15:02:32 [HTTP] <-- POST /session/f84d2cf7…/element 200 20 ms
15:02:32 [HTTP] --> POST /session/f84d2cf7…/element/00000000-0000-0037-ffff-ffff000000a9/value {"text":"Appium Driver","value":[…]}
15:02:32 [HTTP] <-- POST /session/f84d2cf7…/element/…/value 200 57 ms

7. Save the contact

POST /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 contact

POST /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:

20:32:20 execute request  step="launchApp"     payload={"type":"launchApp","appId":"com.google.android.contacts"}
20:32:21 execute response step="launchApp"     status=passed duration_ms=1179
20:32:23 execute response step="assertVisible" status=passed duration_ms=1759
20:32:31 execute response step="tapOn"         status=passed duration_ms=181
20:32:32 execute response step="assertVisible" status=passed duration_ms=861
20:32:32 execute response step="inputText"     status=passed duration_ms=234 message="Input text: Appium Driver"
20:32:42 execute response step="tapOn"         status=passed duration_ms=132
20:32:45 execute response step="assertVisible" status=passed duration_ms=65

9. Device info

GET /session/264715c12d32b7c438e7ebe34c32eb79/device-info
HTTP/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: isSimulator:false and osVersion:"15" reflect Appium's own device attributes — provider-specific fields vary by driver; osVersion was "35" (API level) on the other two drivers.)


10. Session count and teardown

GET /status
HTTP/1.1 200 OK
{"sessions":1,"status":"ok"}
DELETE /session/264715c12d32b7c438e7ebe34c32eb79
HTTP/1.1 204 No Content

The Appium log confirms the teardown was proxied through:

15:02:45 [HTTP] --> DELETE /session/f84d2cf7-dc3a-4124-8086-0ad998073d3e
15:02:45 [AndroidUiautomator2Driver] Deleting UiAutomator2 session …
15:02:45 [HTTP] <-- DELETE /session/f84d2cf7… 200 207 ms

Result

✅ Full create → 8-step create-contact flow (100% status=passed) → device-info → 204 delete, all through the REST endpoint with the runner talking to Appium. Contact Appium Driver persisted to the device.

@pr4bh4sh

pr4bh4sh commented Oct 19, 2026 •

Copy link
Copy Markdown
Author

End-to-end verification transcript for the new web (Chrome over CDP) support: every request and response, captured against an installed Google Chrome launched by maestro-runner server --browser chrome.

REST Endpoint Evidence — Platform: `web` (Chrome over CDP)
  • Endpoint under test: http://127.0.0.1:9999 (maestro-runner server, branch feat/session-rest-api2)
  • Browser: installed Google Chrome — /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • Server command: maestro-runner server --port 9999 --browser chrome
  • Page under test: a local static page served by python3 -m http.server 8123 (heading, text input, button that rewrites a paragraph via JS)
  • Viewport: 1280×800, headless
  • Date: 2026-10-19, trace 21:22:45 – 21:22:47 (IST)
  • All duration fields inside step responses are nanoseconds (Go time.Duration JSON encoding); server traces carry duration_ms.

1. Server readiness

GET /status
HTTP/1.1 200 OK
{"sessions":0,"status":"ok"}

2. Create a web session (appId is the start URL)

POST /session
Content-Type: application/json

{"platformName":"web","appId":"http://127.0.0.1:8123/"}
HTTP/1.1 200 OK
{"sessionId":"66af49390b2a05d9c5cca7b37fa5b1dc"}

Server trace:

21:22:46 [TRACE] server request worker=master method=POST path=/session status=200 duration_ms=1009 session=66af49390b2a05d9c5cca7b37fa5b1dc platform=web deviceId=

Server log:

  ⏳ Launching browser...
[browser] Using installed Chrome: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

3. Execute steps against the page

POST /session/66af49390b2a05d9c5cca7b37fa5b1dc/execute

{"type":"assertVisible","selector":"REST CDP E2E"}
HTTP/1.1 200 OK
{"success":true,"duration":1334542,"message":"Element text=\"REST CDP E2E\" is visible"}
POST /session/66af49390b2a05d9c5cca7b37fa5b1dc/execute

{"type":"inputText","selector":{"id":"name"},"text":"Prabhash"}
HTTP/1.1 200 OK
{"success":true,"duration":40219833,"message":"Entered text: Prabhash"}
POST /session/66af49390b2a05d9c5cca7b37fa5b1dc/execute

{"type":"tapOn","selector":{"id":"greet"}}
HTTP/1.1 200 OK
{"success":true,"duration":90338334,"message":"Tapped on id=\"greet\"","element":{"text":"Greet","bounds":{"x":165,"y":79,"width":49,"height":21},"visible":true,"enabled":true,"class":"BUTTON"}}
POST /session/66af49390b2a05d9c5cca7b37fa5b1dc/execute

{"type":"assertVisible","selector":"Hello Prabhash"}
HTTP/1.1 200 OK
{"success":true,"duration":578917,"message":"Element text=\"Hello Prabhash\" is visible"}
POST /session/66af49390b2a05d9c5cca7b37fa5b1dc/execute

{"type":"assertNotVisible","selector":"Ready"}
HTTP/1.1 200 OK
{"success":true,"duration":642125,"message":"Element text=\"Ready\" is not visible"}

The button's onclick rewrites the paragraph from Ready to Hello Prabhash, so the last two steps prove the click landed and the DOM changed.


4. Device info

GET /session/66af49390b2a05d9c5cca7b37fa5b1dc/device-info
HTTP/1.1 200 OK
{"platform":"web","osVersion":"","deviceName":"Chrome","deviceId":"","isSimulator":true,"screenWidth":1280,"screenHeight":800}

5. UI hierarchy (accessibility tree)

GET /session/66af49390b2a05d9c5cca7b37fa5b1dc/source
HTTP/1.1 200 OK
Content-Type: application/json

[{"nodeId":"3","ignored":false,"role":{"type":"internalRole","value":"RootWebArea"},"chromeRole":{"type":"internalRole","value":144},"name":{"type":"computedString","value":"REST CDP E2E"}}, …]

The CDP driver returns a JSON array of accessibility nodes. First attempt of this change returned application/xml for that payload; content-type detection now recognizes [ as JSON (covered by TestSource_ContentType).


6. Screenshot

GET /session/66af49390b2a05d9c5cca7b37fa5b1dc/screenshot
HTTP/1.1 200 OK
Content-Type: image/png

<13409 bytes, verified: PNG image data, 1280 x 800, 8-bit/color RGB>

7. Session count and teardown

GET /status
HTTP/1.1 200 OK
{"sessions":1,"status":"ok"}
DELETE /session/66af49390b2a05d9c5cca7b37fa5b1dc
HTTP/1.1 204 No Content
GET /status
HTTP/1.1 200 OK
{"sessions":0,"status":"ok"}

Server trace:

21:22:47 [TRACE] server request worker=master method=DELETE path=/session/66af... status=204 duration_ms=0

DELETE closes the browser (CreateWebDriver cleanup → driver.Close()), so no Chrome process is left behind.


Notes

  • platformName used to return 500 failed to create driver: unsupported platform: web; the server factory now dispatches web to CreateWebDriver (Rod + CDP), matching cli.CreateDriver.
  • The server command gained web-only flags: --browser (chrome, chromium, or a binary path), --headed, --window-size, --user-data-dir.
  • Text selectors that look like regular expressions are treated as regex by the browser driver. A heading spelled REST + CDP is parsed as REST, one-or-more spaces, CDP and does not match; use a plain string (REST CDP E2E) or textRegex for literal metacharacters.

Result

✅ Create web session → 5 executed steps (assert, type, click, assert DOM change, assert old text gone) → device-info → JSON hierarchy → PNG screenshot → 204 delete, all through the REST endpoint with Chrome over CDP.

luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Oct 22, 2026
…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).
@pr4bh4sh
pr4bh4sh force-pushed the feat/session-rest-api2 branch from 07d12b5 to 69f092e Compare October 25, 2026 08:50
@pr4bh4sh
pr4bh4sh force-pushed the feat/session-rest-api2 branch from 69f092e to 58b5624 Compare October 25, 2026 08:53
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Oct 26, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Oct 28, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 6, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 7, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 8, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 10, 2026
…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).
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 14, 2026
…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)
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 15, 2026
…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)
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 15, 2026
…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)
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 16, 2026
…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)
luka-vladika-happening-xyz pushed a commit to luka-vladika-happening-xyz/maestro-runner that referenced this pull request Nov 17, 2026
…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
@pr4bh4sh
pr4bh4sh marked this pull request as ready for review November 22, 2026 09:10
@pr4bh4sh

Copy link
Copy Markdown
Author

I have moved for review, @omnarayan Please have look.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant