//! 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. //! //! # comment //! click 710 320 move there, press and release the left button //! move|down|up X Y one pointer event, then a frame //! wheel|wheel-x X Y DELTA //! cancel what losing focus sends //! key NAME press and release a key (`sketch.Key` names) //! type TEXT text input, as typed into a focused field //! console LINE run a console command (`console get` //! takes no frame: it only reads) //! frames N advance N frames without input //! expect FIELD VALUE compare a state field (enums by name or number); //! FIELD may index arrays and vector lanes, //! `boids.buffer[3].pos[0]` //! expect FIELD VALUE ~T numbers within T of VALUE //! await FIELD VALUE [~T] run frames until it holds (a minute at most) //! print FIELD write a field's value to stderr (a vector, //! array or struct: every value in it), no frame //! expect-snapshot NAME live state equals the newest mark NAME, leaf //! by leaf (padding ignored, and leaves a layout //! change reset), exactly //! expect-key WHY FIELD VALUE //! the newest keyframe of this session taken for //! WHY (`Sessions.Why`: before_reload, mark...) //! holds VALUE, read in its own layout //! expect-log TEXT a recent console line contains TEXT //! expect-no-log TEXT no recent console line does //! expect-audio KEY stream KEY has received samples, or voice //! KEY sounded since the last check of it //! expect-no-audio KEY voice KEY did not sound since the last check //! screenshot FILE save the next frame as PNG //! expect-same-screenshot A B [MAX [X Y W H]] //! two saved PNGs match, every channel within MAX //! (default 0), in the rect if given (pixels) //! expect-different-screenshot A B [X Y W H] //! two saved PNGs differ somewhere (in the rect) //! expect-pixel FILE X Y R G B A [TOL] //! a saved PNG's pixel, every channel within TOL //! load LIBRARY swap in another build of the sketch //! reload load the watched library again //! await-reload SECONDS run frames until a build replaces the library //! kill die by SIGKILL, as a crash would //! //! `{name}` is replaced by `--define name=value` from the command line. //! //! Each line but `frames`, `print`, `console get`, the expectations and //! `await-reload` is followed by one frame; `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; 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 command = words.next().?; const rest = std.mem.trim(u8, words.rest(), " \t"); step(host, arena.allocator(), command, rest, &words, &now) 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; } fn step(host: *Host, arena: std.mem.Allocator, command: []const u8, rest: []const u8, words: anytype, now: *u64) !void { const eq = std.mem.eql; if (eq(u8, command, "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) }); } else if (eq(u8, command, "move") or eq(u8, command, "down") or eq(u8, command, "up")) { const x, const y = try point(words); const kind: abi.Event.Kind = if (eq(u8, command, "move")) .mouse_move else if (eq(u8, command, "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) }); } else if (eq(u8, command, "wheel") or eq(u8, command, "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 (eq(u8, command, "wheel-x")) .wheel_horizontal else .wheel, .time = now.*, .x = x, .y = y, .value = @bitCast(delta), .flags = held(host) }); } else if (eq(u8, command, "cancel")) { try host.route(.{ .kind = .cancel, .time = now.* }); } else if (eq(u8, command, "key")) { const key = std.meta.stringToEnum(abi.Key, rest) orelse return error.UnknownKey; try host.route(.{ .kind = .key_down, .time = now.*, .code = @backingInt(key) }); try host.route(.{ .kind = .key_up, .time = now.*, .code = @backingInt(key) }); } else if (eq(u8, command, "hold") or eq(u8, command, "release")) { const key = std.meta.stringToEnum(abi.Key, rest) orelse return error.UnknownKey; try host.route(.{ .kind = if (eq(u8, command, "hold")) .key_down else .key_up, .time = now.*, .code = @backingInt(key) }); } else if (eq(u8, command, "type")) { for (rest) |byte| try host.route(.{ .kind = .text, .time = now.*, .value = byte }); } else if (eq(u8, command, "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; } else if (eq(u8, command, "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() }); return; } else if (eq(u8, command, "frames")) { const count = try std.fmt.parseInt(usize, rest, 10); for (0..count) |_| try advance(host, now); return; } else if (eq(u8, command, "expect") or eq(u8, command, "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 (eq(u8, command, "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; } return; } else if (eq(u8, command, "expect-snapshot")) { const saved = try Console.markState(host, arena, rest); if (!same(host, saved.layout, saved.bytes, rest)) return error.ExpectationFailed; return; } else if (eq(u8, command, "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; } else if (eq(u8, command, "expect-log") or eq(u8, command, "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 != eq(u8, command, "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; } return; } else if (eq(u8, command, "expect-same-screenshot") or eq(u8, command, "expect-different-screenshot")) { const a = words.next() orelse return error.ExpectedFile; const b = words.next() orelse return error.ExpectedFile; const want_same = eq(u8, command, "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; } return; } else if (eq(u8, command, "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; }; return; } else if (eq(u8, command, "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; return; } else if (eq(u8, command, "expect-no-audio")) { if (host.audio.sounded(try std.fmt.parseInt(u32, rest, 10))) return error.ExpectationFailed; return; } else if (eq(u8, command, "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); } else if (eq(u8, command, "load")) { try host.load(rest); } else if (eq(u8, command, "reload")) { try host.reload(); } else if (eq(u8, command, "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); } return; } else if (eq(u8, command, "kill")) { // A crash, for tests of what survives one: SIGKILL, no cleanup. _ = std.os.linux.kill(std.os.linux.getpid(), .KILL); return; } else if (eq(u8, command, "quit")) { host.quit = true; return; } else return error.UnknownScriptCommand; try advance(host, now); } /// The modifiers `hold` has down, for a pointer event's `flags`. fn held(host: *const Host) u8 { var mods: u32 = 0; if (host.input.held(abi.Key.left_shift) or host.input.held(abi.Key.right_shift)) mods |= abi.Key.Mod.shift; if (host.input.held(abi.Key.left_ctrl) or host.input.held(abi.Key.right_ctrl)) mods |= abi.Key.Mod.ctrl; if (host.input.held(abi.Key.left_alt) or host.input.held(abi.Key.right_alt)) mods |= abi.Key.Mod.alt; if (host.input.held(abi.Key.left_gui) or host.input.held(abi.Key.right_gui)) mods |= abi.Key.Mod.gui; return abi.Event.withModifiers(mods); } /// "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; }