zeno-mobile-runner 0.1.3 → 0.2.0

package/src/cli_trace.zig

@@ -6,6 +6,7 @@ const report = @import("report.zig");
 pub const ReportArgs = struct {
     input_path: []const u8,
     out_path: ?[]const u8 = null,
+    junit_path: ?[]const u8 = null,
 };
 
 pub const ExplainArgs = struct {
@@ -21,21 +22,34 @@ pub const ExportArgs = struct {
 };
 
 pub fn parseReportArgs(args: []const []const u8) !ReportArgs {
-    if (args.len == 0) return error.MissingReportInput;
-    var parsed = ReportArgs{ .input_path = args[0] };
+    var input_path: ?[]const u8 = null;
+    var out_path: ?[]const u8 = null;
+    var junit_path: ?[]const u8 = null;
 
-    var index: usize = 1;
+    var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const arg = args[index];
         if (std.mem.eql(u8, arg, "--out")) {
             index += 1;
-            parsed.out_path = if (index < args.len) args[index] else return error.MissingReportOutput;
+            out_path = if (index < args.len) args[index] else return error.MissingReportOutput;
+        } else if (std.mem.eql(u8, arg, "--junit")) {
+            index += 1;
+            junit_path = if (index < args.len) args[index] else return error.MissingJUnitOutput;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (input_path == null) {
+            input_path = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    if (parsed.out_path == null) return error.MissingReportOutput;
-    return parsed;
+    if (input_path == null) return error.MissingReportInput;
+    if (out_path == null) return error.MissingReportOutput;
+    return ReportArgs{
+        .input_path = input_path.?,
+        .out_path = out_path,
+        .junit_path = junit_path,
+    };
 }
 
 pub fn parseExplainArgs(args: []const []const u8) !ExplainArgs {
@@ -54,26 +68,38 @@ pub fn parseExplainArgs(args: []const []const u8) !ExplainArgs {
 }
 
 pub fn parseExportArgs(args: []const []const u8) !ExportArgs {
-    if (args.len == 0) return error.MissingTraceDir;
-    var parsed = ExportArgs{ .trace_dir = args[0] };
+    var trace_dir: ?[]const u8 = null;
+    var out_path: ?[]const u8 = null;
+    var redact = false;
+    var omit_screenshots = false;
 
-    var index: usize = 1;
+    var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const arg = args[index];
         if (std.mem.eql(u8, arg, "--out")) {
             index += 1;
-            parsed.out_path = if (index < args.len) args[index] else return error.MissingTraceBundleOutput;
+            out_path = if (index < args.len) args[index] else return error.MissingTraceBundleOutput;
         } else if (std.mem.eql(u8, arg, "--redact")) {
-            parsed.redact = true;
+            redact = true;
         } else if (std.mem.eql(u8, arg, "--omit-screenshots")) {
-            parsed.redact = true;
-            parsed.omit_screenshots = true;
+            redact = true;
+            omit_screenshots = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (trace_dir == null) {
+            trace_dir = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    if (parsed.out_path == null) return error.MissingTraceBundleOutput;
-    return parsed;
+    if (trace_dir == null) return error.MissingTraceDir;
+    if (out_path == null) return error.MissingTraceBundleOutput;
+    return ExportArgs{
+        .trace_dir = trace_dir.?,
+        .out_path = out_path,
+        .redact = redact,
+        .omit_screenshots = omit_screenshots,
+    };
 }
 
 pub fn runReport(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {
@@ -84,6 +110,10 @@ pub fn runReport(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !
     const parsed = try parseReportArgs(raw_args.items);
     try report.writeHtmlReport(allocator, parsed.input_path, parsed.out_path.?);
     try std.fs.File.stdout().deprecatedWriter().print("wrote {s}\n", .{parsed.out_path.?});
+    if (parsed.junit_path) |junit_path| {
+        try report.writeJUnitReport(allocator, parsed.input_path, junit_path);
+        try std.fs.File.stdout().deprecatedWriter().print("wrote {s}\n", .{junit_path});
+    }
 }
 
 pub fn runExplain(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {

package/src/cli_validate.zig

@@ -9,17 +9,23 @@ pub const ParsedArgs = struct {
 };
 
 pub fn parseArgs(args: []const []const u8) !ParsedArgs {
-    if (args.len == 0) return error.MissingScenarioPath;
-
-    var parsed = ParsedArgs{ .path = args[0] };
-    for (args[1..]) |arg| {
+    var path: ?[]const u8 = null;
+    var json = false;
+    for (args) |arg| {
         if (std.mem.eql(u8, arg, "--json")) {
-            parsed.json = true;
+            json = true;
+        } else if (std.mem.startsWith(u8, arg, "--")) {
+            return error.UnknownFlag;
+        } else if (path == null) {
+            path = arg;
         } else {
             return error.UnknownFlag;
         }
     }
-    return parsed;
+    return ParsedArgs{
+        .path = path orelse return error.MissingScenarioPath,
+        .json = json,
+    };
 }
 
 pub fn run(allocator: std.mem.Allocator, args: *std.process.ArgIterator) !void {

package/src/errors.zig

@@ -10,6 +10,12 @@ pub fn classify(err: anyerror) PublicError {
         error.MissingScenarioPath => .{ .code = "cli.missing_scenario", .message = "missing scenario path" },
         error.MissingDeviceSerial => .{ .code = "cli.missing_device", .message = "missing device serial" },
         error.MissingTraceDir => .{ .code = "cli.missing_trace_dir", .message = "missing trace directory" },
+        error.MissingReportInput => .{ .code = "cli.missing_report_input", .message = "missing report input path" },
+        error.MissingReportOutput => .{ .code = "cli.missing_report_output", .message = "missing report output path" },
+        error.MissingDraftOut => .{ .code = "cli.missing_draft_out", .message = "missing draft output path" },
+        error.MissingDiscoverOut => .{ .code = "cli.missing_discover_out", .message = "missing discover output path" },
+        error.MissingJUnitOutput => .{ .code = "cli.missing_junit_output", .message = "missing JUnit output path" },
+        error.MissingTraceBundleOutput => .{ .code = "cli.missing_trace_bundle_output", .message = "missing trace bundle output path" },
         error.MissingAppId => .{ .code = "cli.missing_app_id", .message = "missing app id" },
         error.MissingAdbPath => .{ .code = "cli.missing_adb_path", .message = "missing adb path" },
         error.MissingXcrunPath => .{ .code = "cli.missing_xcrun_path", .message = "missing xcrun path" },
@@ -19,6 +25,9 @@ pub fn classify(err: anyerror) PublicError {
         error.UnknownFlag => .{ .code = "cli.unknown_flag", .message = "unknown flag" },
         error.MissingParam => .{ .code = "cli.missing_param", .message = "missing parameter" },
         error.FileNotFound => .{ .code = "scenario.file_not_found", .message = "scenario file was not found" },
+        error.SemanticSnapshotMissing => .{ .code = "draft.no_snapshot", .message = "no semantic snapshot was found in the trace" },
+        error.InvalidTraceManifest => .{ .code = "trace.invalid_manifest", .message = "trace manifest is invalid" },
+        error.InvalidSemanticSnapshot => .{ .code = "trace.invalid_semantic_snapshot", .message = "semantic snapshot is invalid" },
         error.UnsupportedPlatform => .{ .code = "cli.unsupported_platform", .message = "unsupported platform" },
         error.UnsupportedTransport => .{ .code = "cli.unsupported_transport", .message = "unsupported transport" },
         error.ScenarioMustBeObject,

package/src/ios.zig

@@ -10,8 +10,10 @@ const types = @import("types.zig");
 
 const default_max_output = 32 * 1024 * 1024;
 // Clean iOS prebuilds can force the XCTest shim script through a full native
-// dependency build before it can answer the first selector query.
-const shim_timeout_ms = 5_400_000;
+// dependency build before it can answer the first selector query. Slower CI
+// hardware can override the default with ZMR_IOS_SHIM_TIMEOUT_MS.
+const default_shim_timeout_ms = 5_400_000;
+const shim_timeout_env = "ZMR_IOS_SHIM_TIMEOUT_MS";
 const shim_best_effort_timeout_ms = 10_000;
 const shim_command_attempts = 2;
 const shim_bootstrap_retry_delay_ms = 500;
@@ -126,7 +128,9 @@ pub const IosDevice = struct {
         const result = try self.runSimctl(&.{ "openurl", self.target(), url }, default_max_output);
         defer result.deinit(self.allocator);
         try result.ensureSuccess();
-        self.acceptOpenURLConfirmationBestEffort();
+        if (urlMayNeedOpenConfirmation(url)) {
+            self.acceptOpenURLConfirmationBestEffort();
+        }
     }
 
     pub fn tap(self: *IosDevice, x: i32, y: i32) !void {
@@ -212,15 +216,22 @@ pub const IosDevice = struct {
 
         const active_package = try self.allocator.dupe(u8, self.app_id);
         errdefer self.allocator.free(active_package);
-        const nodes = if (self.shim_path != null)
-            self.snapshotNodesFromShim() catch |err| blk: {
+        var shim_viewport: ?types.Viewport = null;
+        const nodes = if (self.shim_path != null) blk: {
+            const shim_snapshot = self.snapshotFromShim() catch |err| {
                 if (screenshot_artifact == null) return err;
                 if (writer) |tw| try self.recordSnapshotSemanticFailure(tw, screenshot_artifact.?, err);
                 break :blk try self.allocator.alloc(types.UiNode, 0);
-            }
-        else
-            try self.allocator.alloc(types.UiNode, 0);
+            };
+            shim_viewport = shim_snapshot.viewport;
+            break :blk shim_snapshot.nodes;
+        } else try self.allocator.alloc(types.UiNode, 0);
         errdefer self.allocator.free(nodes);
+        if (shim_viewport) |value| {
+            if (value.width > 0 and value.height > 0) {
+                viewport = value;
+            }
+        }
 
         return .{
             .id = id,
@@ -260,10 +271,10 @@ pub const IosDevice = struct {
         return try self.allocator.dupe(u8, result.stdout);
     }
 
-    fn snapshotNodesFromShim(self: *IosDevice) ![]types.UiNode {
+    fn snapshotFromShim(self: *IosDevice) !ios_shim.SnapshotResponse {
         const response = try self.runShim(.{ .kind = .snapshot });
         defer self.allocator.free(response);
-        return try ios_shim.parseSnapshotNodes(self.allocator, response);
+        return try ios_shim.parseSnapshotResponse(self.allocator, response);
     }
 
     fn recordSnapshotSemanticFailure(self: *IosDevice, writer: *trace.TraceWriter, screenshot_artifact: []const u8, err: anyerror) !void {
@@ -319,7 +330,7 @@ pub const IosDevice = struct {
     }
 
     fn runShim(self: *IosDevice, shim_command: ios_shim.Command) ![]u8 {
-        return self.runShimWithTimeout(shim_command, shim_timeout_ms);
+        return self.runShimWithTimeout(shim_command, shimTimeoutMs());
     }
 
     fn runShimWithTimeout(self: *IosDevice, shim_command: ios_shim.Command, timeout_ms: u64) ![]u8 {
@@ -384,6 +395,25 @@ fn isTransientShimBootstrapFailure(result: command.ExecResult) bool {
         std.mem.indexOf(u8, result.stderr, "operation never finished bootstrapping") != null;
 }
 
+fn shimTimeoutMs() u64 {
+    return parseShimTimeoutMs(std.posix.getenv(shim_timeout_env));
+}
+
+fn parseShimTimeoutMs(raw: ?[]const u8) u64 {
+    const value = raw orelse return default_shim_timeout_ms;
+    const parsed = std.fmt.parseInt(u64, value, 10) catch return default_shim_timeout_ms;
+    if (parsed == 0) return default_shim_timeout_ms;
+    return parsed;
+}
+
+fn urlMayNeedOpenConfirmation(url: []const u8) bool {
+    return startsWithIgnoreCase(url, "http://") or startsWithIgnoreCase(url, "https://");
+}
+
+fn startsWithIgnoreCase(value: []const u8, prefix: []const u8) bool {
+    return value.len >= prefix.len and std.ascii.eqlIgnoreCase(value[0..prefix.len], prefix);
+}
+
 pub fn listDevices(allocator: std.mem.Allocator, xcrun_path: []const u8) ![]types.DeviceInfo {
     return try ios_devices.listSimulators(allocator, xcrun_path);
 }
@@ -401,6 +431,13 @@ pub fn parsePhysicalDevicesJson(allocator: std.mem.Allocator, content: []const u
 }
 
 test "ios xctest shim timeout allows cold xcodebuild startup" {
-    try std.testing.expect(shim_timeout_ms >= 5_400_000);
+    try std.testing.expect(default_shim_timeout_ms >= 5_400_000);
     try std.testing.expect(shim_best_effort_timeout_ms <= 15_000);
 }
+
+test "ios xctest shim timeout env override" {
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs(null));
+    try std.testing.expectEqual(@as(u64, 600_000), parseShimTimeoutMs("600000"));
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("not-a-number"));
+    try std.testing.expectEqual(@as(u64, default_shim_timeout_ms), parseShimTimeoutMs("0"));
+}

package/src/ios_shim.zig

@@ -32,6 +32,16 @@ pub const Command = struct {
     max_chars: ?u32 = null,
 };
 
+pub const SnapshotResponse = struct {
+    nodes: []types.UiNode,
+    viewport: types.Viewport = .{},
+
+    pub fn deinit(self: SnapshotResponse, allocator: std.mem.Allocator) void {
+        for (self.nodes) |node| node.deinit(allocator);
+        allocator.free(self.nodes);
+    }
+};
+
 pub fn writeCommandJson(writer: anytype, command: Command) !void {
     try writer.writeAll("{\"cmd\":");
     try trace.writeJsonString(writer, commandName(command.kind));
@@ -54,12 +64,13 @@ pub fn writeCommandJson(writer: anytype, command: Command) !void {
     try writer.writeAll("}\n");
 }
 
-pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]types.UiNode {
+pub fn parseSnapshotResponse(allocator: std.mem.Allocator, content: []const u8) !SnapshotResponse {
     const parsed = try std.json.parseFromSlice(std.json.Value, allocator, content, .{});
     defer parsed.deinit();
     if (parsed.value != .object) return error.IosShimResponseMustBeObject;
     const status = fieldString(parsed.value.object, "status") orelse return error.IosShimMissingStatus;
     if (!std.mem.eql(u8, status, "ok")) return error.IosShimResponseNotOk;
+    const viewport = parseViewport(parsed.value.object.get("viewport"));
     const nodes_value = parsed.value.object.get("nodes") orelse return error.IosShimMissingNodes;
     if (nodes_value != .array) return error.IosShimNodesMustBeArray;
 
@@ -97,7 +108,15 @@ pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]
         });
     }
 
-    return try nodes.toOwnedSlice(allocator);
+    return .{
+        .nodes = try nodes.toOwnedSlice(allocator),
+        .viewport = viewport,
+    };
+}
+
+pub fn parseSnapshotNodes(allocator: std.mem.Allocator, content: []const u8) ![]types.UiNode {
+    const snapshot = try parseSnapshotResponse(allocator, content);
+    return snapshot.nodes;
 }
 
 pub fn parseOkResponse(content: []const u8) !void {
@@ -278,6 +297,21 @@ fn intField(object: std.json.ObjectMap, key: []const u8) !i32 {
     return @intCast(value.integer);
 }
 
+fn parseViewport(value: ?std.json.Value) types.Viewport {
+    const actual = value orelse return .{};
+    if (actual != .object) return .{};
+    const width = optionalU32Field(actual.object, "width") orelse return .{};
+    const height = optionalU32Field(actual.object, "height") orelse return .{};
+    return .{ .width = width, .height = height };
+}
+
+fn optionalU32Field(object: std.json.ObjectMap, key: []const u8) ?u32 {
+    const value = object.get(key) orelse return null;
+    if (value != .integer) return null;
+    if (value.integer < 0 or value.integer > std.math.maxInt(u32)) return null;
+    return @intCast(value.integer);
+}
+
 fn dupeOptional(allocator: std.mem.Allocator, value: ?[]const u8) !?[]const u8 {
     if (value) |actual| return try allocator.dupe(u8, actual);
     return null;

package/src/json_rpc_methods.zig

@@ -1,12 +1,15 @@
 const std = @import("std");
 const bundle = @import("bundle.zig");
+const cli_output = @import("cli_output.zig");
 const observation = @import("json_rpc_observation.zig");
 const params_parser = @import("json_rpc_params.zig");
 const protocol = @import("json_rpc_protocol.zig");
 const rpc_trace = @import("json_rpc_trace.zig");
 const runner = @import("runner.zig");
+const runner_events = @import("runner_events.zig");
 const selector = @import("selector.zig");
 const trace = @import("trace.zig");
+const validation = @import("validation.zig");
 
 pub fn dispatchMethod(
     allocator: std.mem.Allocator,
@@ -18,11 +21,12 @@ pub fn dispatchMethod(
     live_trace: ?*trace.TraceWriter,
 ) !void {
     if (try dispatchCoreMethod(allocator, device, method, id, writer)) return;
-    if (try dispatchAppMethod(device, method, params, id, writer)) return;
+    if (try dispatchAppMethod(device, method, params, id, writer, live_trace)) return;
     if (try dispatchObserveMethod(device, method, id, writer, live_trace)) return;
     if (try dispatchUiMethod(allocator, device, method, params, id, writer, live_trace)) return;
     if (try dispatchWaitMethod(allocator, device, method, params, id, writer, live_trace)) return;
     if (try dispatchAssertMethod(allocator, device, method, params, id, writer, live_trace)) return;
+    if (try dispatchScenarioMethod(allocator, method, params, id, writer)) return;
     if (try dispatchTraceMethod(allocator, method, params, id, writer, live_trace)) return;
 
     try protocol.writeError(writer, id, -32601, "method not found");
@@ -65,37 +69,53 @@ fn dispatchAppMethod(
     params: ?std.json.Value,
     id: ?std.json.Value,
     writer: anytype,
+    live_trace: ?*trace.TraceWriter,
 ) !bool {
     if (std.mem.eql(u8, method, "app.install")) {
         const path = try params_parser.requiredString(params, "path");
         try device.install(path);
+        if (live_trace) |tw| try rpc_trace.recordSimplePayload(tw, "app.install", "path", path);
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     if (std.mem.eql(u8, method, "app.launch")) {
         try device.launch();
+        if (live_trace) |tw| try tw.recordEvent("app.launch", "{\"status\":\"ok\"}");
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     if (std.mem.eql(u8, method, "app.stop")) {
         try device.stop();
+        if (live_trace) |tw| try tw.recordEvent("app.stop", "{\"status\":\"ok\"}");
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     if (std.mem.eql(u8, method, "app.clearState")) {
         try device.clearState();
+        if (live_trace) |tw| try tw.recordEvent("app.clearState", "{\"status\":\"ok\"}");
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     if (std.mem.eql(u8, method, "app.openLink")) {
         const url = try params_parser.requiredString(params, "url");
         try device.openLink(url);
+        if (live_trace) |tw| try recordAppOpenLink(tw, url);
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     return false;
 }
 
+fn recordAppOpenLink(tw: *trace.TraceWriter, url: []const u8) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const writer = payload.writer(tw.allocator);
+    try writer.writeAll("{\"status\":\"ok\",\"url\":");
+    try trace.writeJsonString(writer, url);
+    try writer.writeAll("}");
+    try tw.recordEvent("app.openLink", payload.items);
+}
+
 fn dispatchObserveMethod(
     device: anytype,
     method: []const u8,
@@ -175,14 +195,13 @@ fn dispatchUiMethod(
         return true;
     }
     if (std.mem.eql(u8, method, "ui.swipe")) {
-        try device.swipe(
-            try params_parser.requiredI32(params, "x1"),
-            try params_parser.requiredI32(params, "y1"),
-            try params_parser.requiredI32(params, "x2"),
-            try params_parser.requiredI32(params, "y2"),
-            @as(u32, @intCast(try params_parser.optionalU64(params, "durationMs", 300))),
-        );
-        if (live_trace) |tw| try tw.recordEvent("ui.swipe", "{\"status\":\"ok\"}");
+        const x1 = try params_parser.requiredI32(params, "x1");
+        const y1 = try params_parser.requiredI32(params, "y1");
+        const x2 = try params_parser.requiredI32(params, "x2");
+        const y2 = try params_parser.requiredI32(params, "y2");
+        const duration_ms = @as(u32, @intCast(try params_parser.optionalU64(params, "durationMs", 300)));
+        try device.swipe(x1, y1, x2, y2, duration_ms);
+        if (live_trace) |tw| try runner_events.recordSwipe(tw, x1, y1, x2, y2, duration_ms);
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
@@ -263,14 +282,14 @@ fn dispatchAssertMethod(
     if (std.mem.eql(u8, method, "assert.visible")) {
         const wanted = try params_parser.selectorParam(allocator, params);
         defer wanted.deinit(allocator);
-        if (!try runner.waitUntilVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
+        if (!try runner.assertVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
     if (std.mem.eql(u8, method, "assert.notVisible")) {
         const wanted = try params_parser.selectorParam(allocator, params);
         defer wanted.deinit(allocator);
-        if (!try runner.waitUntilNotVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
+        if (!try runner.assertNotVisible(device, wanted, try params_parser.optionalU64(params, "timeoutMs", 5000), live_trace, .{})) return error.AssertionFailed;
         try protocol.writeResultRaw(writer, id, "true");
         return true;
     }
@@ -282,6 +301,26 @@ fn dispatchAssertMethod(
     return false;
 }
 
+fn dispatchScenarioMethod(
+    allocator: std.mem.Allocator,
+    method: []const u8,
+    params: ?std.json.Value,
+    id: ?std.json.Value,
+    writer: anytype,
+) !bool {
+    if (std.mem.eql(u8, method, "scenario.validate")) {
+        const path = try params_parser.requiredString(params, "path");
+        var result = try validation.validateFile(allocator, path);
+        defer result.deinit(allocator);
+        var payload = std.ArrayList(u8).empty;
+        defer payload.deinit(allocator);
+        try cli_output.writeValidationJson(payload.writer(allocator), path, result);
+        try protocol.writeResultRaw(writer, id, std.mem.trimRight(u8, payload.items, " \t\r\n"));
+        return true;
+    }
+    return false;
+}
+
 fn dispatchTraceMethod(
     allocator: std.mem.Allocator,
     method: []const u8,
@@ -296,6 +335,41 @@ fn dispatchTraceMethod(
         try rpc_trace.writeEventsResult(allocator, writer, id, live_trace, after_seq, limit);
         return true;
     }
+    if (std.mem.eql(u8, method, "trace.discover")) {
+        try rpc_trace.writeDiscoverResult(
+            allocator,
+            writer,
+            id,
+            live_trace,
+            try params_parser.requiredString(params, "out"),
+            try params_parser.optionalBool(params, "includeActions", false),
+            try params_parser.optionalBool(params, "validate", false),
+            try params_parser.optionalBool(params, "force", false),
+            try params_parser.optionalString(params, "name"),
+            try params_parser.optionalString(params, "appId"),
+        );
+        return true;
+    }
+    if (std.mem.eql(u8, method, "trace.explore")) {
+        try rpc_trace.writeExploreResult(
+            allocator,
+            writer,
+            id,
+            live_trace,
+            try params_parser.requiredString(params, "out"),
+            try params_parser.requiredString(params, "goal"),
+            try params_parser.optionalBool(params, "includeActions", false),
+            try params_parser.optionalBool(params, "validate", false),
+            try params_parser.optionalBool(params, "force", false),
+            try params_parser.optionalString(params, "name"),
+            try params_parser.optionalString(params, "appId"),
+        );
+        return true;
+    }
+    if (std.mem.eql(u8, method, "trace.explain")) {
+        try rpc_trace.writeExplainResult(allocator, writer, id, live_trace);
+        return true;
+    }
     if (std.mem.eql(u8, method, "trace.export")) {
         const tw = live_trace orelse {
             try protocol.writeTraceDisabledResult(writer, id);

package/src/json_rpc_params.zig

@@ -31,6 +31,14 @@ pub fn requiredString(params: ?std.json.Value, key: []const u8) ![]const u8 {
     return try json_fields.requiredString(params, key, error.MissingParam, error.ParamMustBeString);
 }
 
+pub fn optionalString(params: ?std.json.Value, key: []const u8) !?[]const u8 {
+    const value = field(params, key) orelse return null;
+    return switch (value) {
+        .string => |actual| actual,
+        else => error.ParamMustBeString,
+    };
+}
+
 pub fn requiredI32(params: ?std.json.Value, key: []const u8) !i32 {
     return try json_fields.requiredI32(params, key, error.MissingParam, error.ParamMustBeInteger);
 }

package/src/json_rpc_protocol.zig

@@ -11,7 +11,7 @@ pub const capabilities_json =
     "\",\"minimumCompatibleVersion\":\"" ++ version.protocol_min_compatible_version ++
     "\",\"stability\":\"" ++ version.protocol_stability ++
     "\",\"breakingChangePolicy\":\"" ++ version.protocol_breaking_change_policy ++
-    "\"},\"platforms\":[\"android\",\"ios\"],\"platformSupport\":{\"android\":{\"status\":\"supported\",\"deviceTypes\":[\"emulator\",\"physical\"],\"automation\":[\"adb\",\"uiautomator\",\"android-shim\"]},\"ios\":{\"status\":\"supported\",\"deviceTypes\":[\"simulator\",\"physical\"],\"automation\":[\"simctl\",\"devicectl\",\"xctest-shim\"],\"physicalDevices\":true}},\"iosPreview\":false,\"transports\":[\"stdio\",\"tcp\"],\"methods\":[\"runner.capabilities\",\"device.list\",\"session.create\",\"session.close\",\"app.install\",\"app.launch\",\"app.stop\",\"app.openLink\",\"app.clearState\",\"observe.snapshot\",\"observe.semanticSnapshot\",\"ui.tap\",\"ui.type\",\"ui.eraseText\",\"ui.hideKeyboard\",\"ui.swipe\",\"ui.pressBack\",\"ui.scrollUntilVisible\",\"wait.until\",\"wait.any\",\"wait.gone\",\"assert.visible\",\"assert.notVisible\",\"assert.healthy\",\"trace.events\",\"trace.export\"]}";
+    "\"},\"platforms\":[\"android\",\"ios\"],\"platformSupport\":{\"android\":{\"status\":\"supported\",\"deviceTypes\":[\"emulator\",\"physical\"],\"automation\":[\"adb\",\"uiautomator\",\"android-shim\"]},\"ios\":{\"status\":\"supported\",\"deviceTypes\":[\"simulator\",\"physical\"],\"automation\":[\"simctl\",\"devicectl\",\"xctest-shim\"],\"physicalDevices\":true}},\"iosPreview\":false,\"transports\":[\"stdio\",\"tcp\"],\"methods\":[\"runner.capabilities\",\"device.list\",\"session.create\",\"session.close\",\"app.install\",\"app.launch\",\"app.stop\",\"app.openLink\",\"app.clearState\",\"observe.snapshot\",\"observe.semanticSnapshot\",\"ui.tap\",\"ui.type\",\"ui.eraseText\",\"ui.hideKeyboard\",\"ui.swipe\",\"ui.pressBack\",\"ui.scrollUntilVisible\",\"wait.until\",\"wait.any\",\"wait.gone\",\"assert.visible\",\"assert.notVisible\",\"assert.healthy\",\"scenario.validate\",\"trace.events\",\"trace.explore\",\"trace.discover\",\"trace.explain\",\"trace.export\"]}";
 
 pub fn writeCapabilitiesResult(writer: anytype, id: ?std.json.Value) !void {
     try writeResultRaw(writer, id, capabilities_json);