webview-preview 0.0.0-stage → 1.0.0

package/src/engines/webkitgtk.py

@@ -0,0 +1,318 @@
+import argparse
+import json
+import os
+import sys
+
+os.environ.setdefault("GDK_BACKEND", "x11")
+
+import gi
+
+gi.require_version("Gdk", "3.0")
+gi.require_version("Gtk", "3.0")
+gi.require_version("WebKit2", "4.1")
+
+from gi.repository import Gdk, GLib, Gtk, WebKit2
+
+INPUT_SETTLE_MS = 50
+GDK_KEY_NAMES = {
+    "Tab": "Tab", "Enter": "Return", "Escape": "Escape", "Backspace": "BackSpace", "Delete": "Delete",
+    "Insert": "Insert", "Space": "space", "Home": "Home", "End": "End", "PageUp": "Page_Up", "PageDown": "Page_Down",
+    "ArrowUp": "Up", "ArrowDown": "Down", "ArrowLeft": "Left", "ArrowRight": "Right",
+    **{f"F{number}": f"F{number}" for number in range(1, 13)}
+}
+MODIFIER_KEYS = {"Shift": "Shift_L", "Control": "Control_L", "Alt": "Alt_L", "Meta": "Super_L"}
+MODIFIER_MASKS = {
+    "Shift": Gdk.ModifierType.SHIFT_MASK,
+    "Control": Gdk.ModifierType.CONTROL_MASK,
+    "Alt": Gdk.ModifierType.MOD1_MASK,
+    "Meta": Gdk.ModifierType.SUPER_MASK
+}
+
+
+def emit(kind, value):
+    sys.stdout.write(f"{kind}\t{json.dumps(value)}\n")
+    sys.stdout.flush()
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("url")
+    parser.add_argument("--steps", required=True)
+    parser.add_argument("--init", required=True)
+    parser.add_argument("--init-errors", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--prefix", required=True)
+    parser.add_argument("--width", type=int, required=True)
+    parser.add_argument("--height", type=int, required=True)
+    parser.add_argument("--snap-margin", type=int, required=True)
+    parser.add_argument("--headed", action="store_true")
+    parser.add_argument("--keep-storage", action="store_true")
+    parser.add_argument("--wait-for-timeout-ms", type=int, required=True)
+    parser.add_argument("--wait-for-poll-ms", type=int, required=True)
+    parser.add_argument("--load-settle-ms", type=int, required=True)
+    parser.add_argument("--js-settle-ms", type=int, required=True)
+    parser.add_argument("--timeout-ms", type=int, required=True)
+    return parser.parse_args()
+
+
+def describe(value):
+    if value.is_string():
+        return value.to_string()
+    if value.is_undefined():
+        return "undefined"
+    return value.to_json(0) or value.to_string()
+
+
+def keyval_for(key):
+    if key in GDK_KEY_NAMES:
+        return Gdk.keyval_from_name(GDK_KEY_NAMES[key])
+    return Gdk.unicode_to_keyval(ord(key))
+
+
+def main():
+    args = parse_args()
+    steps = json.loads(args.steps)
+    init_scripts = json.loads(args.init)
+    os.makedirs(args.out, exist_ok=True)
+
+    window = Gtk.Window(title="webview-preview") if args.headed else Gtk.OffscreenWindow()
+    window.set_default_size(args.width, args.height)
+    window.set_size_request(args.width, args.height)
+    manager = WebKit2.UserContentManager()
+    for source in init_scripts:
+        manager.add_script(WebKit2.UserScript.new(
+            source,
+            WebKit2.UserContentInjectedFrames.TOP_FRAME,
+            WebKit2.UserScriptInjectionTime.START,
+            None,
+            None
+        ))
+    view = WebKit2.WebView(user_content_manager=manager, is_ephemeral=not args.keep_storage)
+    window.add(view)
+    window.show_all()
+
+    display = Gdk.Display.get_default()
+    seat = display.get_default_seat()
+    keymap = Gdk.Keymap.get_for_display(display)
+    state = {"index": 0, "failed": False, "started": False}
+
+    def finish(failed=False):
+        state["failed"] = state["failed"] or failed
+        Gtk.main_quit()
+        return False
+
+    def step_failed(message):
+        state["failed"] = True
+        emit("error", message)
+
+    def deliver(event):
+        if args.headed:
+            Gtk.main_do_event(event)
+        else:
+            window.event(event)
+
+    def focus_window():
+        event = Gdk.Event.new(Gdk.EventType.FOCUS_CHANGE)
+        event.focus_change.window = window.get_window()
+        event.focus_change.send_event = 1
+        event.focus_change.in_ = 1
+        event.set_device(seat.get_keyboard())
+        deliver(event)
+        view.grab_focus()
+
+    def key_event(kind, keyval, mask):
+        found, entries = keymap.get_entries_for_keyval(keyval)
+        event = Gdk.Event.new(kind)
+        event.key.window = window.get_window()
+        event.key.send_event = 1
+        event.key.time = Gtk.get_current_event_time()
+        event.key.keyval = keyval
+        event.key.state = mask
+        if found and entries:
+            event.key.hardware_keycode = entries[0].keycode
+        event.set_device(seat.get_keyboard())
+        deliver(event)
+
+    def press(keyval, modifiers=()):
+        mask = Gdk.ModifierType(0)
+        for modifier in modifiers:
+            key_event(Gdk.EventType.KEY_PRESS, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
+            mask |= MODIFIER_MASKS[modifier]
+        key_event(Gdk.EventType.KEY_PRESS, keyval, mask)
+        key_event(Gdk.EventType.KEY_RELEASE, keyval, mask)
+        for modifier in reversed(modifiers):
+            key_event(Gdk.EventType.KEY_RELEASE, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
+            mask &= ~MODIFIER_MASKS[modifier]
+
+    def mouse(kind, x, y):
+        event = Gdk.Event.new(kind)
+        fields = event.motion if kind == Gdk.EventType.MOTION_NOTIFY else event.button
+        if kind != Gdk.EventType.MOTION_NOTIFY:
+            fields.button = 1
+        fields.window = view.get_window()
+        fields.send_event = 1
+        fields.x = x
+        fields.y = y
+        fields.time = Gtk.get_current_event_time()
+        event.set_device(seat.get_pointer())
+        view.event(event)
+
+    def full_pixbuf():
+        if args.headed:
+            return Gdk.pixbuf_get_from_window(
+                view.get_window(), 0, 0, view.get_allocated_width(), view.get_allocated_height()
+            )
+        return window.get_pixbuf()
+
+    def save(name, pixbuf):
+        path = os.path.join(args.out, f"{args.prefix}{name}.png")
+        pixbuf.savev(path, "png", [], [])
+        emit("saved", path)
+
+    def evaluate(code, on_value, on_error):
+        def on_result(webview, result):
+            try:
+                on_value(describe(webview.evaluate_javascript_finish(result)))
+            except Exception as error:
+                on_error(str(error))
+
+        view.evaluate_javascript(code, -1, None, None, None, on_result)
+
+    def with_rect(step, use):
+        selector = step.get("selector") or step["value"]
+
+        def on_value(text):
+            rect = json.loads(text) if text and text != "null" else None
+            if not rect:
+                step_failed(f"{step['kind']}:{step['value']} failed: no element matches {selector}")
+                return next_step()
+            if rect["width"] <= 0 or rect["height"] <= 0:
+                step_failed(f"{step['kind']}:{step['value']} failed: {selector} has no size (hidden?)")
+                return next_step()
+            use(rect)
+
+        evaluate(step["rect"], on_value, lambda error: (step_failed(f"{step['kind']}:{step['value']} failed: {error}"), next_step()))
+
+    def snap_element(step, rect):
+        pixbuf = full_pixbuf()
+        width, height = view.get_allocated_width(), view.get_allocated_height()
+        scale = pixbuf.get_width() / width
+        margin = args.snap_margin
+        left = max(0, int(rect["x"] - margin))
+        top = max(0, int(rect["y"] - margin))
+        right = min(width, int(rect["x"] + rect["width"] + margin + 0.999))
+        bottom = min(height, int(rect["y"] + rect["height"] + margin + 0.999))
+        if right <= left or bottom <= top:
+            step_failed(f"snap:{step['value']} failed: element is outside the window")
+            return next_step()
+        cropped = pixbuf.new_subpixbuf(
+            int(left * scale), int(top * scale), int((right - left) * scale), int((bottom - top) * scale)
+        ).copy()
+        save(step["value"], cropped)
+        next_step()
+
+    def point_at(step, rect):
+        x = rect["x"] + rect["width"] / 2
+        y = rect["y"] + rect["height"] / 2
+        mouse(Gdk.EventType.MOTION_NOTIFY, x, y)
+        if step["kind"] == "click":
+            mouse(Gdk.EventType.BUTTON_PRESS, x, y)
+            mouse(Gdk.EventType.BUTTON_RELEASE, x, y)
+        GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+
+    def wait_for(step, started):
+        def on_value(text):
+            if text == "true":
+                return next_step()
+            if (GLib.get_monotonic_time() - started) / 1000 >= args.wait_for_timeout_ms:
+                step_failed(f"waitfor:{step['value']} timed out after {args.wait_for_timeout_ms} ms")
+                return next_step()
+            GLib.timeout_add(args.wait_for_poll_ms, lambda: (wait_for(step, started), False)[1])
+
+        evaluate(step["check"], on_value, lambda error: (step_failed(f"waitfor:{step['value']} failed: {error}"), next_step()))
+
+    def next_step():
+        GLib.idle_add(run_step)
+
+    def run_step():
+        if state["index"] >= len(steps):
+            return finish()
+        step = steps[state["index"]]
+        state["index"] += 1
+        kind, value = step["kind"], step["value"]
+
+        if kind == "snap":
+            if step.get("selector"):
+                with_rect(step, lambda rect: snap_element(step, rect))
+            else:
+                save(value, full_pixbuf())
+                next_step()
+        elif kind in ("js", "jsnow"):
+            evaluate(value, lambda _: None, lambda error: emit("error", f"js failed: {error}"))
+            if kind == "js":
+                GLib.timeout_add(args.js_settle_ms, run_step)
+            else:
+                next_step()
+        elif kind == "wait":
+            GLib.timeout_add(int(value), run_step)
+        elif kind == "waitfor":
+            wait_for(step, GLib.get_monotonic_time())
+        elif kind == "resize":
+            width, height = (int(part) for part in value.split("x"))
+            window.set_size_request(width, height)
+            window.resize(width, height)
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        elif kind == "print":
+            evaluate(
+                value,
+                lambda text: (emit("print", text), next_step()),
+                lambda error: (emit("error", f"print failed: {error}"), next_step())
+            )
+        elif kind in ("hover", "click"):
+            with_rect(step, lambda rect: point_at(step, rect))
+        elif kind == "key":
+            press(keyval_for(step["key"]), step["modifiers"])
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        elif kind == "type":
+            for character in value:
+                press(Gdk.unicode_to_keyval(ord(character)))
+            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+        return False
+
+    def start_steps():
+        focus_window()
+        if not init_scripts:
+            return run_step()
+        evaluate(
+            args.init_errors,
+            lambda text: (emit("init-errors", text), next_step()),
+            lambda error: (emit("error", f"init check failed: {error}"), next_step())
+        )
+        return False
+
+    def on_load_changed(_view, event):
+        if event == WebKit2.LoadEvent.FINISHED and not state["started"]:
+            state["started"] = True
+            GLib.timeout_add(args.load_settle_ms, start_steps)
+
+    def on_load_failed(_view, _event, uri, error):
+        emit("error", f"failed to load {uri}: {error.message}")
+        return finish(failed=True)
+
+    def on_timeout():
+        emit("error", f"timed out after {args.timeout_ms} ms")
+        return finish(failed=True)
+
+    view.connect("load-changed", on_load_changed)
+    view.connect("load-failed", on_load_failed)
+    view.load_uri(args.url)
+    GLib.timeout_add(args.timeout_ms, on_timeout)
+    Gtk.main()
+
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(1 if state["failed"] else 0)
+
+
+if __name__ == "__main__":
+    main()

package/src/index.d.ts

@@ -0,0 +1,101 @@
+export type Engine = "auto" | "webkitgtk" | "msedge" | "chrome" | "chromium" | "webkit";
+
+export type Step =
+	| `js:${string}`
+	| `jsnow:${string}`
+	| `wait:${number}`
+	| `waitfor:${string}`
+	| `measure:${string}`
+	| `snap:${string}`
+	| `print:${string}`
+	| `resize:${number}x${number}`
+	| `key:${string}`
+	| `type:${string}`
+	| `hover:${string}`
+	| `click:${string}`
+	| `macro:${string}`;
+
+export interface ServerOptions {
+	command: string;
+	port: number;
+	host?: string;
+	cwd?: string;
+	readyTimeoutMs?: number;
+}
+
+export interface PreviewConfig {
+	baseUrl?: string;
+	server?: ServerOptions;
+	engine?: Engine;
+	size?: `${number}x${number}`;
+	out?: string;
+	prefix?: string;
+	scale?: number;
+	init?: InitEntry | InitEntry[];
+	mock?: Record<string, MockResponse>;
+	logRequests?: boolean;
+	headed?: boolean;
+	keepStorage?: boolean;
+	waitTimeout?: number;
+	snapMargin?: number;
+	compare?: boolean;
+	updateBaseline?: boolean;
+	baseline?: string;
+	maxDiffPixels?: number;
+	compareTolerance?: number;
+	tauri?: boolean | TauriStub;
+	globals?: Record<string, unknown>;
+	locale?: string;
+	macros?: Record<string, Step[] | string[]>;
+}
+
+export interface TauriStub {
+	commands?: Record<string, unknown | ((args: Record<string, unknown>) => unknown)>;
+	label?: string;
+}
+
+export interface AnyApi {
+	readonly members: Record<string, unknown>;
+}
+
+export interface MockResponse {
+	status?: number;
+	json?: unknown;
+	body?: string;
+	headers?: Record<string, string>;
+	delayMs?: number;
+}
+
+export type InitEntry = string | { file: string }
+
+export interface PreviewOptions extends PreviewConfig {
+	target?: string;
+	steps?: Step[] | string[];
+	initFile?: string | string[];
+	mockFile?: string | string[];
+	config?: string | false;
+	log?: { info: (message: string) => void; error: (message: string) => void }
+}
+
+export interface PreviewResult {
+	engine: Exclude<Engine, "auto">;
+	url: string;
+	saved: string[];
+	failed: boolean;
+}
+
+export declare const ENGINES: Engine[];
+export declare const REQUESTS_KEY: "__webviewPreviewRequests";
+export declare function resolveUrl(target: string, baseUrl?: string): string;
+export declare function preview(options?: PreviewOptions): Promise<PreviewResult>;
+export declare function defineConfig(config: PreviewConfig): PreviewConfig;
+export declare function anyApi(members?: Record<string, unknown>): AnyApi;
+export interface CleanOptions {
+	config?: string | false;
+	out?: string;
+	baseline?: string;
+	olderThan?: string;
+	dryRun?: boolean;
+}
+
+export declare function cleanSnapshots(options?: CleanOptions): Promise<{ removed: string[]; out: string }>;

package/src/index.mjs

@@ -0,0 +1,101 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import { compareSnapshots } from "#src/snapshots/compare.mjs";
+import { loadConfig } from "#src/core/config.mjs";
+import { resolveEngine, runEngine } from "#src/engines/index.mjs";
+import { checkLocale, globalsScript, localeScript } from "#src/page/globals.mjs";
+import { resolveInit, wrapInit } from "#src/page/init.mjs";
+import { compileMock, mockScript, resolveMockFiles } from "#src/page/mock.mjs";
+import { startServer } from "#src/core/server.mjs";
+import { expandMacros, parseSize, parseSteps } from "#src/core/steps.mjs";
+import { resolveTauri, tauriScript } from "#src/page/tauri.mjs";
+
+export { ENGINES } from "#src/engines/index.mjs";
+export { REQUESTS_KEY } from "#src/page/mock.mjs";
+export { cleanSnapshots } from "#src/snapshots/clean.mjs";
+export { anyApi } from "#src/page/source.mjs";
+
+const DEFAULTS = { engine: "auto", size: "1200x650", out: ".webview-preview", steps: ["snap:page"] }
+const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/i;
+
+const consoleLog = {
+	info: message => console.log(message),
+	error: message => console.error(message)
+}
+
+export const resolveUrl = (target, baseUrl) => {
+	if (ABSOLUTE_URL.test(target)) return target;
+	if (!baseUrl) throw new Error(`"${target}" is not a full URL; set baseUrl to open routes`);
+	return `${baseUrl}${target.startsWith("/") ? target : `/${target}`}`;
+}
+
+export const preview = async (options = {}) => {
+	const config = options.config === false ? {} : await loadConfig(options.config);
+	const merged = { ...DEFAULTS, ...config, ...Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined)) }
+	const baseDir = config.configDir ?? process.cwd();
+	const engine = resolveEngine(merged.engine);
+	const macros = { ...config.macros, ...options.macros }
+	const steps = parseSteps(expandMacros(merged.steps.length ? merged.steps : DEFAULTS.steps, macros));
+	const out = path.resolve(baseDir, merged.out);
+	const url = resolveUrl(merged.target ?? merged.url ?? "/", merged.baseUrl);
+	parseSize(merged.size);
+	const mockFiles = await resolveMockFiles(options.mockFile, process.cwd());
+	const hasMock = config.mock !== undefined || options.mock !== undefined || mockFiles.length > 0
+		|| !!(options.logRequests ?? config.logRequests);
+	const mockRules = compileMock([config.mock, ...mockFiles, options.mock]);
+	const locale = merged.locale === undefined ? undefined : checkLocale(String(merged.locale));
+	const tauri = resolveTauri(config.tauri, options.tauri);
+	const globals = { ...config.globals, ...options.globals }
+	const stubs = [
+		locale && { label: "locale", source: localeScript(locale) },
+		tauri && { label: "tauri", source: tauriScript(tauri) },
+		Object.keys(globals).length && { label: "globals", source: globalsScript(globals) }
+	].filter(Boolean).map(stub => {
+		try {
+			new Function(stub.source);
+		} catch (error) {
+			throw new Error(`${stub.label}: the generated script does not parse (${error.message}); check the functions in your config`);
+		}
+		return wrapInit(stub);
+	});
+	const init = stubs.concat(hasMock ? [mockScript(mockRules)] : [], resolveInit([
+		{ entries: config.init, baseDir },
+		{ entries: options.init, baseDir: process.cwd() },
+		{ entries: options.initFile && [].concat(options.initFile).map(file => ({ file })), baseDir: process.cwd() }
+	], baseDir));
+	mkdirSync(out, { recursive: true });
+
+	const server = merged.server && { cwd: baseDir, ...merged.server }
+	const stopServer = await startServer(server);
+	try {
+		const result = await runEngine(engine, {
+			url,
+			steps,
+			init,
+			size: merged.size,
+			locale,
+			out,
+			prefix: merged.prefix ?? `${engine}-`,
+			scale: merged.scale === undefined ? undefined : Number(merged.scale),
+			snapMargin: Number(merged.snapMargin ?? 8),
+			isHeaded: !!merged.headed,
+			isStorageKept: !!merged.keepStorage,
+			waitForTimeoutMs: Number(merged.waitTimeout ?? 10000),
+			log: merged.log ?? consoleLog
+		});
+		const shouldCompare = !!(merged.compare || merged.updateBaseline);
+		const compareFailed = shouldCompare && compareSnapshots({
+			saved: result.saved,
+			baselineDir: path.resolve(baseDir, merged.baseline ?? "webview-preview-baseline"),
+			updateBaseline: !!merged.updateBaseline,
+			tolerance: Number(merged.compareTolerance ?? 2),
+			maxDiffPixels: Number(merged.maxDiffPixels ?? 0),
+			log: merged.log ?? consoleLog
+		});
+		return { engine, url, ...result, failed: result.failed || compareFailed }
+	} finally {
+		stopServer();
+	}
+}
+
+export const defineConfig = config => config;

package/src/page/globals.mjs

@@ -0,0 +1,37 @@
+import { ANY_FUNCTION, toSource } from "#src/page/source.mjs";
+
+const GLOBAL_PATH = /^(window\.)?[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+const LOCALE = /^[a-z]{2,3}(-[A-Za-z\d]{2,8})*$/i;
+
+export const globalsScript = globals => {
+	const entries = Object.entries(globals).map(([path, value]) => {
+		if (!GLOBAL_PATH.test(path)) throw new Error(`globals: "${path}" must be a dotted path like window.api or window.go.main`);
+		const name = path.startsWith("window.") ? path : `window.${path}`;
+		return `assign(${JSON.stringify(name)}, ${toSource(value, name)});`;
+	});
+	return `(() => {
+	const __webviewPreviewAny = ${ANY_FUNCTION};
+	const assign = (path, value) => {
+		const parts = path.split(".").slice(1);
+		const last = parts.pop();
+		let target = window;
+		for (const part of parts) {
+			if (target[part] === undefined || target[part] === null) target[part] = {};
+			target = target[part];
+		}
+		target[last] = value;
+	}
+	${entries.join("\n\t")}
+})();`;
+}
+
+export const checkLocale = locale => {
+	if (!LOCALE.test(locale)) throw new Error(`locale must look like en-US or ru, got "${locale}"`);
+	return locale;
+}
+
+export const localeScript = locale => `(() => {
+	const language = ${JSON.stringify(checkLocale(locale))};
+	Object.defineProperty(Navigator.prototype, "language", { get: () => language, configurable: true });
+	Object.defineProperty(Navigator.prototype, "languages", { get: () => [language], configurable: true });
+})();`;

package/src/page/init.mjs

@@ -0,0 +1,32 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+const ERRORS_KEY = "__webviewPreviewInitErrors";
+export const INIT_ERRORS_EXPRESSION = `JSON.stringify(window.${ERRORS_KEY} || [])`;
+const toList = value => value === undefined || value === null ? [] : Array.isArray(value) ? value : [value];
+
+const readEntry = (entry, baseDir, index) => {
+	if (typeof entry === "string") return { label: `init[${index}]`, source: entry }
+	if (entry && typeof entry.file === "string") {
+		const file = path.resolve(baseDir, entry.file);
+		if (!existsSync(file)) throw new Error(`init file not found: ${file}`);
+		return { label: path.basename(file), source: readFileSync(file, "utf8") }
+	}
+	throw new Error(`init entries must be code strings or { file: "path" }, got ${JSON.stringify(entry)}`);
+}
+
+export const wrapInit = ({ label, source }) => `{
+	try {
+		${source}
+	} catch (error) {
+		(window.${ERRORS_KEY} = window.${ERRORS_KEY} || []).push(${JSON.stringify(label)} + ": " + (error && error.message || error));
+	}
+}`;
+
+export const resolveInit = (groups, baseDir) => groups
+	.flatMap(group => toList(group.entries).map(entry => ({ entry, baseDir: group.baseDir })))
+	.map(({ entry, baseDir: dir }, index) => wrapInit(readEntry(entry, dir ?? baseDir, index)));
+
+export const reportInitErrors = (json, log) => {
+	for (const message of JSON.parse(json || "[]")) log.error(`init failed: ${message}`);
+}