webview-preview 1.0.0 → 1.1.1

package/src/engines/playwright.mjs

@@ -16,15 +16,26 @@ const loadPlaywright = async () => {
 	}
 }
 
-export const runPlaywright = async ({ engine, url, steps, init = [], size, locale, out, prefix, scale, snapMargin = 8, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, log }) => {
+export const runPlaywright = async ({
+	engine, url, steps, init = [], size, locale,
+	colorScheme, isMotionReduced = false, out, prefix, scale,
+	snapMargin = 8, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, log
+}) => {
 	const playwright = await loadPlaywright();
 	const browserType = engine === "webkit" ? playwright.webkit : playwright.chromium;
 	const browser = await browserType.launch({ channel: CHANNELS[engine], headless: true });
 	const saved = [];
+	const films = [];
 	let failed = false;
 
 	try {
-		const page = await browser.newPage({ viewport: parseSize(size), deviceScaleFactor: scale ?? 1, locale });
+		const page = await browser.newPage({
+			viewport: parseSize(size),
+			deviceScaleFactor: scale ?? 1,
+			locale,
+			colorScheme,
+			reducedMotion: isMotionReduced ? "reduce" : undefined
+		});
 		page.setDefaultTimeout(TIMEOUT_MS);
 		for (const content of init) await page.addInitScript({ content });
 		await page.goto(url, { waitUntil: "load" });
@@ -45,6 +56,20 @@ export const runPlaywright = async ({ engine, url, steps, init = [], size, local
 			return parseRect(result.value, step.selector ?? step.value);
 		}
 
+		const film = async step => {
+			const frames = [];
+			const started = Date.now();
+			for (let index = 0; index < step.frames; index += 1) {
+				const due = started + index * step.durationMs / (step.frames - 1);
+				if (Date.now() < due) await page.waitForTimeout(due - Date.now());
+				const time = Date.now() - started;
+				const file = path.join(out, `${prefix}${step.value}.frame-${index}.png`);
+				const [, rect] = await Promise.all([page.screenshot({ path: file }), step.rect ? evaluate(step.rect) : {}]);
+				frames.push({ file, time, rect: rect.value && rect.value !== "null" ? JSON.parse(rect.value) : null });
+			}
+			films.push({ name: step.value, file: path.join(out, `${prefix}${step.value}.png`), scale: scale ?? 1, viewport: page.viewportSize(), frames });
+		}
+
 		const runStep = async step => {
 			const { kind, value } = step;
 			if (kind === "snap") {
@@ -52,6 +77,8 @@ export const runPlaywright = async ({ engine, url, steps, init = [], size, local
 				const clip = step.selector ? clipRect(await elementRect(step), snapMargin, page.viewportSize()) : undefined;
 				await page.screenshot({ path: file, clip });
 				saved.push(file);
+			} else if (kind === "film") {
+				await film(step);
 			} else if (kind === "hover" || kind === "click") {
 				const rect = await elementRect(step);
 				const x = rect.x + rect.width / 2;
@@ -100,5 +127,5 @@ export const runPlaywright = async ({ engine, url, steps, init = [], size, local
 		await browser.close();
 	}
 
-	return { saved, failed }
+	return { saved, failed, films }
 }

package/src/engines/webkitgtk.mjs

@@ -9,7 +9,12 @@ const PROBE = "import gi; gi.require_version('Gtk', '3.0'); gi.require_version('
 export const isWebkitGtkAvailable = () => process.platform === "linux"
 	&& spawnSync("python3", ["-c", PROBE], { stdio: "ignore" }).status === 0;
 
-export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMargin = 8, isHeaded = false, isStorageKept = false, waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, log }) => new Promise((resolve, reject) => {
+export const runWebkitGtk = ({
+	url, steps, init = [], size, colorScheme,
+	isMotionReduced = false, out, prefix, snapMargin = 8,
+	isHeaded = false, isStorageKept = false,
+	waitForTimeoutMs = WAIT_FOR_TIMEOUT_MS, timeoutMs = TIMEOUT_MS, log
+}) => new Promise((resolve, reject) => {
 	if (!isWebkitGtkAvailable()) {
 		reject(new Error("WebKitGTK engine needs Linux with python3-gi and WebKit2 4.1 (gir1.2-webkit2-4.1)"));
 		return;
@@ -18,14 +23,14 @@ export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMar
 	const { width, height } = parseSize(size);
 	const child = spawn("python3", [
 		SCRIPT, url,
-		"--steps", JSON.stringify(steps),
-		"--init", JSON.stringify(init),
 		"--init-errors", INIT_ERRORS_EXPRESSION,
 		"--out", out,
 		"--prefix", prefix,
 		"--width", String(width),
 		"--height", String(height),
 		"--snap-margin", String(snapMargin),
+		...(colorScheme ? ["--color-scheme", colorScheme] : []),
+		...(isMotionReduced ? ["--reduced-motion"] : []),
 		...(isHeaded ? ["--headed"] : []),
 		...(isStorageKept ? ["--keep-storage"] : []),
 		"--wait-for-timeout-ms", String(waitForTimeoutMs),
@@ -34,11 +39,15 @@ export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMar
 		"--js-settle-ms", String(JS_SETTLE_MS),
 		"--timeout-ms", String(timeoutMs)
 	], {
-		stdio: ["ignore", "pipe", "pipe"],
+		stdio: ["pipe", "pipe", "pipe"],
 		env: { PYTHONUNBUFFERED: "1", ...process.env }
 	});
 
+	child.stdin.on("error", () => undefined);
+	child.stdin.end(JSON.stringify({ steps, init }));
+
 	const saved = [];
+	const films = [];
 	let buffer = "";
 	child.stdout.setEncoding("utf8");
 	child.stdout.on("data", chunk => {
@@ -51,6 +60,7 @@ export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMar
 			const kind = line.slice(0, tab);
 			const value = JSON.parse(line.slice(tab + 1));
 			if (kind === "saved") saved.push(value);
+			else if (kind === "film") films.push(value);
 			else if (kind === "print") log.info(value);
 			else if (kind === "error") log.error(value);
 			else if (kind === "init-errors") reportInitErrors(value, log);
@@ -63,5 +73,5 @@ export const runWebkitGtk = ({ url, steps, init = [], size, out, prefix, snapMar
 		}
 	});
 	child.once("error", reject);
-	child.once("exit", code => resolve({ saved, failed: code !== 0 }));
+	child.once("exit", code => resolve({ saved, failed: code !== 0, films }));
 });

package/src/engines/webkitgtk.py

@@ -14,6 +14,11 @@ gi.require_version("WebKit2", "4.1")
 from gi.repository import Gdk, GLib, Gtk, WebKit2
 
 INPUT_SETTLE_MS = 50
+UNSUPPORTED_RESULT = "Unsupported result type"
+KEY_POLL_MS = 20
+KEY_WAIT_MS = 2000
+KEYUPS = "window.__webviewPreviewKeyups || 0"
+KEYUP_COUNTER = "addEventListener('keyup', () => { window.__webviewPreviewKeyups = (window.__webviewPreviewKeyups || 0) + 1 }, true);"
 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",
@@ -37,14 +42,14 @@ def emit(kind, value):
 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("--color-scheme", choices=("light", "dark"))
+    parser.add_argument("--reduced-motion", action="store_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)
@@ -69,17 +74,28 @@ def keyval_for(key):
     return Gdk.unicode_to_keyval(ord(key))
 
 
+def apply_media(args):
+    settings = Gtk.Settings.get_default()
+    if args.color_scheme:
+        settings.set_property("gtk-theme-name", "Adwaita")
+        settings.set_property("gtk-application-prefer-dark-theme", args.color_scheme == "dark")
+    if args.reduced_motion:
+        settings.set_property("gtk-enable-animations", False)
+
+
 def main():
     args = parse_args()
-    steps = json.loads(args.steps)
-    init_scripts = json.loads(args.init)
+    apply_media(args)
+    payload = json.loads(sys.stdin.read())
+    steps = payload["steps"]
+    init_scripts = payload["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:
+    for source in [KEYUP_COUNTER, *init_scripts]:
         manager.add_script(WebKit2.UserScript.new(
             source,
             WebKit2.UserContentInjectedFrames.TOP_FRAME,
@@ -117,7 +133,9 @@ def main():
         event.focus_change.send_event = 1
         event.focus_change.in_ = 1
         event.set_device(seat.get_keyboard())
+        display.error_trap_push()
         deliver(event)
+        display.error_trap_pop_ignored()
         view.grab_focus()
 
     def key_event(kind, keyval, mask):
@@ -144,6 +162,29 @@ def main():
             key_event(Gdk.EventType.KEY_RELEASE, Gdk.keyval_from_name(MODIFIER_KEYS[modifier]), mask)
             mask &= ~MODIFIER_MASKS[modifier]
 
+    def press_all(presses):
+        def count(text):
+            return int(text) if text and text.isdigit() else 0
+
+        def send(text):
+            expected = count(text) + sum(1 + len(modifiers) for _, modifiers in presses)
+            for keyval, modifiers in presses:
+                press(keyval, modifiers)
+            started = GLib.get_monotonic_time()
+
+            def check():
+                def on_value(text):
+                    if count(text) >= expected or (GLib.get_monotonic_time() - started) / 1000 >= KEY_WAIT_MS:
+                        GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+                    else:
+                        GLib.timeout_add(KEY_POLL_MS, lambda: (check(), False)[1])
+
+                evaluate(KEYUPS, on_value, lambda _: GLib.timeout_add(INPUT_SETTLE_MS, run_step))
+
+            check()
+
+        evaluate(KEYUPS, send, lambda _: send("0"))
+
     def mouse(kind, x, y):
         event = Gdk.Event.new(kind)
         fields = event.motion if kind == Gdk.EventType.MOTION_NOTIFY else event.button
@@ -231,6 +272,44 @@ def main():
 
         evaluate(step["check"], on_value, lambda error: (step_failed(f"waitfor:{step['value']} failed: {error}"), next_step()))
 
+    def film(step):
+        frames = []
+        started = GLib.get_monotonic_time() / 1000
+        interval = step["durationMs"] / (step["frames"] - 1)
+
+        def store_rect(frame, text):
+            frame["rect"] = json.loads(text) if text and text != "null" else None
+
+        def finish_film():
+            width, height = view.get_allocated_width(), view.get_allocated_height()
+            for index, frame in enumerate(frames):
+                path = os.path.join(args.out, f"{args.prefix}{step['value']}.frame-{index}.png")
+                frame.pop("pixbuf").savev(path, "png", [], [])
+                frame["file"] = path
+            emit("film", {
+                "name": step["value"],
+                "file": os.path.join(args.out, f"{args.prefix}{step['value']}.png"),
+                "scale": full_pixbuf().get_width() / width,
+                "viewport": {"width": width, "height": height},
+                "frames": frames
+            })
+            next_step()
+
+        def capture():
+            now = GLib.get_monotonic_time() / 1000
+            frame = {"pixbuf": full_pixbuf(), "time": round(now - started), "rect": None}
+            frames.append(frame)
+            if step.get("rect"):
+                evaluate(step["rect"], lambda text: store_rect(frame, text), lambda _: None)
+            if len(frames) < step["frames"]:
+                due = started + len(frames) * interval
+                GLib.timeout_add(max(0, int(due - GLib.get_monotonic_time() / 1000)), capture)
+            else:
+                evaluate("0", lambda _: finish_film(), lambda _: finish_film())
+            return False
+
+        capture()
+
     def next_step():
         GLib.idle_add(run_step)
 
@@ -247,8 +326,10 @@ def main():
             else:
                 save(value, full_pixbuf())
                 next_step()
+        elif kind == "film":
+            film(step)
         elif kind in ("js", "jsnow"):
-            evaluate(value, lambda _: None, lambda error: emit("error", f"js failed: {error}"))
+            evaluate(value, lambda _: None, lambda error: None if UNSUPPORTED_RESULT in error else emit("error", f"js failed: {error}"))
             if kind == "js":
                 GLib.timeout_add(args.js_settle_ms, run_step)
             else:
@@ -259,9 +340,21 @@ def main():
             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.set_size_request(-1, -1)
+            window.set_default_size(width, height)
             window.resize(width, height)
-            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+            started = GLib.get_monotonic_time()
+
+            def check_size():
+                def on_value(text):
+                    if text == f"{width}x{height}" or (GLib.get_monotonic_time() - started) / 1000 >= KEY_WAIT_MS:
+                        GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+                    else:
+                        GLib.timeout_add(KEY_POLL_MS, lambda: (check_size(), False)[1])
+
+                evaluate("innerWidth + 'x' + innerHeight", on_value, lambda _: GLib.timeout_add(INPUT_SETTLE_MS, run_step))
+
+            check_size()
         elif kind == "print":
             evaluate(
                 value,
@@ -271,12 +364,9 @@ def main():
         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)
+            press_all([(keyval_for(step["key"]), step["modifiers"])])
         elif kind == "type":
-            for character in value:
-                press(Gdk.unicode_to_keyval(ord(character)))
-            GLib.timeout_add(INPUT_SETTLE_MS, run_step)
+            press_all([(Gdk.unicode_to_keyval(ord(character)), ()) for character in value])
         return False
 
     def start_steps():

package/src/index.d.ts

@@ -6,6 +6,16 @@ export type Step =
 	| `wait:${number}`
 	| `waitfor:${string}`
 	| `measure:${string}`
+	| `assert:${string}`
+	| "focusorder"
+	| `focusorder:${number}`
+	| `film:${string}:${number}`
+	| `film:${string}:${number}/${number}`
+	| `film:${string}:${number}@${string}`
+	| `film:${string}:${number}/${number}@${string}`
+	| "offline"
+	| "online"
+	| `latency:${number}`
 	| `snap:${string}`
 	| `print:${string}`
 	| `resize:${number}x${number}`
@@ -27,7 +37,13 @@ export interface PreviewConfig {
 	baseUrl?: string;
 	server?: ServerOptions;
 	engine?: Engine;
-	size?: `${number}x${number}`;
+	size?: Size | Size[] | string;
+	colorScheme?: "light" | "dark";
+	reducedMotion?: boolean;
+	offline?: boolean;
+	latency?: number;
+	watch?: string | string[];
+	report?: boolean;
 	out?: string;
 	prefix?: string;
 	scale?: number;
@@ -47,8 +63,11 @@ export interface PreviewConfig {
 	globals?: Record<string, unknown>;
 	locale?: string;
 	macros?: Record<string, Step[] | string[]>;
+	failOnError?: boolean;
 }
 
+export type Size = `${number}x${number}`;
+
 export interface TauriStub {
 	commands?: Record<string, unknown | ((args: Record<string, unknown>) => unknown)>;
 	label?: string;
@@ -80,7 +99,11 @@ export interface PreviewOptions extends PreviewConfig {
 export interface PreviewResult {
 	engine: Exclude<Engine, "auto">;
 	url: string;
+	sizes: string[];
 	saved: string[];
+	consoleErrors: number;
+	failedAsserts: number;
+	report?: string;
 	failed: boolean;
 }
 
@@ -88,6 +111,7 @@ 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 watchPreview(options?: PreviewOptions, onRun?: (result: PreviewResult) => void): Promise<() => void>;
 export declare function defineConfig(config: PreviewConfig): PreviewConfig;
 export declare function anyApi(members?: Record<string, unknown>): AnyApi;
 export interface CleanOptions {

package/src/index.mjs

@@ -1,13 +1,18 @@
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import path from "node:path";
 import { compareSnapshots } from "#src/snapshots/compare.mjs";
+import { stitchFilm } from "#src/snapshots/film.mjs";
+import { writeReport } from "#src/snapshots/report.mjs";
 import { loadConfig } from "#src/core/config.mjs";
 import { resolveEngine, runEngine } from "#src/engines/index.mjs";
+import { consoleScript, consoleStep, watchOutput } from "#src/page/console.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 { watchFiles } from "#src/core/watch.mjs";
 import { expandMacros, parseSize, parseSteps } from "#src/core/steps.mjs";
+import { checkLatency, networkScript } from "#src/page/network.mjs";
 import { resolveTauri, tauriScript } from "#src/page/tauri.mjs";
 
 export { ENGINES } from "#src/engines/index.mjs";
@@ -26,7 +31,23 @@ const consoleLog = {
 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}`}`;
+	const route = target.startsWith("/") ? target : `/${target}`;
+	return baseUrl.endsWith("/") ? `${baseUrl}${route.slice(1)}` : `${baseUrl}${route}`;
+}
+
+const COLOR_SCHEMES = ["light", "dark"];
+
+const parseSizes = value => {
+	const sizes = [].concat(value).flatMap(item => String(item).split(",")).map(item => item.trim()).filter(Boolean);
+	if (!sizes.length) throw new Error("size needs at least one WxH");
+	for (const size of sizes) parseSize(size);
+	return sizes;
+}
+
+const checkColorScheme = value => {
+	if (value === undefined) return undefined;
+	if (!COLOR_SCHEMES.includes(value)) throw new Error(`colorScheme must be ${COLOR_SCHEMES.join(" or ")}, got "${value}"`);
+	return value;
 }
 
 export const preview = async (options = {}) => {
@@ -38,7 +59,9 @@ export const preview = async (options = {}) => {
 	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 sizes = parseSizes(merged.size);
+	const snapMargin = Number(merged.snapMargin ?? 8);
+	const colorScheme = checkColorScheme(merged.colorScheme);
 	const mockFiles = await resolveMockFiles(options.mockFile, process.cwd());
 	const hasMock = config.mock !== undefined || options.mock !== undefined || mockFiles.length > 0
 		|| !!(options.logRequests ?? config.logRequests);
@@ -46,11 +69,8 @@ export const preview = async (options = {}) => {
 	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 => {
+	const network = { isOffline: !!merged.offline, latencyMs: checkLatency(merged.latency) }
+	const checked = stubs => stubs.filter(Boolean).map(stub => {
 		try {
 			new Function(stub.source);
 		} catch (error) {
@@ -58,44 +78,149 @@ export const preview = async (options = {}) => {
 		}
 		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));
+	const init = [
+		...checked([
+			{ label: "console", source: consoleScript() },
+			locale && { label: "locale", source: localeScript(locale) },
+			tauri && { label: "tauri", source: tauriScript(tauri) },
+			Object.keys(globals).length && { label: "globals", source: globalsScript(globals) }
+		]),
+		...checked([hasMock && { label: "mock", source: mockScript(mockRules) }]),
+		...checked([{ label: "network", source: networkScript(network) }]),
+		...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 baseLog = merged.log ?? consoleLog;
+	const lines = [];
+	const log = {
+		info: message => {
+			lines.push(["info", message]);
+			baseLog.info(message);
+		},
+		error: message => {
+			lines.push(["error", message]);
+			baseLog.error(message);
+		}
+	}
+	const output = watchOutput(log);
 	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 prefix = merged.prefix ?? `${engine}-`;
+		const result = { saved: [], failed: false }
+		for (const size of sizes) {
+			if (sizes.length > 1) output.log.info(`size ${size}`);
+			const run = await runEngine(engine, {
+				url,
+				steps: [...steps, consoleStep],
+				init,
+				size,
+				locale,
+				colorScheme,
+				isMotionReduced: !!merged.reducedMotion,
+				out,
+				prefix: sizes.length > 1 ? `${prefix}${size}-` : prefix,
+				scale: merged.scale === undefined ? undefined : Number(merged.scale),
+				snapMargin,
+				isHeaded: !!merged.headed,
+				isStorageKept: !!merged.keepStorage,
+				waitForTimeoutMs: Number(merged.waitTimeout ?? 10000),
+				log: output.log
+			});
+			result.saved.push(...run.saved);
+			for (const film of run.films ?? []) {
+				try {
+					output.log.info(stitchFilm(film, snapMargin));
+					result.saved.push(film.file);
+				} catch (error) {
+					output.log.error(`film:${film.name} failed: ${error.message}`);
+					result.failed = true;
+				}
+			}
+			result.failed ||= run.failed;
+		}
+		
+		const { consoleErrors, failedAsserts } = output.report();
 		const shouldCompare = !!(merged.compare || merged.updateBaseline);
-		const compareFailed = shouldCompare && compareSnapshots({
+		const compared = 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 }
+			log
+		}) : { failed: false, results: [] }
+		const consoleFailed = !!merged.failOnError && consoleErrors > 0;
+		const failed = result.failed || compared.failed || consoleFailed || failedAsserts > 0;
+		const report = merged.report
+			? writeReport({ out, url, engine, sizes, lines, saved: result.saved, compared: compared.results, failed })
+			: undefined;
+		if (report) baseLog.info(`report → ${report}`);
+		return { engine, url, sizes, ...result, consoleErrors, failedAsserts, report, failed }
 	} finally {
 		stopServer();
 	}
 }
 
+export const watchPreview = async (options = {}, onRun = () => {}) => {
+	const config = options.config === false ? {} : await loadConfig(options.config);
+	const baseDir = config.configDir ?? process.cwd();
+	const log = options.log ?? consoleLog;
+	const entries = [].concat(options.watch ?? config.watch ?? (existsSync(path.join(baseDir, "src")) ? "src" : "."));
+	const folders = entries.map(entry => path.resolve(baseDir, entry));
+	const isConfigWatched = !config.configFile || folders.some(folder => config.configFile === folder || config.configFile.startsWith(folder + path.sep));
+	const targets = isConfigWatched ? folders : [...folders, config.configFile];
+	const ignore = [
+		path.resolve(baseDir, options.out ?? config.out ?? DEFAULTS.out),
+		path.resolve(baseDir, options.baseline ?? config.baseline ?? "webview-preview-baseline")
+	];
+	const server = options.server ?? config.server;
+	const stopServer = await startServer(server && { cwd: baseDir, ...server });
+	let isRunning = false;
+	let next = null;
+
+	const run = async reason => {
+		if (isRunning) {
+			next = reason;
+			return;
+		}
+		isRunning = true;
+		log.info(reason);
+		try {
+			onRun(await preview(options));
+		} catch (error) {
+			log.error(`webview-preview: ${error.message}`);
+		}
+		isRunning = false;
+		if (next) {
+			const queued = next;
+			next = null;
+			await run(queued);
+		}
+	}
+
+	let stopWatching;
+	try {
+		stopWatching = watchFiles({
+			targets,
+			ignore,
+			onChange: file => run(`\nchanged ${path.relative(baseDir, file) || file}, running again`)
+		});
+	} catch (error) {
+		stopServer();
+		throw error;
+	}
+	
+	await run(`watching ${targets.map(target => path.relative(baseDir, target) || ".").join(", ")}; Ctrl+C to stop`);
+	return () => {
+		stopWatching();
+		stopServer();
+	}
+}
+
 export const defineConfig = config => config;