zig-mobile-runner 0.1.0

package/clients/go/zmr/client.go

@@ -0,0 +1,432 @@
+package zmr
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os/exec"
+	"sync"
+)
+
+type Client struct {
+	cmd    *exec.Cmd
+	stdin  io.WriteCloser
+	lines  *bufio.Scanner
+	nextID int64
+	mu     sync.Mutex
+	closed bool
+}
+
+type RPCError struct {
+	Code       int             `json:"code"`
+	Message    string          `json:"message"`
+	PublicCode string          `json:"publicCode,omitempty"`
+	Data       json.RawMessage `json:"data,omitempty"`
+}
+
+func (e *RPCError) Error() string {
+	if e.Message == "" {
+		return "ZMR JSON-RPC error"
+	}
+	return e.Message
+}
+
+type rpcRequest struct {
+	JSONRPC string      `json:"jsonrpc"`
+	ID      int64       `json:"id"`
+	Method  string      `json:"method"`
+	Params  interface{} `json:"params"`
+}
+
+type rpcResponse struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      int64           `json:"id"`
+	Result  json.RawMessage `json:"result,omitempty"`
+	Error   *RPCError       `json:"error,omitempty"`
+}
+
+type Capabilities struct {
+	Name            string                     `json:"name"`
+	Version         string                     `json:"version"`
+	ProtocolVersion string                     `json:"protocolVersion"`
+	Platforms       []string                   `json:"platforms"`
+	PlatformSupport map[string]PlatformSupport `json:"platformSupport"`
+	IosPreview      bool                       `json:"iosPreview"`
+	Transports      []string                   `json:"transports"`
+	Methods         []string                   `json:"methods"`
+}
+
+type PlatformSupport struct {
+	Status          string   `json:"status"`
+	DeviceTypes     []string `json:"deviceTypes"`
+	Automation      []string `json:"automation"`
+	PhysicalDevices bool     `json:"physicalDevices,omitempty"`
+}
+
+type Session struct {
+	SessionID string `json:"sessionId"`
+}
+
+type DeviceInfo struct {
+	Serial string `json:"serial"`
+	State  string `json:"state"`
+	Ready  bool   `json:"ready"`
+}
+
+type Snapshot struct {
+	ID             string                 `json:"id"`
+	TimestampMS    int64                  `json:"timestampMs"`
+	Viewport       map[string]interface{} `json:"viewport"`
+	ActivePackage  string                 `json:"activePackage"`
+	ActiveActivity string                 `json:"activeActivity"`
+	Nodes          []Node                 `json:"nodes"`
+}
+
+type Node struct {
+	StableID    string                 `json:"stableId"`
+	ClassName   string                 `json:"className"`
+	ResourceID  string                 `json:"resourceId,omitempty"`
+	Text        *string                `json:"text"`
+	ContentDesc *string                `json:"contentDesc"`
+	Bounds      map[string]interface{} `json:"bounds"`
+	Enabled     bool                   `json:"enabled"`
+	Visible     bool                   `json:"visible"`
+	Selected    bool                   `json:"selected"`
+}
+
+type SemanticSnapshot struct {
+	ID             string         `json:"id"`
+	TimestampMS    int64          `json:"timestampMs"`
+	Viewport       map[string]any `json:"viewport"`
+	ActivePackage  string         `json:"activePackage"`
+	ActiveActivity string         `json:"activeActivity"`
+	FocusedNodeID  *string        `json:"focusedNodeId"`
+	Nodes          []SemanticNode `json:"nodes"`
+	Summary        struct {
+		NodeCount        int      `json:"nodeCount"`
+		InteractiveCount int      `json:"interactiveCount"`
+		VisibleText      []string `json:"visibleText"`
+	} `json:"summary"`
+}
+
+type SemanticNode struct {
+	ID                string                 `json:"id"`
+	Role              string                 `json:"role"`
+	Name              string                 `json:"name"`
+	Selector          map[string]string      `json:"selector"`
+	Source            map[string]interface{} `json:"source"`
+	Bounds            map[string]interface{} `json:"bounds"`
+	Enabled           bool                   `json:"enabled"`
+	Visible           bool                   `json:"visible"`
+	Selected          bool                   `json:"selected"`
+	Interactive       bool                   `json:"interactive"`
+	RecommendedAction *string                `json:"recommendedAction"`
+}
+
+type TraceEvents struct {
+	TraceDir  string                   `json:"traceDir"`
+	AfterSeq  int64                    `json:"afterSeq"`
+	NextSeq   int64                    `json:"nextSeq"`
+	LatestSeq int64                    `json:"latestSeq"`
+	Events    []map[string]interface{} `json:"events"`
+}
+
+type TraceExport struct {
+	TraceDir        string `json:"traceDir"`
+	Out             string `json:"out"`
+	Redacted        bool   `json:"redacted"`
+	OmitScreenshots bool   `json:"omitScreenshots"`
+}
+
+func Start(ctx context.Context, command string, args ...string) (*Client, error) {
+	cmd := exec.CommandContext(ctx, command, args...)
+	stdin, err := cmd.StdinPipe()
+	if err != nil {
+		return nil, err
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return nil, err
+	}
+	if err := cmd.Start(); err != nil {
+		return nil, err
+	}
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+	return &Client{cmd: cmd, stdin: stdin, lines: scanner, nextID: 1}, nil
+}
+
+func (c *Client) Close() error {
+	c.mu.Lock()
+	if c.closed {
+		c.mu.Unlock()
+		return nil
+	}
+	c.closed = true
+	stdin := c.stdin
+	cmd := c.cmd
+	c.mu.Unlock()
+
+	_ = stdin.Close()
+	if cmd.Process != nil {
+		_ = cmd.Process.Kill()
+	}
+	return cmd.Wait()
+}
+
+func (c *Client) Request(ctx context.Context, method string, params interface{}, out interface{}) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.closed {
+		return errors.New("zmr client is closed")
+	}
+	id := c.nextID
+	c.nextID++
+	request := rpcRequest{JSONRPC: "2.0", ID: id, Method: method, Params: params}
+	line, err := json.Marshal(request)
+	if err != nil {
+		return err
+	}
+	if _, err := c.stdin.Write(append(line, '\n')); err != nil {
+		return err
+	}
+
+	type responseResult struct {
+		line string
+		ok   bool
+	}
+	responseCh := make(chan responseResult, 1)
+	go func() {
+		ok := c.lines.Scan()
+		responseCh <- responseResult{line: c.lines.Text(), ok: ok}
+	}()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case response := <-responseCh:
+		if !response.ok {
+			if err := c.lines.Err(); err != nil {
+				return err
+			}
+			return io.EOF
+		}
+		var decoded rpcResponse
+		if err := json.Unmarshal([]byte(response.line), &decoded); err != nil {
+			return err
+		}
+		if decoded.ID != id {
+			return fmt.Errorf("unexpected JSON-RPC response id %d", decoded.ID)
+		}
+		if decoded.Error != nil {
+			return decoded.Error
+		}
+		if out == nil {
+			return nil
+		}
+		return json.Unmarshal(decoded.Result, out)
+	}
+}
+
+func (c *Client) Capabilities(ctx context.Context) (Capabilities, error) {
+	var out Capabilities
+	err := c.Request(ctx, "runner.capabilities", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) CreateSession(ctx context.Context) (Session, error) {
+	var out Session
+	err := c.Request(ctx, "session.create", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) CloseSession(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "session.close", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) Devices(ctx context.Context) ([]DeviceInfo, error) {
+	var out []DeviceInfo
+	err := c.Request(ctx, "device.list", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) Launch(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "app.launch", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) Stop(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "app.stop", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) ClearState(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "app.clearState", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) OpenLink(ctx context.Context, url string) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "app.openLink", map[string]interface{}{"url": url}, &out)
+	return out, err
+}
+
+func (c *Client) Snapshot(ctx context.Context) (Snapshot, error) {
+	var out Snapshot
+	err := c.Request(ctx, "observe.snapshot", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) SemanticSnapshot(ctx context.Context) (SemanticSnapshot, error) {
+	var out SemanticSnapshot
+	err := c.Request(ctx, "observe.semanticSnapshot", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) Tap(ctx context.Context, selector map[string]interface{}) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "ui.tap", map[string]interface{}{"selector": selector}, &out)
+	return out, err
+}
+
+func (c *Client) TypeText(ctx context.Context, text string, selector map[string]interface{}) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"text": text}
+	if selector != nil {
+		params["selector"] = selector
+	}
+	err := c.Request(ctx, "ui.type", params, &out)
+	return out, err
+}
+
+func (c *Client) EraseText(ctx context.Context, selector map[string]interface{}, maxChars int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{}
+	if selector != nil {
+		params["selector"] = selector
+	}
+	if maxChars > 0 {
+		params["maxChars"] = maxChars
+	}
+	err := c.Request(ctx, "ui.eraseText", params, &out)
+	return out, err
+}
+
+func (c *Client) HideKeyboard(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "ui.hideKeyboard", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) Swipe(ctx context.Context, x1 int64, y1 int64, x2 int64, y2 int64, durationMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"x1": x1, "y1": y1, "x2": x2, "y2": y2}
+	if durationMS > 0 {
+		params["durationMs"] = durationMS
+	}
+	err := c.Request(ctx, "ui.swipe", params, &out)
+	return out, err
+}
+
+func (c *Client) PressBack(ctx context.Context) (bool, error) {
+	var out bool
+	err := c.Request(ctx, "ui.pressBack", map[string]interface{}{}, &out)
+	return out, err
+}
+
+func (c *Client) ScrollUntilVisible(ctx context.Context, selector map[string]interface{}, direction string, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"selector": selector}
+	if direction != "" {
+		params["direction"] = direction
+	}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "ui.scrollUntilVisible", params, &out)
+	return out, err
+}
+
+func (c *Client) WaitUntil(ctx context.Context, selector map[string]interface{}, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"visible": selector}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "wait.until", params, &out)
+	return out, err
+}
+
+func (c *Client) WaitAny(ctx context.Context, selectors []map[string]interface{}, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"selectors": selectors}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "wait.any", params, &out)
+	return out, err
+}
+
+func (c *Client) WaitGone(ctx context.Context, selector map[string]interface{}, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"selector": selector}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "wait.gone", params, &out)
+	return out, err
+}
+
+func (c *Client) AssertVisible(ctx context.Context, selector map[string]interface{}, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"selector": selector}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "assert.visible", params, &out)
+	return out, err
+}
+
+func (c *Client) AssertNotVisible(ctx context.Context, selector map[string]interface{}, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{"selector": selector}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "assert.notVisible", params, &out)
+	return out, err
+}
+
+func (c *Client) AssertHealthy(ctx context.Context, timeoutMS int64) (bool, error) {
+	var out bool
+	params := map[string]interface{}{}
+	if timeoutMS > 0 {
+		params["timeoutMs"] = timeoutMS
+	}
+	err := c.Request(ctx, "assert.healthy", params, &out)
+	return out, err
+}
+
+func (c *Client) ExportTrace(ctx context.Context, outPath string, redact bool, omitScreenshots bool) (TraceExport, error) {
+	var out TraceExport
+	err := c.Request(ctx, "trace.export", map[string]interface{}{"out": outPath, "redact": redact, "omitScreenshots": omitScreenshots}, &out)
+	return out, err
+}
+
+func (c *Client) TraceEvents(ctx context.Context, afterSeq int64, limit int64) (TraceEvents, error) {
+	var out TraceEvents
+	params := map[string]interface{}{"afterSeq": afterSeq}
+	if limit > 0 {
+		params["limit"] = limit
+	}
+	err := c.Request(ctx, "trace.events", params, &out)
+	return out, err
+}

package/clients/kotlin/README.md

@@ -0,0 +1,35 @@
+# ZMR Kotlin Client
+
+Small JVM client for Kotlin agents and test harnesses that drive
+`zmr serve --transport stdio`.
+
+For now, build it from a local checkout and consume the generated jar:
+
+```bash
+git submodule add https://github.com/johnmikel/zig-mobile-runner.git vendor/zig-mobile-runner
+gradle -p vendor/zig-mobile-runner/clients/kotlin build
+```
+
+Run the package test from the repository root:
+
+```bash
+gradle -p clients/kotlin test
+```
+
+Run the fake-session example from the repository root:
+
+```bash
+gradle -p clients/kotlin runFakeSession \
+  -Pzmr="$PWD/zig-out/bin/zmr" \
+  -Padb="$PWD/tests/fake-adb.sh" \
+  -PtraceDir="$PWD/traces/demo-kotlin-client" \
+  -PtraceOut="$PWD/traces/demo-kotlin-client-redacted.zmrtrace"
+```
+
+```kotlin
+implementation(files("path/to/zig-mobile-runner/clients/kotlin/build/libs/zmr-client-0.1.0.jar"))
+```
+
+The Kotlin client is host-side. It is useful for Android teams that want test
+or agent tooling in Kotlin, but it still controls the app through the local
+`zmr` binary rather than running inside the app process.

package/clients/kotlin/build.gradle.kts

@@ -0,0 +1,35 @@
+plugins {
+    kotlin("jvm") version "2.0.21"
+    `java-library`
+}
+
+group = "dev.zmr"
+version = "0.1.0"
+
+kotlin {
+    jvmToolchain(17)
+}
+
+dependencies {
+    testImplementation(kotlin("test"))
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.register<JavaExec>("runFakeSession") {
+    group = "application"
+    description = "Run the fake ZMR JSON-RPC session example."
+    dependsOn(tasks.named("classes"))
+    classpath = sourceSets["main"].runtimeClasspath
+    mainClass.set("dev.zmr.FakeSessionKt")
+    args = listOf(
+        "--zmr", providers.gradleProperty("zmr").orElse("zig-out/bin/zmr").get(),
+        "--adb", providers.gradleProperty("adb").orElse("tests/fake-adb.sh").get(),
+        "--device", providers.gradleProperty("device").orElse("fake-android-1").get(),
+        "--app-id", providers.gradleProperty("appId").orElse("com.example.mobiletest").get(),
+        "--trace-dir", providers.gradleProperty("traceDir").orElse("traces/demo-kotlin-client").get(),
+        "--trace-out", providers.gradleProperty("traceOut").orElse("traces/demo-kotlin-client-redacted.zmrtrace").get()
+    )
+}

package/clients/kotlin/settings.gradle.kts

@@ -0,0 +1,15 @@
+pluginManagement {
+    repositories {
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        mavenCentral()
+    }
+}
+
+rootProject.name = "zmr-client"

package/clients/kotlin/src/main/kotlin/dev/zmr/FakeSession.kt

@@ -0,0 +1,86 @@
+package dev.zmr
+
+private data class Options(
+    var zmr: String = "zig-out/bin/zmr",
+    var adb: String = "tests/fake-adb.sh",
+    var device: String = "fake-android-1",
+    var appId: String = "com.example.mobiletest",
+    var traceDir: String = "traces/demo-kotlin-client",
+    var traceOut: String = "traces/demo-kotlin-client-redacted.zmrtrace"
+)
+
+fun main(args: Array<String>) {
+    val options = parseOptions(args)
+    ZmrClient(
+        listOf(
+            options.zmr,
+            "serve",
+            "--transport", "stdio",
+            "--device", options.device,
+            "--app-id", options.appId,
+            "--adb", options.adb,
+            "--trace-dir", options.traceDir
+        )
+    ).use { client ->
+        val capabilities = client.call("runner.capabilities")
+        client.createSession()
+        client.call("app.openLink", """{"url":"exampleapp://kotlin-client"}""")
+        client.call("wait.until", """{"visible":{"text":"Dashboard"},"timeoutMs":1000}""")
+        client.call("ui.tap", """{"selector":{"text":"Sign in"}}""")
+        client.call("ui.type", """{"text":"agent@example.com","selector":{"resourceId":"email-login-email-input"}}""")
+        client.call("assert.notVisible", """{"selector":{"text":"Application has crashed"},"timeoutMs":100}""")
+        client.assertHealthy(timeoutMs = 100)
+        val snapshot = client.snapshot()
+        val exported = client.call(
+            "trace.export",
+            """{"out":"${escapeJson(options.traceOut)}","redact":true,"includeScreenshots":true}"""
+        )
+        val events = client.call("trace.events", """{"afterSeq":0,"limit":10}""")
+
+        println(
+            "{" +
+                "\"protocolVersion\":\"${extractString(capabilities, "protocolVersion")}\"," +
+                "\"activePackage\":\"${extractString(snapshot, "activePackage")}\"," +
+                "\"nodes\":${countOccurrences(snapshot, "\"stableId\"")}," +
+                "\"events\":${extractNumber(events, "nextSeq")}," +
+                "\"traceDir\":\"${escapeJson(options.traceDir)}\"," +
+                "\"traceOut\":\"${escapeJson(extractString(exported, "out"))}\"" +
+                "}"
+        )
+    }
+}
+
+private fun parseOptions(args: Array<String>): Options {
+    val options = Options()
+    var index = 0
+    while (index < args.size) {
+        val value = args.getOrNull(index + 1) ?: error("${args[index]} requires a value")
+        when (args[index]) {
+            "--zmr" -> options.zmr = value
+            "--adb" -> options.adb = value
+            "--device" -> options.device = value
+            "--app-id" -> options.appId = value
+            "--trace-dir" -> options.traceDir = value
+            "--trace-out" -> options.traceOut = value
+            else -> error("unknown argument: ${args[index]}")
+        }
+        index += 2
+    }
+    return options
+}
+
+private fun extractString(json: String, key: String): String {
+    val match = Regex(""""$key"\s*:\s*"([^"]*)"""").find(json)
+    return match?.groupValues?.get(1) ?: ""
+}
+
+private fun extractNumber(json: String, key: String): String {
+    val match = Regex(""""$key"\s*:\s*([0-9]+)""").find(json)
+    return match?.groupValues?.get(1) ?: "0"
+}
+
+private fun countOccurrences(value: String, needle: String): Int =
+    Regex.escape(needle).toRegex().findAll(value).count()
+
+private fun escapeJson(value: String): String =
+    value.replace("\\", "\\\\").replace("\"", "\\\"")

package/clients/kotlin/src/main/kotlin/dev/zmr/ZmrClient.kt

@@ -0,0 +1,67 @@
+package dev.zmr
+
+import java.io.BufferedReader
+import java.io.BufferedWriter
+import java.io.Closeable
+import java.io.InputStreamReader
+import java.io.OutputStreamWriter
+
+class ZmrRpcException(
+    val code: Int,
+    message: String,
+    val publicCode: String? = null
+) : RuntimeException(message)
+
+class ZmrClient(
+    private val command: List<String> = listOf("zmr", "serve", "--transport", "stdio")
+) : Closeable {
+    private var nextId = 1
+    private val process = ProcessBuilder(command).redirectError(ProcessBuilder.Redirect.INHERIT).start()
+    private val input = BufferedWriter(OutputStreamWriter(process.outputStream))
+    private val output = BufferedReader(InputStreamReader(process.inputStream))
+
+    fun createSession(): String = call("session.create")
+
+    fun snapshot(): String = call("observe.snapshot")
+
+    fun semanticSnapshot(): String = call("observe.semanticSnapshot")
+
+    fun assertHealthy(timeoutMs: Long? = null): String {
+        val params = timeoutMs?.let { "{\"timeoutMs\":$it}" } ?: "{}"
+        return call("assert.healthy", params)
+    }
+
+    @Synchronized
+    fun call(method: String, paramsJson: String? = null): String {
+        val id = nextId++
+        val params = paramsJson?.let { "," + "\"params\":" + it } ?: ""
+        input.write("{\"jsonrpc\":\"2.0\",\"id\":$id,\"method\":\"$method\"$params}")
+        input.newLine()
+        input.flush()
+        val response = output.readLine() ?: error("zmr closed stdout")
+        if (response.contains(""""error"""")) {
+            throw ZmrRpcException(
+                code = extractNumber(response, "code") ?: -32000,
+                message = extractString(response, "message").ifEmpty { "ZMR JSON-RPC error" },
+                publicCode = extractString(response, "publicCode").ifEmpty { null }
+            )
+        }
+        return response
+    }
+
+    override fun close() {
+        runCatching { call("session.close") }
+        runCatching { input.close() }
+        process.destroy()
+    }
+}
+
+private fun extractString(json: String, key: String): String {
+    val pattern = """"$key"\s*:\s*"([^"]*)"""".toRegex()
+    return pattern.find(json)?.groupValues?.get(1) ?: ""
+}
+
+private fun extractNumber(json: String, key: String): Int? {
+    val pattern = """"$key"\s*:\s*(-?[0-9]+)""".toRegex()
+    return pattern.find(json)?.groupValues?.get(1)?.toIntOrNull()
+}