zig-mobile-runner 0.1.0

package/src/runner_events.zig

@@ -0,0 +1,170 @@
+const std = @import("std");
+const runner_diagnostics = @import("runner_diagnostics.zig");
+const selector = @import("selector.zig");
+const trace = @import("trace.zig");
+const types = @import("types.zig");
+
+pub fn eventString(allocator: std.mem.Allocator, value: []const u8) ![]const u8 {
+    var buffer = std.ArrayList(u8).empty;
+    errdefer buffer.deinit(allocator);
+    try buffer.writer(allocator).writeAll("{\"value\":");
+    try trace.writeJsonString(buffer.writer(allocator), value);
+    try buffer.writer(allocator).writeAll("}");
+    return try buffer.toOwnedSlice(allocator);
+}
+
+pub fn recordNativeWait(tw: *trace.TraceWriter, kind: []const u8, wanted: selector.Selector, matched_index: ?usize) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    try payload.writer(tw.allocator).writeAll("{\"status\":\"ok\",\"strategy\":\"nativeSelector\"");
+    if (matched_index) |index| try payload.writer(tw.allocator).print(",\"matchedIndex\":{d}", .{index});
+    try payload.writer(tw.allocator).writeAll(",\"selector\":");
+    try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+    try payload.writer(tw.allocator).writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}
+
+pub fn recordNativeWaitTimeout(tw: *trace.TraceWriter, kind: []const u8, selectors: []const selector.Selector) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    try payload.writer(tw.allocator).writeAll("{\"status\":\"timeout\",\"strategy\":\"nativeSelector\",\"selectors\":[");
+    for (selectors, 0..) |wanted, index| {
+        if (index > 0) try payload.writer(tw.allocator).writeAll(",");
+        try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+    }
+    try payload.writer(tw.allocator).writeAll("]}");
+    try tw.recordEvent(kind, payload.items);
+}
+
+pub fn recordNativeWaitTimeoutWithDiagnostics(device: anytype, tw: *trace.TraceWriter, kind: []const u8, selectors: []const selector.Selector) !void {
+    var snap = device.snapshot(tw) catch {
+        try recordNativeWaitTimeout(tw, kind, selectors);
+        return;
+    };
+    defer snap.deinit(device.allocator);
+    try recordDiagnosticWithStrategy(tw, kind, "timeout", "nativeSelector", selectors, snap);
+}
+
+pub fn recordSelectorEvent(tw: *trace.TraceWriter, kind: []const u8, wanted: selector.Selector) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    try payload.writer(tw.allocator).writeAll("{\"selector\":");
+    try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+    try payload.writer(tw.allocator).writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}
+
+pub fn recordActionStatus(tw: *trace.TraceWriter, kind: []const u8, status: []const u8, err: ?anyerror, url: ?[]const u8) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const out = payload.writer(tw.allocator);
+    try out.writeAll("{\"status\":");
+    try trace.writeJsonString(out, status);
+    if (err) |actual| {
+        try out.writeAll(",\"error\":");
+        try trace.writeJsonString(out, @errorName(actual));
+    }
+    if (url) |value| {
+        try out.writeAll(",\"url\":");
+        try trace.writeJsonString(out, value);
+    }
+    try out.writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}
+
+pub fn recordStepError(tw: *trace.TraceWriter, index: usize, err: anyerror) !void {
+    const payload = try std.fmt.allocPrint(
+        tw.allocator,
+        "{{\"index\":{d},\"error\":\"{s}\"}}",
+        .{ index, @errorName(err) },
+    );
+    defer tw.allocator.free(payload);
+    try tw.recordEvent("step.error", payload);
+}
+
+pub fn recordScenarioEnd(
+    tw: *trace.TraceWriter,
+    name: []const u8,
+    status: []const u8,
+    failed_index: ?usize,
+    err: ?anyerror,
+) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const writer = payload.writer(tw.allocator);
+    try writer.writeAll("{\"value\":");
+    try trace.writeJsonString(writer, name);
+    try writer.writeAll(",\"status\":");
+    try trace.writeJsonString(writer, status);
+    if (failed_index) |index| {
+        try writer.print(",\"failedStepIndex\":{d}", .{index});
+    }
+    if (err) |actual| {
+        try writer.writeAll(",\"error\":");
+        try trace.writeJsonString(writer, @errorName(actual));
+    }
+    try writer.writeAll("}");
+    try tw.recordEvent("scenario.end", payload.items);
+}
+
+pub fn recordSelectorMiss(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    wanted: selector.Selector,
+    snap: types.ObservationSnapshot,
+) !void {
+    const selectors = [_]selector.Selector{wanted};
+    try recordDiagnostic(tw, kind, "not_found", selectors[0..], snap);
+}
+
+pub fn recordWaitTimeout(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    selectors: []const selector.Selector,
+    snap: types.ObservationSnapshot,
+) !void {
+    try recordDiagnostic(tw, kind, "timeout", selectors, snap);
+}
+
+pub fn recordObservationRetry(tw: *trace.TraceWriter, kind: []const u8, err: anyerror) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const writer = payload.writer(tw.allocator);
+    try writer.writeAll("{\"status\":\"retry\",\"kind\":");
+    try trace.writeJsonString(writer, kind);
+    try writer.writeAll(",\"error\":");
+    try trace.writeJsonString(writer, @errorName(err));
+    try writer.writeAll("}");
+    try tw.recordEvent("observe.retry", payload.items);
+}
+
+pub fn recordDiagnostic(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    status: []const u8,
+    selectors: []const selector.Selector,
+    snap: types.ObservationSnapshot,
+) !void {
+    try recordDiagnosticWithStrategy(tw, kind, status, null, selectors, snap);
+}
+
+pub fn recordDiagnosticWithStrategy(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    status: []const u8,
+    strategy: ?[]const u8,
+    selectors: []const selector.Selector,
+    snap: types.ObservationSnapshot,
+) !void {
+    try runner_diagnostics.record(tw, kind, status, strategy, selectors, snap);
+}
+
+pub fn writeSelectorDiagnosticJson(
+    writer: anytype,
+    status: []const u8,
+    strategy: ?[]const u8,
+    selectors: []const selector.Selector,
+    snap: types.ObservationSnapshot,
+) !void {
+    try runner_diagnostics.writeSelectorDiagnosticJson(writer, status, strategy, selectors, snap);
+}

package/src/runner_native.zig

@@ -0,0 +1,88 @@
+const std = @import("std");
+const selector = @import("selector.zig");
+const trace = @import("trace.zig");
+
+pub fn tryTapSelector(
+    device: anytype,
+    wanted: selector.Selector,
+    writer: ?*trace.TraceWriter,
+    settle_ms: u64,
+) !bool {
+    if (!@hasDecl(@TypeOf(device.*), "tapBySelector")) return false;
+    const tapped = device.tapBySelector(wanted) catch |err| {
+        if (writer) |tw| try recordSelectorActionFailure(tw, "ui.tap", wanted, err);
+        return err;
+    };
+    if (!tapped) return false;
+    if (writer) |tw| try recordSelectorAction(tw, "ui.tap", wanted, null);
+    try device.settle(settle_ms);
+    return true;
+}
+
+pub fn tryTypeTextSelector(
+    device: anytype,
+    wanted: selector.Selector,
+    text: []const u8,
+    writer: ?*trace.TraceWriter,
+    settle_ms: u64,
+) !bool {
+    if (!@hasDecl(@TypeOf(device.*), "typeTextBySelector")) return false;
+    const typed = device.typeTextBySelector(wanted, text) catch |err| {
+        if (writer) |tw| try recordSelectorActionFailure(tw, "ui.type", wanted, err);
+        return err;
+    };
+    if (!typed) return false;
+    if (writer) |tw| try recordSelectorAction(tw, "ui.type", wanted, null);
+    try device.settle(settle_ms);
+    return true;
+}
+
+pub fn tryEraseTextSelector(
+    device: anytype,
+    wanted: selector.Selector,
+    max_chars: u32,
+    writer: ?*trace.TraceWriter,
+    settle_ms: u64,
+) !bool {
+    if (!@hasDecl(@TypeOf(device.*), "eraseTextBySelector")) return false;
+    const erased = device.eraseTextBySelector(wanted, max_chars) catch |err| {
+        if (writer) |tw| try recordSelectorActionFailure(tw, "ui.eraseText", wanted, err);
+        return err;
+    };
+    if (!erased) return false;
+    if (writer) |tw| try recordSelectorAction(tw, "ui.eraseText", wanted, max_chars);
+    try device.settle(settle_ms);
+    return true;
+}
+
+fn recordSelectorAction(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    wanted: selector.Selector,
+    max_chars: ?u32,
+) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    try payload.writer(tw.allocator).writeAll("{\"status\":\"ok\",\"strategy\":\"nativeSelector\",\"selector\":");
+    try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+    if (max_chars) |value| try payload.writer(tw.allocator).print(",\"maxChars\":{d}", .{value});
+    try payload.writer(tw.allocator).writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}
+
+fn recordSelectorActionFailure(
+    tw: *trace.TraceWriter,
+    kind: []const u8,
+    wanted: selector.Selector,
+    err: anyerror,
+) !void {
+    var payload = std.ArrayList(u8).empty;
+    defer payload.deinit(tw.allocator);
+    const out = payload.writer(tw.allocator);
+    try out.writeAll("{\"status\":\"failed\",\"strategy\":\"nativeSelector\",\"error\":");
+    try trace.writeJsonString(out, @errorName(err));
+    try out.writeAll(",\"selector\":");
+    try trace.writeSelectorJson(out, wanted);
+    try out.writeAll("}");
+    try tw.recordEvent(kind, payload.items);
+}

package/src/runner_waits.zig

@@ -0,0 +1,300 @@
+const std = @import("std");
+const health = @import("health.zig");
+const runner_config = @import("runner_config.zig");
+const runner_events = @import("runner_events.zig");
+const runner_native = @import("runner_native.zig");
+const scenario = @import("scenario.zig");
+const selector = @import("selector.zig");
+const trace = @import("trace.zig");
+
+const RunOptions = runner_config.RunOptions;
+
+pub fn waitUntilVisible(
+    device: anytype,
+    wanted: selector.Selector,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !bool {
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        if (try nativeVisibleBySelector(device, wanted)) |visible| {
+            if (visible) {
+                if (writer) |tw| try runner_events.recordNativeWait(tw, "wait.visible", wanted, null);
+                return true;
+            }
+            if (std.time.milliTimestamp() >= deadline) {
+                if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.visible", &[_]selector.Selector{wanted});
+                return false;
+            }
+            try sleepMs(options.poll_ms);
+            continue;
+        }
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "wait.visible", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+        if (selector.find(snap.nodes, wanted) != null) {
+            if (writer) |tw| try tw.recordEvent("wait.visible", "{\"status\":\"ok\"}");
+            return true;
+        }
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| {
+                const selectors = [_]selector.Selector{wanted};
+                try runner_events.recordWaitTimeout(tw, "wait.visible", selectors[0..], snap);
+            }
+            return false;
+        }
+        try sleepMs(options.poll_ms);
+    }
+}
+
+pub fn waitUntilNotVisible(
+    device: anytype,
+    wanted: selector.Selector,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !bool {
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        if (try nativeVisibleBySelector(device, wanted)) |visible| {
+            if (!visible) {
+                if (writer) |tw| try runner_events.recordNativeWait(tw, "wait.notVisible", wanted, null);
+                return true;
+            }
+            if (std.time.milliTimestamp() >= deadline) {
+                if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.notVisible", &[_]selector.Selector{wanted});
+                return false;
+            }
+            try sleepMs(options.poll_ms);
+            continue;
+        }
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "wait.notVisible", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+        if (selector.find(snap.nodes, wanted) == null) {
+            if (writer) |tw| try tw.recordEvent("wait.notVisible", "{\"status\":\"ok\"}");
+            return true;
+        }
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| {
+                const selectors = [_]selector.Selector{wanted};
+                try runner_events.recordWaitTimeout(tw, "wait.notVisible", selectors[0..], snap);
+            }
+            return false;
+        }
+        try sleepMs(options.poll_ms);
+    }
+}
+
+pub fn waitUntilAnyVisible(
+    device: anytype,
+    selectors: []const selector.Selector,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !?usize {
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        var all_native = true;
+        for (selectors, 0..) |wanted, index| {
+            if (try nativeVisibleBySelector(device, wanted)) |visible| {
+                if (visible) {
+                    if (writer) |tw| try runner_events.recordNativeWait(tw, "wait.any", wanted, index);
+                    return index;
+                }
+            } else {
+                all_native = false;
+                break;
+            }
+        }
+        if (all_native) {
+            if (std.time.milliTimestamp() >= deadline) {
+                if (writer) |tw| try runner_events.recordNativeWaitTimeoutWithDiagnostics(device, tw, "wait.any", selectors);
+                return null;
+            }
+            try sleepMs(options.poll_ms);
+            continue;
+        }
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "wait.any", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+        for (selectors, 0..) |wanted, index| {
+            if (selector.find(snap.nodes, wanted)) |node| {
+                if (writer) |tw| {
+                    var payload = std.ArrayList(u8).empty;
+                    defer payload.deinit(tw.allocator);
+                    try payload.writer(tw.allocator).print("{{\"status\":\"ok\",\"matchedIndex\":{d},\"target\":\"{s}\",\"selector\":", .{ index, node.stable_id });
+                    try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+                    try payload.writer(tw.allocator).writeAll("}");
+                    try tw.recordEvent("wait.any", payload.items);
+                }
+                return index;
+            }
+        }
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| try runner_events.recordWaitTimeout(tw, "wait.any", selectors, snap);
+            return null;
+        }
+        try sleepMs(options.poll_ms);
+    }
+}
+
+pub fn assertNoneVisible(
+    device: anytype,
+    selectors: []const selector.Selector,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !bool {
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "assert.noneVisible", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+
+        var matched = false;
+        for (selectors) |wanted| {
+            if (selector.find(snap.nodes, wanted) != null) {
+                matched = true;
+                break;
+            }
+        }
+
+        if (!matched) {
+            if (writer) |tw| try tw.recordEvent("assert.noneVisible", "{\"status\":\"ok\"}");
+            return true;
+        }
+
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| try runner_events.recordDiagnostic(tw, "assert.noneVisible", "visible", selectors, snap);
+            return false;
+        }
+
+        try sleepMs(options.poll_ms);
+    }
+}
+
+pub fn assertHealthy(
+    device: anytype,
+    timeout_ms: u64,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !bool {
+    const health_selectors = health.defaultSelectors();
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "assert.healthy", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+
+        if (!health.hasUnhealthyOverlay(snap.nodes)) {
+            if (writer) |tw| try tw.recordEvent("assert.healthy", "{\"status\":\"ok\"}");
+            return true;
+        }
+
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| try runner_events.recordDiagnostic(tw, "assert.healthy", "unhealthy", health_selectors, snap);
+            return false;
+        }
+
+        try sleepMs(options.poll_ms);
+    }
+}
+
+pub fn scrollUntilVisible(
+    device: anytype,
+    wanted: selector.Selector,
+    timeout_ms: u64,
+    direction: scenario.ScrollDirection,
+    writer: ?*trace.TraceWriter,
+    options: RunOptions,
+) !bool {
+    const deadline = std.time.milliTimestamp() + @as(i64, @intCast(timeout_ms));
+    while (true) {
+        var snap = device.snapshot(writer) catch |err| {
+            if (try retryTransientObservation(err, "ui.scrollUntilVisible", writer, deadline, options)) continue;
+            return err;
+        };
+        defer snap.deinit(device.allocator);
+        if (selector.find(snap.nodes, wanted)) |node| {
+            if (writer) |tw| {
+                var payload = std.ArrayList(u8).empty;
+                defer payload.deinit(tw.allocator);
+                try payload.writer(tw.allocator).print("{{\"status\":\"ok\",\"target\":\"{s}\",\"selector\":", .{node.stable_id});
+                try trace.writeSelectorJson(payload.writer(tw.allocator), wanted);
+                try payload.writer(tw.allocator).writeAll("}");
+                try tw.recordEvent("ui.scrollUntilVisible", payload.items);
+            }
+            return true;
+        }
+        if (std.time.milliTimestamp() >= deadline) {
+            if (writer) |tw| {
+                const selectors = [_]selector.Selector{wanted};
+                try runner_events.recordWaitTimeout(tw, "ui.scrollUntilVisible", selectors[0..], snap);
+            }
+            return false;
+        }
+
+        const width = if (snap.viewport.width == 0) @as(i32, 720) else @as(i32, @intCast(snap.viewport.width));
+        const height = if (snap.viewport.height == 0) @as(i32, 1280) else @as(i32, @intCast(snap.viewport.height));
+        const x = @divTrunc(width, 2);
+        const start_y = switch (direction) {
+            .down => @divTrunc(height * 4, 5),
+            .up => @divTrunc(height * 3, 10),
+        };
+        const end_y = switch (direction) {
+            .down => @divTrunc(height * 3, 10),
+            .up => @divTrunc(height * 4, 5),
+        };
+        try device.swipe(x, start_y, x, end_y, 350);
+        if (writer) |tw| {
+            const payload = try std.fmt.allocPrint(tw.allocator, "{{\"direction\":\"{s}\",\"x\":{d},\"y1\":{d},\"y2\":{d}}}", .{
+                if (direction == .down) "down" else "up",
+                x,
+                start_y,
+                end_y,
+            });
+            defer tw.allocator.free(payload);
+            try tw.recordEvent("ui.scroll", payload);
+        }
+        try settleDevice(device, options);
+    }
+}
+
+fn nativeVisibleBySelector(device: anytype, wanted: selector.Selector) !?bool {
+    if (!@hasDecl(@TypeOf(device.*), "visibleBySelector")) return null;
+    return try device.visibleBySelector(wanted);
+}
+
+fn retryTransientObservation(
+    err: anyerror,
+    kind: []const u8,
+    writer: ?*trace.TraceWriter,
+    deadline: i64,
+    options: RunOptions,
+) !bool {
+    if (err != error.CommandTimedOut) return false;
+    if (std.time.milliTimestamp() >= deadline) return false;
+    if (writer) |tw| try runner_events.recordObservationRetry(tw, kind, err);
+    try sleepMs(options.poll_ms);
+    return true;
+}
+
+fn settleDevice(device: anytype, options: RunOptions) !void {
+    try device.settle(options.settle_ms);
+}
+
+fn sleepMs(ms: u64) !void {
+    std.Thread.sleep(ms * std.time.ns_per_ms);
+}