//! End-to-end scripts: plain text that plays a sketch like a person would, //! through the same routing and frames, on a fixed 60 Hz clock. A line is //! a verb of `verbs` and its words; `# comment`; `{name}` is replaced by //! `--define name=value` from the command line. `update` gets one call per //! frame, live or replayed, so `console play` then `frames N` replays N //! recorded frames at the script's 60 Hz. const std = @import("std"); const c = @import("c"); const abi = @import("abi"); const Host = @import("Host.zig"); const fields = @import("fields.zig"); const memory = @import("memory.zig"); const Console = @import("Console.zig"); const Sessions = @import("Sessions.zig"); pub const frame_ns: u64 = std.time.ns_per_s / 60; /// The most frames `await` plays: a minute. const await_limit = 60 * 60; /// The script's verbs, a row each. A verb with `frame` is followed by one /// frame; the `input` verbs are also what a 9P `ctl` takes live (`input`). pub const Verb = enum { click, move, down, up, wheel, @"wheel-x", cancel, key, hold, release, type, console, frames, expect, await, print, @"expect-snapshot", @"expect-key", @"expect-log", @"expect-no-log", @"expect-audio", @"expect-no-audio", screenshot, @"expect-same-screenshot", @"expect-different-screenshot", @"expect-pixel", load, reload, @"await-reload", kill, quit }; pub const Row = struct { args: []const u8 = "", doc: []const u8, frame: bool = false, input: bool = false }; pub const verbs = std.enums.EnumArray(Verb, Row).init(.{ .click = .{ .args = "X Y", .doc = "move there, press and release the left button", .frame = true, .input = true }, .move = .{ .args = "X Y", .doc = "a pointer move", .frame = true, .input = true }, .down = .{ .args = "X Y", .doc = "the left button down there", .frame = true, .input = true }, .up = .{ .args = "X Y", .doc = "the left button up there", .frame = true, .input = true }, .wheel = .{ .args = "X Y DELTA", .doc = "a wheel turn", .frame = true, .input = true }, .@"wheel-x" = .{ .args = "X Y DELTA", .doc = "a sideways wheel turn", .frame = true, .input = true }, .cancel = .{ .doc = "what losing focus sends", .frame = true, .input = true }, .key = .{ .args = "NAME", .doc = "press and release a key (`sketch.Key` names)", .frame = true, .input = true }, .hold = .{ .args = "NAME", .doc = "a key down until released, for modifiers", .frame = true, .input = true }, .release = .{ .args = "NAME", .doc = "a held key up", .frame = true, .input = true }, .type = .{ .args = "TEXT", .doc = "text input, as typed into a focused field", .frame = true, .input = true }, .console = .{ .args = "LINE", .doc = "a console line (`console get` takes no frame: it only reads); one that fails fails the script", .frame = true }, .frames = .{ .args = "N", .doc = "N frames without input" }, .expect = .{ .args = "FIELD VALUE [~T]", .doc = "a State field holds VALUE (enums by name or number; numbers within T); FIELD may index arrays and vector lanes, `boids.buffer[3].pos[0]`" }, .await = .{ .args = "FIELD VALUE [~T]", .doc = "frames until expect holds, a minute at most" }, .print = .{ .args = "FIELD", .doc = "a field's value to stderr (a vector, array or struct: every value in it)" }, .@"expect-snapshot" = .{ .args = "NAME", .doc = "live State equals the newest mark NAME, leaf by leaf (padding, and leaves a layout change reset, ignored)" }, .@"expect-key" = .{ .args = "WHY FIELD VALUE", .doc = "the newest keyframe of this session taken for WHY (`Sessions.Why`: before_reload, mark...) holds VALUE, read in its own layout" }, .@"expect-log" = .{ .args = "TEXT", .doc = "a recent console line contains TEXT" }, .@"expect-no-log" = .{ .args = "TEXT", .doc = "no recent console line does" }, .@"expect-audio" = .{ .args = "KEY", .doc = "stream KEY has received samples, or voice KEY sounded since the last check of it" }, .@"expect-no-audio" = .{ .args = "KEY", .doc = "voice KEY did not sound since the last check" }, .screenshot = .{ .args = "FILE", .doc = "save the next frame as PNG", .frame = true }, .@"expect-same-screenshot" = .{ .args = "A B [MAX [X Y W H]]", .doc = "two saved PNGs match, every channel within MAX (0), in the rect if given (pixels)" }, .@"expect-different-screenshot" = .{ .args = "A B [X Y W H]", .doc = "two saved PNGs differ somewhere (in the rect)" }, .@"expect-pixel" = .{ .args = "FILE X Y R G B A [TOL]", .doc = "a saved PNG's pixel, every channel within TOL" }, .load = .{ .args = "LIBRARY", .doc = "swap in another build of the sketch", .frame = true }, .reload = .{ .doc = "load the watched library again", .frame = true }, .@"await-reload" = .{ .args = "SECONDS", .doc = "frames until a build replaces the library" }, .kill = .{ .doc = "die by SIGKILL, as a crash would" }, .quit = .{ .doc = "end the run" }, }); pub fn run(host: *Host, source: []const u8, defines: []const [2][]const u8) !void { var arena: std.heap.ArenaAllocator = .init(host.gpa); defer arena.deinit(); var now: u64 = std.time.ns_per_s; var failures: usize = 0; var lines = std.mem.splitScalar(u8, source, '\n'); var number: usize = 0; while (lines.next()) |raw| { number += 1; const line = try substitute(arena.allocator(), std.mem.trim(u8, raw, " \t\r"), defines); if (line.len == 0 or line[0] == '#') continue; var words = std.mem.tokenizeAny(u8, line, " \t"); const verb = std.meta.stringToEnum(Verb, words.next().?); const rest = std.mem.trim(u8, words.rest(), " \t"); (if (verb) |v| step(host, arena.allocator(), v, rest, &words, &now) else error.UnknownScriptCommand) catch |err| { failures += 1; std.debug.print("script:{d}: {s}: {t}\n", .{ number, line, err }); if (err != error.ExpectationFailed) break; }; if (host.quit) break; } if (failures > 0) return error.ScriptFailed; } /// Routes an input verb's events at `now`, no frame after: a script's /// line, or a 9P `ctl` line live. pub fn input(host: *Host, verb: Verb, words: *std.mem.TokenIterator(u8, .any), now: u64) !void { const rest = std.mem.trim(u8, words.rest(), " \t"); switch (verb) { .click => { const x, const y = try point(words); try host.route(.{ .kind = .mouse_move, .time = now, .x = x, .y = y, .flags = held(host) }); try host.route(.{ .kind = .mouse_down, .time = now, .x = x, .y = y, .code = 1, .flags = held(host) }); try host.route(.{ .kind = .mouse_up, .time = now, .x = x, .y = y, .code = 1, .flags = held(host) }); }, .move, .down, .up => { const x, const y = try point(words); const kind: abi.Event.Kind = switch (verb) { .move => .mouse_move, .down => .mouse_down, else => .mouse_up, }; try host.route(.{ .kind = kind, .time = now, .x = x, .y = y, .code = if (kind == .mouse_move) 0 else 1, .flags = held(host) }); }, .wheel, .@"wheel-x" => { const x, const y = try point(words); const delta = try std.fmt.parseFloat(f32, words.next() orelse return error.ExpectedDelta); try host.route(.{ .kind = if (verb == .@"wheel-x") .wheel_horizontal else .wheel, .time = now, .x = x, .y = y, .value = @bitCast(delta), .flags = held(host) }); }, .cancel => try host.route(.{ .kind = .cancel, .time = now }), .key => { const key = std.meta.stringToEnum(abi.Key, rest) orelse return error.UnknownKey; // with the modifiers `hold` has down, as a window's key carries them try host.route(.{ .kind = .key_down, .time = now, .code = @backingInt(key), .value = mods(host) }); try host.route(.{ .kind = .key_up, .time = now, .code = @backingInt(key), .value = mods(host) }); }, .hold, .release => { const key = std.meta.stringToEnum(abi.Key, rest) orelse return error.UnknownKey; try host.route(.{ .kind = if (verb == .hold) .key_down else .key_up, .time = now, .code = @backingInt(key) }); }, .type => for (rest) |byte| try host.route(.{ .kind = .text, .time = now, .value = byte }), else => return error.NotInput, } } fn step(host: *Host, arena: std.mem.Allocator, verb: Verb, rest: []const u8, words: *std.mem.TokenIterator(u8, .any), now: *u64) !void { switch (verb) { .click, .move, .down, .up, .wheel, .@"wheel-x", .cancel, .key, .hold, .release, .type => try input(host, verb, words, now.*), .console => { // A failing console line fails the script, like a failed expect. host.runLine(rest, now.*) catch |err| { std.debug.print(" console {s}: {t}\n", .{ rest, err }); return err; }; if (std.mem.startsWith(u8, rest, "get ")) return; }, .print => { const path = words.next() orelse return error.ExpectedField; var buf: [4096]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); fields.formatPath(host.state.layout, host.live(), path, &w) catch |err| switch (err) { error.UnknownField => return error.UnknownField, error.WriteFailed => {}, }; std.debug.print("{s} = {s}\n", .{ path, w.buffered() }); }, .frames => { const count = try std.fmt.parseInt(usize, rest, 10); for (0..count) |_| try advance(host, now); }, .expect, .await => { const path = words.next() orelse return error.ExpectedField; const want, const tolerance = try expected(std.mem.trim(u8, words.rest(), " \t")); // Looked up again after each frame: a reload may move the field. _ = host.state.layout.find(path) orelse return error.UnknownField; // `await` plays frames until the field holds the value, for up to a // minute: for waits whose length is the sketch's business. if (verb == .await) { var waited: usize = 0; while (!holds(host, path, want, tolerance) and waited < await_limit) : (waited += 1) try advance(host, now); } if (!holds(host, path, want, tolerance)) { var buf: [128]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); fields.formatPath(host.state.layout, host.live(), path, &w) catch |err| switch (err) { error.UnknownField => w.writeAll("no such field") catch {}, error.WriteFailed => {}, }; if (tolerance) |t| { std.debug.print(" {s}: expected {s} ~{d}, found {s}\n", .{ path, want, t, w.buffered() }); } else std.debug.print(" {s}: expected {s}, found {s}\n", .{ path, want, w.buffered() }); return error.ExpectationFailed; } }, .@"expect-snapshot" => { const saved = try Console.markState(host, arena, rest); if (!same(host, saved.layout, saved.bytes, rest)) return error.ExpectationFailed; }, .@"expect-key" => { const why = std.meta.stringToEnum(Sessions.Why, words.next() orelse "") orelse return error.UnknownWhy; const path = words.next() orelse return error.ExpectedField; const want = std.mem.trim(u8, words.rest(), " \t"); const s = &host.sessions; try s.commit(.none); var k = s.keys; while (k > 0) { k -= 1; const key = try s.load(s.session, k); defer key.free(host.gpa); if (key.why != why) continue; const leaf = (try memory.layoutOf(arena, key.layout)).find(path) orelse return error.UnknownField; if (fields.matches(leaf, key.state, want)) return; var buf: [128]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); fields.format(leaf, key.state, &w) catch {}; std.debug.print(" {s} keyframe {d}: {s} expected {s}, found {s}\n", .{ @tagName(why), k, path, want, w.buffered() }); return error.ExpectationFailed; } std.debug.print(" no {s} keyframe in this session\n", .{@tagName(why)}); return error.ExpectationFailed; }, .@"expect-log", .@"expect-no-log" => { var found = false; for (&host.console.lines) |*l| { if (std.mem.indexOf(u8, l.bytes[0..l.len], rest) != null) found = true; } if (found != (verb == .@"expect-log")) { std.debug.print(" console log:\n", .{}); for (&host.console.lines) |*l| std.debug.print(" {s}\n", .{l.bytes[0..l.len]}); return error.ExpectationFailed; } }, .@"expect-same-screenshot", .@"expect-different-screenshot" => { const a = words.next() orelse return error.ExpectedFile; const b = words.next() orelse return error.ExpectedFile; const want_same = verb == .@"expect-same-screenshot"; const max: u8 = if (!want_same) 0 else if (words.next()) |m| std.fmt.parseInt(u8, m, 10) catch return error.InvalidValue else 0; var rect: ?[4]usize = null; if (words.next()) |x| { var r: [4]usize = undefined; r[0] = std.fmt.parseInt(usize, x, 10) catch return error.InvalidRect; for (r[1..]) |*v| v.* = std.fmt.parseInt(usize, words.next() orelse return error.InvalidRect, 10) catch return error.InvalidRect; rect = r; } const diff = try comparePng(arena, a, b, max, rect); if ((diff.count == 0) != want_same) { if (want_same) { std.debug.print(" {s} vs {s}: {d} pixels differ by more than {d}, first at {d},{d}\n", .{ a, b, diff.count, max, diff.first[0], diff.first[1] }); } else std.debug.print(" {s} and {s} are the same\n", .{ a, b }); return error.ExpectationFailed; } }, .@"expect-pixel" => { const file = words.next() orelse return error.ExpectedFile; var n: [7]u8 = .{ 0, 0, 0, 0, 0, 0, 0 }; var x: usize = 0; var y: usize = 0; for (0..7) |i| { const word = words.next() orelse if (i == 6) break else return error.ExpectedPixel; if (i < 2) { (if (i == 0) &x else &y).* = std.fmt.parseInt(usize, word, 10) catch return error.ExpectedPixel; } else n[i - 2] = std.fmt.parseInt(u8, word, 0) catch return error.ExpectedPixel; } const tol = n[4]; const surface = try loadPng(arena, file); defer c.SDL_DestroySurface(surface); if (x >= surface.*.w or y >= surface.*.h) return error.OutsideScreenshot; const p = (@as([*]const u8, @ptrCast(surface.*.pixels.?)) + y * @as(usize, @intCast(surface.*.pitch)) + x * 4)[0..4]; for (p, n[0..4]) |got, want| if (@max(got, want) - @min(got, want) > tol) { std.debug.print(" {s} at {d},{d}: expected {d} {d} {d} {d}, found {d} {d} {d} {d}\n", .{ file, x, y, n[0], n[1], n[2], n[3], p[0], p[1], p[2], p[3] }); return error.ExpectationFailed; }; }, .@"expect-audio" => { const key = try std.fmt.parseInt(u32, rest, 10); if (host.input.stream(key).pushed == 0 and !host.audio.sounded(key)) return error.ExpectationFailed; }, .@"expect-no-audio" => { if (host.audio.sounded(try std.fmt.parseInt(u32, rest, 10))) return error.ExpectationFailed; }, .screenshot => { if (std.fs.path.dirname(rest)) |dir| try std.Io.Dir.cwd().createDirPath(host.io, dir); host.screenshot = try arena.dupeSentinel(u8, rest, 0); }, .load => { try host.load(rest); }, .reload => { try host.reload(); }, .@"await-reload" => { const seconds = try std.fmt.parseInt(u64, rest, 10); const start = host.reloads; const deadline = std.Io.Timestamp.now(host.io, .awake).nanoseconds + @as(i96, seconds) * std.time.ns_per_s; while (host.reloads == start) { if (std.Io.Timestamp.now(host.io, .awake).nanoseconds > deadline) return error.NoReload; try advance(host, now); try std.Io.sleep(host.io, .fromMilliseconds(10), .awake); } }, .kill => { // A crash, for tests of what survives one: SIGKILL, no cleanup. _ = std.os.linux.kill(std.os.linux.getpid(), .KILL); }, .quit => { host.quit = true; }, } if (verbs.get(verb).frame) try advance(host, now); } /// The modifiers `hold` has down, as `Key.Mod` bits: a key event's `value`. fn mods(host: *const Host) u32 { var m: u32 = 0; if (host.input.held(abi.Key.left_shift) or host.input.held(abi.Key.right_shift)) m |= abi.Key.Mod.shift; if (host.input.held(abi.Key.left_ctrl) or host.input.held(abi.Key.right_ctrl)) m |= abi.Key.Mod.ctrl; if (host.input.held(abi.Key.left_alt) or host.input.held(abi.Key.right_alt)) m |= abi.Key.Mod.alt; if (host.input.held(abi.Key.left_gui) or host.input.held(abi.Key.right_gui)) m |= abi.Key.Mod.gui; return m; } /// The same, for a pointer event's `flags`. fn held(host: *const Host) u8 { return abi.Event.withModifiers(mods(host)); } /// "VALUE" or "VALUE ~TOLERANCE". fn expected(text: []const u8) !struct { []const u8, ?f64 } { const tilde = std.mem.lastIndexOfScalar(u8, text, '~') orelse return .{ text, null }; const tolerance = std.fmt.parseFloat(f64, std.mem.trim(u8, text[tilde + 1 ..], " \t")) catch return error.InvalidTolerance; return .{ std.mem.trim(u8, text[0..tilde], " \t"), tolerance }; } fn holds(host: *Host, path: []const u8, want: []const u8, tolerance: ?f64) bool { const leaf = host.state.layout.find(path) orelse return false; const t = tolerance orelse return fields.matches(leaf, host.live(), want); const value = fields.number(leaf, host.live()) orelse return false; const target = std.fmt.parseFloat(f64, want) catch return false; return @abs(value - target) <= t; } /// Live state against mark `name`'s (`saved`, taken in layout `from`), leaf /// by leaf over the leaves migration kept; prints the first few differences. fn same(host: *Host, from: memory.Layout, saved: []const u8, name: []const u8) bool { const layout = host.state.layout; const live = host.live(); var count: usize = 0; for (layout.fields) |leaf| { if (leaf.whole() or (from.hash != layout.hash and !memory.keeps(from, leaf))) continue; var it = leaf.elements(); while (it.next()) |offset| { if (std.mem.eql(u8, live[offset..][0..leaf.size], saved[offset..][0..leaf.size])) continue; count += 1; if (count > 5) continue; var buf: [256]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); leaf.name(offset, &w) catch {}; w.writeAll(": live ") catch {}; fields.format(leaf.at(offset), live, &w) catch {}; w.print(", snapshot {s} ", .{name}) catch {}; fields.format(leaf.at(offset), saved, &w) catch {}; std.debug.print(" {s}\n", .{w.buffered()}); } } if (count > 5) std.debug.print(" ... {d} differing values in all\n", .{count}); return count == 0; } const PngDiff = struct { count: usize = 0, first: [2]usize = .{ 0, 0 } }; /// Pixels whose channels differ by more than `max`; a size mismatch /// counts every pixel. fn comparePng(arena: std.mem.Allocator, a: []const u8, b: []const u8, max: u8, rect: ?[4]usize) !PngDiff { const sa = try loadPng(arena, a); defer c.SDL_DestroySurface(sa); const sb = try loadPng(arena, b); defer c.SDL_DestroySurface(sb); if (sa.*.w != sb.*.w or sa.*.h != sb.*.h) return .{ .count = @intCast(@max(sa.*.w * sa.*.h, sb.*.w * sb.*.h, 1)) }; var diff: PngDiff = .{}; const w: usize = @intCast(sa.*.w); const h: usize = @intCast(sa.*.h); const r = rect orelse [4]usize{ 0, 0, w, h }; for (@min(r[1], h)..@min(r[1] + r[3], h)) |y| { const ra: [*]const u8 = @as([*]const u8, @ptrCast(sa.*.pixels.?)) + y * @as(usize, @intCast(sa.*.pitch)); const rb: [*]const u8 = @as([*]const u8, @ptrCast(sb.*.pixels.?)) + y * @as(usize, @intCast(sb.*.pitch)); for (@min(r[0], w)..@min(r[0] + r[2], w)) |x| { const differs = for (0..4) |i| { const p = ra[x * 4 + i]; const q = rb[x * 4 + i]; if (@max(p, q) - @min(p, q) > max) break true; } else false; if (!differs) continue; if (diff.count == 0) diff.first = .{ x, y }; diff.count += 1; } } return diff; } fn loadPng(arena: std.mem.Allocator, path: []const u8) !*c.SDL_Surface { const loaded = c.SDL_LoadPNG((try arena.dupeSentinel(u8, path, 0)).ptr) orelse { std.debug.print(" {s}: {s}\n", .{ path, c.SDL_GetError() }); return error.ScreenshotUnreadable; }; defer c.SDL_DestroySurface(loaded); return c.SDL_ConvertSurface(loaded, c.SDL_PIXELFORMAT_RGBA32) orelse error.ScreenshotUnreadable; } fn advance(host: *Host, now: *u64) !void { try host.frame(now.*); now.* += frame_ns; } fn point(words: anytype) !struct { f32, f32 } { const x = try std.fmt.parseFloat(f32, words.next() orelse return error.ExpectedPoint); const y = try std.fmt.parseFloat(f32, words.next() orelse return error.ExpectedPoint); return .{ x, y }; } fn substitute(arena: std.mem.Allocator, line: []const u8, defines: []const [2][]const u8) ![]const u8 { var out = line; for (defines) |pair| { const pattern = try std.fmt.allocPrint(arena, "{{{s}}}", .{pair[0]}); out = try std.mem.replaceOwned(u8, arena, out, pattern, pair[1]); } return out; }