zig-mobile-runner 0.1.0

package/clients/python/README.md

@@ -0,0 +1,29 @@
+# ZMR Python Reference Client
+
+Standard-library Python client for ZMR's newline-delimited JSON-RPC protocol.
+
+```python
+from zmr_client import ZmrClient
+
+with ZmrClient(
+    "zmr",
+    [
+        "serve",
+        "--transport", "stdio",
+        "--device", "emulator-5554",
+        "--app-id", "com.example.mobiletest",
+        "--trace-dir", "traces/agent-session",
+    ],
+) as zmr:
+    zmr.create_session()
+    zmr.open_link("exampleapp://e2e-auth?probe=1")
+    zmr.wait_until({"text": "E2E auth probe"}, timeout_ms=30000)
+    snapshot = zmr.snapshot()
+    events = zmr.trace_events(0, limit=100)
+    print(snapshot["nodes"])
+    print(len(events["events"]))
+    zmr.export_trace("traces/agent-session-redacted.zmrtrace", redact=True, omit_screenshots=True)
+```
+
+The client intentionally avoids runtime dependencies so agents can vendor or
+copy it into automation harnesses easily.

package/clients/python/examples/fake_session.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+import json
+import os
+
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from zmr_client import ZmrClient  # noqa: E402
+
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../.."))
+
+
+with ZmrClient(
+    os.path.join(ROOT, "zig-out", "bin", "zmr"),
+    [
+        "serve",
+        "--transport",
+        "stdio",
+        "--device",
+        "fake-android-1",
+        "--app-id",
+        "com.example.mobiletest",
+        "--adb",
+        os.path.join(ROOT, "tests", "fake-adb.sh"),
+        "--trace-dir",
+        "traces/demo-python-client",
+    ],
+) as zmr:
+    capabilities = zmr.capabilities()
+    zmr.create_session()
+    zmr.open_link("exampleapp://e2e-auth?probe=1")
+    zmr.assert_healthy(timeout_ms=100)
+    snapshot = zmr.snapshot()
+    events = zmr.trace_events(0, limit=20)
+    zmr.export_trace("traces/demo-python-client-redacted.zmrtrace", redact=True, omit_screenshots=True)
+    print(
+        json.dumps(
+            {
+                "protocolVersion": capabilities["protocolVersion"],
+                "activePackage": snapshot["activePackage"],
+                "nodes": len(snapshot["nodes"]),
+                "events": len(events["events"]),
+            },
+            separators=(",", ":"),
+        )
+    )

package/clients/python/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zmr-client"
+version = "0.1.0.dev1"
+description = "Python JSON-RPC client for Zig Mobile Runner."
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+[tool.setuptools]
+py-modules = ["zmr_client"]

package/clients/python/zmr_client.py

@@ -0,0 +1,202 @@
+import json
+import subprocess
+import threading
+
+
+class ZmrRpcError(RuntimeError):
+    def __init__(self, error):
+        super().__init__(error.get("message", "ZMR JSON-RPC error"))
+        self.code = error.get("code")
+        self.public_code = error.get("publicCode")
+        self.data = error.get("data")
+
+
+class ZmrClient:
+    def __init__(self, command, args=None, cwd=None, env=None, stderr=None):
+        self._process = subprocess.Popen(
+            [command, *(args or [])],
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=stderr,
+            text=True,
+            encoding="utf-8",
+            bufsize=1,
+        )
+        self._next_id = 1
+        self._lock = threading.Lock()
+        self._closed = False
+
+    def request(self, method, params=None):
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("zmr client is closed")
+            request_id = self._next_id
+            self._next_id += 1
+            line = json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": request_id,
+                    "method": method,
+                    "params": params or {},
+                },
+                separators=(",", ":"),
+            )
+            self._process.stdin.write(line + "\n")
+            self._process.stdin.flush()
+
+            response_line = self._process.stdout.readline()
+            if response_line == "":
+                code = self._process.poll()
+                raise RuntimeError(f"zmr process exited with {code}")
+            response = json.loads(response_line)
+            if response.get("id") != request_id:
+                raise RuntimeError(f"unexpected JSON-RPC response id {response.get('id')!r}")
+            if "error" in response:
+                raise ZmrRpcError(response["error"])
+            return response.get("result")
+
+    def capabilities(self):
+        return self.request("runner.capabilities")
+
+    def create_session(self):
+        return self.request("session.create")
+
+    def close_session(self):
+        return self.request("session.close")
+
+    def devices(self):
+        return self.request("device.list")
+
+    def launch(self):
+        return self.request("app.launch")
+
+    def stop(self):
+        return self.request("app.stop")
+
+    def clear_state(self):
+        return self.request("app.clearState")
+
+    def open_link(self, url):
+        return self.request("app.openLink", {"url": url})
+
+    def snapshot(self):
+        return self.request("observe.snapshot")
+
+    def semantic_snapshot(self):
+        return self.request("observe.semanticSnapshot")
+
+    def tap(self, selector):
+        return self.request("ui.tap", {"selector": selector})
+
+    def type_text(self, text, selector=None):
+        params = {"text": text}
+        if selector is not None:
+            params["selector"] = selector
+        return self.request("ui.type", params)
+
+    def erase_text(self, selector=None, max_chars=None):
+        params = {}
+        if selector is not None:
+            params["selector"] = selector
+        if max_chars is not None:
+            params["maxChars"] = max_chars
+        return self.request("ui.eraseText", params)
+
+    def hide_keyboard(self):
+        return self.request("ui.hideKeyboard")
+
+    def swipe(self, x1, y1, x2, y2, duration_ms=None):
+        params = {"x1": x1, "y1": y1, "x2": x2, "y2": y2}
+        if duration_ms is not None:
+            params["durationMs"] = duration_ms
+        return self.request("ui.swipe", params)
+
+    def press_back(self):
+        return self.request("ui.pressBack")
+
+    def scroll_until_visible(self, selector, direction=None, timeout_ms=None):
+        params = {"selector": selector}
+        if direction is not None:
+            params["direction"] = direction
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("ui.scrollUntilVisible", params)
+
+    def wait_until(self, selector, timeout_ms=None):
+        params = {"visible": selector}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("wait.until", params)
+
+    def wait_any(self, selectors, timeout_ms=None):
+        params = {"selectors": selectors}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("wait.any", params)
+
+    def wait_gone(self, selector, timeout_ms=None):
+        params = {"selector": selector}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("wait.gone", params)
+
+    def assert_visible(self, selector, timeout_ms=None):
+        params = {"selector": selector}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("assert.visible", params)
+
+    def assert_not_visible(self, selector, timeout_ms=None):
+        params = {"selector": selector}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("assert.notVisible", params)
+
+    def assert_healthy(self, timeout_ms=None):
+        params = {}
+        if timeout_ms is not None:
+            params["timeoutMs"] = timeout_ms
+        return self.request("assert.healthy", params)
+
+    def export_trace(self, out, redact=False, omit_screenshots=False):
+        return self.request(
+            "trace.export",
+            {
+                "out": out,
+                "redact": redact,
+                "omitScreenshots": omit_screenshots,
+            },
+        )
+
+    def trace_events(self, after_seq=0, limit=None):
+        params = {"afterSeq": after_seq}
+        if limit is not None:
+            params["limit"] = limit
+        return self.request("trace.events", params)
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        if self._process.stdin:
+            self._process.stdin.close()
+        if self._process.poll() is None:
+            self._process.terminate()
+            try:
+                self._process.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                self._process.kill()
+                self._process.wait(timeout=2)
+        if self._process.stdout:
+            self._process.stdout.close()
+        if self._process.stderr:
+            self._process.stderr.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        self.close()
+        return False

package/clients/rust/Cargo.lock

@@ -0,0 +1,107 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.149"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zmr-client"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]

package/clients/rust/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "zmr-client"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+description = "Rust JSON-RPC client for Zig Mobile Runner."
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"

package/clients/rust/README.md

@@ -0,0 +1,19 @@
+# ZMR Rust Client
+
+Small synchronous JSON-RPC client for driving `zmr serve --transport stdio`
+from Rust agents and test harnesses.
+
+```rust
+let mut client = zmr_client::Client::start("zmr", ["serve", "--transport", "stdio"])?;
+let snapshot = client.snapshot()?;
+let healthy = client.assert_healthy(Some(1000))?;
+```
+
+Run the fake-session example from the repository root:
+
+```sh
+cargo run --manifest-path clients/rust/Cargo.toml --example fake_session -- \
+  --zmr ./zig-out/bin/zmr \
+  --adb ./tests/fake-adb.sh \
+  --trace-dir traces/demo-rust-client
+```

package/clients/rust/examples/fake_session.rs

@@ -0,0 +1,70 @@
+use serde_json::json;
+use std::env;
+use zmr_client::Client;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let mut zmr = String::from("zig-out/bin/zmr");
+    let mut adb = String::from("tests/fake-adb.sh");
+    let mut device = String::from("fake-android-1");
+    let mut app_id = String::from("com.example.mobiletest");
+    let mut trace_dir = String::from("traces/demo-rust-client");
+    let mut trace_out = String::from("traces/demo-rust-client-redacted.zmrtrace");
+
+    let mut args = env::args().skip(1);
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--zmr" => zmr = args.next().ok_or("--zmr requires a value")?,
+            "--adb" => adb = args.next().ok_or("--adb requires a value")?,
+            "--device" => device = args.next().ok_or("--device requires a value")?,
+            "--app-id" => app_id = args.next().ok_or("--app-id requires a value")?,
+            "--trace-dir" => trace_dir = args.next().ok_or("--trace-dir requires a value")?,
+            "--trace-out" => trace_out = args.next().ok_or("--trace-out requires a value")?,
+            _ => return Err(format!("unknown argument: {arg}").into()),
+        }
+    }
+
+    let mut client = Client::start(
+        &zmr,
+        [
+            "serve",
+            "--transport",
+            "stdio",
+            "--device",
+            &device,
+            "--app-id",
+            &app_id,
+            "--adb",
+            &adb,
+            "--trace-dir",
+            &trace_dir,
+        ],
+    )?;
+    let capabilities = client.capabilities()?;
+    client.create_session()?;
+    client.open_link("exampleapp://rust-client")?;
+    client.wait_until(json!({ "text": "Dashboard" }), Some(1000))?;
+    client.tap(json!({ "text": "Sign in" }))?;
+    client.type_text(
+        "agent@example.com",
+        Some(json!({ "resourceId": "email-login-email-input" })),
+    )?;
+    client.assert_not_visible(json!({ "text": "Application has crashed" }), Some(100))?;
+    client.assert_healthy(Some(100))?;
+    let snapshot = client.snapshot()?;
+    let exported = client.export_trace(&trace_out, true, true)?;
+    let events = client.trace_events(0, Some(10))?;
+
+    println!(
+        "{}",
+        json!({
+            "protocolVersion": capabilities.protocol_version,
+            "activePackage": snapshot.active_package,
+            "nodes": snapshot.nodes.len(),
+            "events": events.next_seq,
+            "traceDir": trace_dir,
+            "traceOut": exported.out,
+        })
+    );
+
+    Ok(())
+}