plum-e2e 2.9.0 → 2.9.2

package/README.md

@@ -79,25 +79,33 @@ Full documentation is available at:
 
 ## Command Reference
 
-| Command                       | Description                                                        |
-| ----------------------------- | ------------------------------------------------------------------ |
-| `plum init`                   | Initialize a new project in the current folder                     |
-| `plum server start`           | Start the full UI stack via Docker                                 |
-| `plum server restart`         | Rebuild Docker images and restart the server without prompts       |
-| `plum server stop`            | Stop the server (data preserved)                                   |
-| `plum server reconfig`        | Re-enter server settings without starting                          |
-| `plum update`                 | Update Plum and auto-restart whatever is running (server or node)  |
-| `plum node start`             | Set up connectivity, start a runner node, and open the runner menu |
-| `plum node restart`           | Stop, refresh dependencies, and restart the runner node            |
-| `plum node stop`              | Stop the runner node started from this folder                      |
-| `plum node reconfig`          | Re-enter node settings and re-register                             |
-| `plum run-test`               | Run all tests locally without Docker                               |
-| `plum run-test @tag`          | Run tests matching a tag                                           |
-| `plum run-test --parallel N`  | Run tests across N parallel workers                                |
-| `plum run-test --browser <b>` | Run in `chromium` (default) or `firefox`                           |
-| `plum run-test --help`        | Show usage for `run-test`                                          |
-| `plum create-step`            | Interactively scaffold a new step definition                       |
-| `plum manage-runners`         | Open the interactive runner management menu                        |
+| Command                       | Description                                                                                                                                                |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plum init`                   | Initialize a new project in the current folder                                                                                                             |
+| `plum server start`           | Start the full UI stack via Docker                                                                                                                         |
+| `plum server restart`         | Rebuild Docker images and restart the server without prompts                                                                                               |
+| `plum server stop`            | Stop the server (data preserved)                                                                                                                           |
+| `plum server reconfig`        | Re-enter server settings without starting                                                                                                                  |
+| `plum update`                 | Update Plum, then restart each registered server/node on this machine (asks before each, in an interactive shell)                                          |
+| `plum sync-scaffold`          | Check `tests/utils/browser.ts`/`hooks.ts` against Plum's recommended starter pattern; reports what's stale but changes nothing (rarely needed — see below) |
+| `plum sync-scaffold --force`  | Overwrite files reported stale by the above (previous version backed up first)                                                                             |
+| `plum node start`             | Set up connectivity, start a runner node, and open the runner menu                                                                                         |
+| `plum node restart`           | Stop, refresh dependencies, and restart the runner node                                                                                                    |
+| `plum node stop`              | Stop the runner node started from this folder                                                                                                              |
+| `plum node reconfig`          | Re-enter node settings and re-register                                                                                                                     |
+| `plum run-test`               | Run all tests locally without Docker                                                                                                                       |
+| `plum run-test @tag`          | Run tests matching a tag                                                                                                                                   |
+| `plum run-test --parallel N`  | Run tests across N parallel workers                                                                                                                        |
+| `plum run-test --browser <b>` | Run in `chromium` (default) or `firefox`                                                                                                                   |
+| `plum run-test --help`        | Show usage for `run-test`                                                                                                                                  |
+| `plum create-step`            | Interactively scaffold a new step definition                                                                                                               |
+| `plum manage-runners`         | Open the interactive runner management menu                                                                                                                |
+
+---
+
+## `tests/utils/plum-modules/`
+
+`tests/utils/browser.ts` and `hooks.ts` are yours — customize them freely, they're never touched automatically. They import Plum's session recording from `tests/utils/plum-modules/`, which is regenerated from the installed Plum version before every run (`plum run-test`, `plum node start`, and every run triggered from the web UI), so recording fixes and features reach existing projects without any update step. Don't edit anything inside `plum-modules/` — it's overwritten on the next run.
 
 ---
 

package/backend/_scaffold/utils/browser.ts

@@ -15,222 +15,11 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-// Wires up Plum's session recording — removing or reordering code here can silently break report replay.
+import type { Page, BrowserContext, Browser } from 'playwright';
+import * as plum from './plum-modules/runtime';
 
-import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as zlib from 'zlib';
+export const page = (): Page => plum.page();
+export const context = (): BrowserContext => plum.context();
+export const browser = (): Browser => plum.browser();
 
-// Must match the mime type Plum's server expects — do not change.
-const RRWEB_MIME_TYPE = 'application/x-plum-rrweb+json';
-// Always attached, even for a scenario with no recorded events, so the
-// worker that ran it is still recoverable for grouping.
-const WORKER_META_MIME_TYPE = 'application/x-plum-worker+json';
-// @rrweb/record's package.json only exports its main entry ("."), so a deep
-// require.resolve() of the UMD bundle is blocked by Node's exports map — resolve
-// the (exported) main entry instead and locate the sibling file on disk.
-const RECORD_BUNDLE_PATH = path.join(
-	path.dirname(require.resolve('@rrweb/record')),
-	'record.umd.min.cjs'
-);
-
-interface TabRecording {
-	tabId: string;
-	tabIndex: number;
-	events: unknown[];
-	openedAt: number;
-	closedAt: number | null;
-	liveFlushedCount: number;
-}
-
-let _browser: Browser;
-let _context: BrowserContext;
-let _page: Page;
-let _liveRRwebCounter = 0;
-let _liveRRwebTimer: ReturnType<typeof setInterval> | null = null;
-let _tabs: Map<Page, TabRecording> = new Map();
-let _tabCounter = 0;
-let _workerId = 1;
-
-export const page = (): Page => _page;
-export const context = (): BrowserContext => _context;
-
-function tabIdForIndex(index: number): string {
-	return index === 0 ? 'main' : `tab-${index + 1}`;
-}
-
-// A static page (nothing left to interact with) can go a long time between
-// rrweb events, or emit none at all after its initial load — its own event
-// timestamps are a poor proxy for how long it stayed relevant. Real
-// open/close times let the replay UI line multiple tabs up on one timeline
-// without guessing from event gaps.
-function attachRecorder(pg: Page): void {
-	const tabIndex = _tabCounter++;
-	const recording: TabRecording = {
-		tabId: tabIdForIndex(tabIndex),
-		tabIndex,
-		events: [],
-		openedAt: Date.now(),
-		closedAt: null,
-		liveFlushedCount: 0
-	};
-	_tabs.set(pg, recording);
-	pg.on('close', () => {
-		recording.closedAt = Date.now();
-	});
-}
-
-export async function setup(): Promise<void> {
-	const isHeadless = process.env.IS_HEADLESS?.toLowerCase() !== 'false';
-	const browserName = (process.env.BROWSER || 'chromium').toLowerCase();
-	const browserType =
-		browserName === 'firefox' ? firefox : browserName === 'webkit' ? webkit : chromium;
-	_browser = await browserType.launch({ headless: isHeadless });
-	_context = await _browser.newContext();
-
-	_tabs = new Map();
-	_tabCounter = 0;
-	// Cucumber forks one OS process per --parallel worker and injects this env
-	// var into each — 0-indexed, so display/report as 1-based like the rest of
-	// the worker-count UI.
-	const parsedWorkerId = parseInt(process.env.CUCUMBER_WORKER_ID ?? '', 10);
-	_workerId = Number.isFinite(parsedWorkerId) ? parsedWorkerId + 1 : 1;
-
-	// Context-level exposeBinding/addInitScript apply to every page in the
-	// context automatically — current and future (popups, target=_blank tabs) —
-	// so recording setup never races a new tab's first navigation.
-	await _context.exposeBinding('__plumEmitRRwebEvent', (source, eventJson: string) => {
-		const recording = source.page && _tabs.get(source.page);
-		if (!recording) return;
-		try {
-			recording.events.push(JSON.parse(eventJson));
-		} catch {
-			// malformed event — drop it, recording is best-effort
-		}
-	});
-	await _context.addInitScript({ path: RECORD_BUNDLE_PATH });
-	await _context.addInitScript(() => {
-		// addInitScript runs in every frame, including hidden ad/tracking iframes.
-		// Recordings are tracked per-Page, so an unguarded sub-frame session would
-		// corrupt the tab's event stream with bogus 0x0 "about:blank" entries.
-		// @ts-ignore
-		if (window.self !== window.top) return;
-		// @ts-ignore
-		if (window.rrwebRecord) {
-			// @ts-ignore
-			window.rrwebRecord.record({
-				emit: (event: unknown) => {
-					// @ts-ignore — exposed by BrowserContext.exposeBinding above
-					window.__plumEmitRRwebEvent(JSON.stringify(event));
-				}
-			});
-		}
-	});
-
-	_context.on('page', attachRecorder);
-	_page = await _context.newPage();
-
-	// Only when someone's actually watching live — a scheduled/background run
-	// with no viewer shouldn't pay for this.
-	if (process.env.PLUM_SS_DIR) {
-		_liveRRwebTimer = setInterval(flushLiveRRwebEvents, 500);
-	}
-}
-
-// Sends only what's newly arrived since the last tick, per tab, so the live
-// viewer gets a steady trickle instead of the full buffer growing unbounded.
-function flushLiveRRwebEvents(): void {
-	const ssDir = process.env.PLUM_SS_DIR;
-	if (!ssDir) return;
-	for (const recording of _tabs.values()) {
-		const newEvents = recording.events.slice(recording.liveFlushedCount);
-		if (newEvents.length === 0) continue;
-		recording.liveFlushedCount = recording.events.length;
-		try {
-			const seq = `${String(Date.now()).padStart(16, '0')}-${String(++_liveRRwebCounter).padStart(4, '0')}`;
-			fs.writeFileSync(
-				path.join(ssDir, `${seq}.rrweb.json`),
-				JSON.stringify({
-					workerId: _workerId,
-					tabId: recording.tabId,
-					tabIndex: recording.tabIndex,
-					events: newEvents
-				})
-			);
-		} catch {
-			// best-effort — live streaming shouldn't affect the recording itself
-		}
-	}
-}
-
-/**
- * Injects a labeled rrweb custom event at the current recording timestamp so
- * the replay UI can show which step was running at any point in the timeline.
- */
-export async function markStepStart(stepName: string): Promise<void> {
-	if (!_page) return;
-	try {
-		await _page.evaluate((name) => {
-			// @ts-ignore — rrwebRecord is injected by the record.umd.min.cjs bundle
-			if (window.rrwebRecord?.record?.addCustomEvent) {
-				// @ts-ignore
-				window.rrwebRecord.record.addCustomEvent('step', { name });
-			}
-		}, stepName);
-	} catch {
-		// best-effort — a missing marker just means the replay UI won't show a
-		// step label at that point, it doesn't affect the recording itself
-	}
-}
-
-/**
- * Flushes every tab's buffered rrweb events (one per opened tab/popup) as a
- * gzip-compressed Cucumber attachment, tagged with the mime type Plum's
- * server looks for.
- */
-export async function flushRecordings(
-	attach: (data: Buffer, mime: string) => Promise<void>
-): Promise<void> {
-	if (_liveRRwebTimer) {
-		clearInterval(_liveRRwebTimer);
-		_liveRRwebTimer = null;
-	}
-	// One last live flush so the stream doesn't miss whatever happened between
-	// the final tick and scenario end.
-	flushLiveRRwebEvents();
-
-	try {
-		await attach(
-			Buffer.from(JSON.stringify({ workerId: _workerId }), 'utf8'),
-			WORKER_META_MIME_TYPE
-		);
-	} catch {
-		// best-effort — a missing worker marker just falls back to workerId 1
-	}
-
-	const flushedAt = Date.now();
-	for (const recording of _tabs.values()) {
-		if (recording.events.length === 0) continue;
-		try {
-			const payload = JSON.stringify({
-				workerId: _workerId,
-				tabId: recording.tabId,
-				tabIndex: recording.tabIndex,
-				events: recording.events,
-				openedAt: recording.openedAt,
-				// A tab still open when the scenario ends (typically the main tab)
-				// stayed relevant through to the flush, not just its last DOM event.
-				closedAt: recording.closedAt ?? flushedAt
-			});
-			const gz = zlib.gzipSync(Buffer.from(payload, 'utf8'));
-			await attach(gz, RRWEB_MIME_TYPE);
-		} catch {
-			// a failed recording flush shouldn't fail the scenario
-		}
-	}
-}
-
-export async function teardown(): Promise<void> {
-	await _browser?.close();
-}
+// Add your own page/context helpers below.

package/backend/_scaffold/utils/hooks.ts

@@ -15,53 +15,9 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-// Wires up Plum's session recording — removing or reordering code here can silently break report replay.
+import * as plum from './plum-modules/runtime';
 
-import { Before, After, BeforeStep, ITestCaseHookParameter } from '@cucumber/cucumber';
-import { setup, teardown, flushRecordings, markStepStart } from './browser';
-import dotenv from 'dotenv';
+plum.registerHooks();
 
-dotenv.config();
-
-/**
- * Pickle steps carry no keyword (Cucumber normalizes Given/When/Then/And/But
- * away during Gherkin → Pickle compilation) — recover it by walking the
- * gherkinDocument for the AST node the pickle step was compiled from.
- */
-function resolveStepKeyword(gherkinDocument: any, pickleStep: any): string {
-	const astNodeId = pickleStep?.astNodeIds?.[0];
-	if (!astNodeId) return '';
-	const steps: any[] = [];
-	for (const child of gherkinDocument?.feature?.children ?? []) {
-		if (child.background) steps.push(...child.background.steps);
-		if (child.scenario) steps.push(...child.scenario.steps);
-		for (const ruleChild of child.rule?.children ?? []) {
-			if (ruleChild.background) steps.push(...ruleChild.background.steps);
-			if (ruleChild.scenario) steps.push(...ruleChild.scenario.steps);
-		}
-	}
-	return steps.find((s) => s.id === astNodeId)?.keyword?.trim() ?? '';
-}
-
-Before(async ({ pickle }: ITestCaseHookParameter) => {
-	const tags = pickle.tags.map((t) => t.name).join(' ');
-	console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
-	await setup();
-});
-
-BeforeStep(async function ({
-	pickleStep,
-	gherkinDocument
-}: {
-	pickleStep: any;
-	gherkinDocument: any;
-}) {
-	const keyword = resolveStepKeyword(gherkinDocument, pickleStep);
-	const text = pickleStep?.text ?? '';
-	await markStepStart(keyword ? `${keyword} ${text}` : text);
-});
-
-After(async function () {
-	await flushRecordings(this.attach.bind(this));
-	await teardown();
-});
+// Add your own custom Before/After/BeforeStep hooks below — Cucumber runs
+// every registered hook, so these run alongside Plum's own.

package/backend/_scaffold/utils/plum-modules/README.md

@@ -0,0 +1,24 @@
+# Do not edit this folder
+
+Everything under `plum-modules/` is regenerated from the installed Plum version before every test run — any change you make here is silently overwritten the next time you run `plum run-test`, `plum node start`, or trigger a run from the web UI.
+
+This is what gives you Plum's session recording (rrweb) and reporting hooks. Use it from your own `tests/utils/browser.ts` and `hooks.ts`:
+
+```ts
+import * as plum from './plum-modules/runtime';
+
+export const page = () => plum.page();
+export const context = () => plum.context();
+export const browser = () => plum.browser();
+```
+
+```ts
+import * as plum from './plum-modules/runtime';
+
+plum.registerHooks();
+
+// Add your own Before/After/BeforeStep hooks below — Cucumber runs every
+// registered hook, so yours run alongside Plum's.
+```
+
+If you need something from here that isn't exported, don't copy the file — ask, since it's meant to be extended, not forked.

package/backend/_scaffold/utils/plum-modules/runtime.ts

@@ -0,0 +1,290 @@
+/*
+ * This file is part of Plum.
+ *
+ * Plum is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Plum is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Plum. If not, see https://www.gnu.org/licenses/.
+ */
+
+// DO NOT EDIT — see README.md in this directory. Plum overwrites this whole
+// folder before every run, so any change here is silently discarded.
+
+import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
+import { Before, After, BeforeStep, ITestCaseHookParameter } from '@cucumber/cucumber';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as zlib from 'zlib';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+// Must match the mime type Plum's server expects — do not change.
+const RRWEB_MIME_TYPE = 'application/x-plum-rrweb+json';
+// Always attached, even for a scenario with no recorded events, so the
+// worker that ran it is still recoverable for grouping.
+const WORKER_META_MIME_TYPE = 'application/x-plum-worker+json';
+// @rrweb/record's package.json only exports its main entry ("."), so a deep
+// require.resolve() of the UMD bundle is blocked by Node's exports map — resolve
+// the (exported) main entry instead and locate the sibling file on disk.
+const RECORD_BUNDLE_PATH = path.join(
+	path.dirname(require.resolve('@rrweb/record')),
+	'record.umd.min.cjs'
+);
+
+interface TabRecording {
+	tabId: string;
+	tabIndex: number;
+	events: unknown[];
+	openedAt: number;
+	closedAt: number | null;
+	liveFlushedCount: number;
+}
+
+let _browser: Browser;
+let _context: BrowserContext;
+let _page: Page;
+let _liveRRwebCounter = 0;
+let _liveRRwebTimer: ReturnType<typeof setInterval> | null = null;
+let _tabs: Map<Page, TabRecording> = new Map();
+let _tabCounter = 0;
+let _workerId = 1;
+
+export const page = (): Page => _page;
+export const context = (): BrowserContext => _context;
+export const browser = (): Browser => _browser;
+
+function tabIdForIndex(index: number): string {
+	return index === 0 ? 'main' : `tab-${index + 1}`;
+}
+
+// A static page (nothing left to interact with) can go a long time between
+// rrweb events, or emit none at all after its initial load — its own event
+// timestamps are a poor proxy for how long it stayed relevant. Real
+// open/close times let the replay UI line multiple tabs up on one timeline
+// without guessing from event gaps.
+function attachRecorder(pg: Page): void {
+	const tabIndex = _tabCounter++;
+	const recording: TabRecording = {
+		tabId: tabIdForIndex(tabIndex),
+		tabIndex,
+		events: [],
+		openedAt: Date.now(),
+		closedAt: null,
+		liveFlushedCount: 0
+	};
+	_tabs.set(pg, recording);
+	pg.on('close', () => {
+		recording.closedAt = Date.now();
+	});
+}
+
+export async function setup(): Promise<void> {
+	const isHeadless = process.env.IS_HEADLESS?.toLowerCase() !== 'false';
+	const browserName = (process.env.BROWSER || 'chromium').toLowerCase();
+	const browserType =
+		browserName === 'firefox' ? firefox : browserName === 'webkit' ? webkit : chromium;
+	_browser = await browserType.launch({ headless: isHeadless });
+	_context = await _browser.newContext();
+
+	_tabs = new Map();
+	_tabCounter = 0;
+	// Cucumber forks one OS process per --parallel worker and injects this env
+	// var into each — 0-indexed, so display/report as 1-based like the rest of
+	// the worker-count UI.
+	const parsedWorkerId = parseInt(process.env.CUCUMBER_WORKER_ID ?? '', 10);
+	_workerId = Number.isFinite(parsedWorkerId) ? parsedWorkerId + 1 : 1;
+
+	// Context-level exposeBinding/addInitScript apply to every page in the
+	// context automatically — current and future (popups, target=_blank tabs) —
+	// so recording setup never races a new tab's first navigation.
+	await _context.exposeBinding('__plumEmitRRwebEvent', (source, eventJson: string) => {
+		const recording = source.page && _tabs.get(source.page);
+		if (!recording) return;
+		try {
+			recording.events.push(JSON.parse(eventJson));
+		} catch {
+			// malformed event — drop it, recording is best-effort
+		}
+	});
+	await _context.addInitScript({ path: RECORD_BUNDLE_PATH });
+	await _context.addInitScript(() => {
+		// addInitScript runs in every frame, including hidden ad/tracking iframes.
+		// Recordings are tracked per-Page, so an unguarded sub-frame session would
+		// corrupt the tab's event stream with bogus 0x0 "about:blank" entries.
+		// @ts-ignore
+		if (window.self !== window.top) return;
+		// @ts-ignore
+		if (window.rrwebRecord) {
+			// @ts-ignore
+			window.rrwebRecord.record({
+				emit: (event: unknown) => {
+					// @ts-ignore — exposed by BrowserContext.exposeBinding above
+					window.__plumEmitRRwebEvent(JSON.stringify(event));
+				}
+			});
+		}
+	});
+
+	_context.on('page', attachRecorder);
+	_page = await _context.newPage();
+
+	// Only when someone's actually watching live — a scheduled/background run
+	// with no viewer shouldn't pay for this.
+	if (process.env.PLUM_SS_DIR) {
+		_liveRRwebTimer = setInterval(flushLiveRRwebEvents, 500);
+	}
+}
+
+// Sends only what's newly arrived since the last tick, per tab, so the live
+// viewer gets a steady trickle instead of the full buffer growing unbounded.
+function flushLiveRRwebEvents(): void {
+	const ssDir = process.env.PLUM_SS_DIR;
+	if (!ssDir) return;
+	for (const recording of _tabs.values()) {
+		const newEvents = recording.events.slice(recording.liveFlushedCount);
+		if (newEvents.length === 0) continue;
+		recording.liveFlushedCount = recording.events.length;
+		try {
+			const seq = `${String(Date.now()).padStart(16, '0')}-${String(++_liveRRwebCounter).padStart(4, '0')}`;
+			fs.writeFileSync(
+				path.join(ssDir, `${seq}.rrweb.json`),
+				JSON.stringify({
+					workerId: _workerId,
+					tabId: recording.tabId,
+					tabIndex: recording.tabIndex,
+					events: newEvents
+				})
+			);
+		} catch {
+			// best-effort — live streaming shouldn't affect the recording itself
+		}
+	}
+}
+
+/**
+ * Injects a labeled rrweb custom event at the current recording timestamp so
+ * the replay UI can show which step was running at any point in the timeline.
+ */
+export async function markStepStart(stepName: string): Promise<void> {
+	if (!_page) return;
+	try {
+		await _page.evaluate((name) => {
+			// @ts-ignore — rrwebRecord is injected by the record.umd.min.cjs bundle
+			if (window.rrwebRecord?.record?.addCustomEvent) {
+				// @ts-ignore
+				window.rrwebRecord.record.addCustomEvent('step', { name });
+			}
+		}, stepName);
+	} catch {
+		// best-effort — a missing marker just means the replay UI won't show a
+		// step label at that point, it doesn't affect the recording itself
+	}
+}
+
+/**
+ * Flushes every tab's buffered rrweb events (one per opened tab/popup) as a
+ * gzip-compressed Cucumber attachment, tagged with the mime type Plum's
+ * server looks for.
+ */
+export async function flushRecordings(
+	attach: (data: Buffer, mime: string) => Promise<void>
+): Promise<void> {
+	if (_liveRRwebTimer) {
+		clearInterval(_liveRRwebTimer);
+		_liveRRwebTimer = null;
+	}
+	// One last live flush so the stream doesn't miss whatever happened between
+	// the final tick and scenario end.
+	flushLiveRRwebEvents();
+
+	try {
+		await attach(
+			Buffer.from(JSON.stringify({ workerId: _workerId }), 'utf8'),
+			WORKER_META_MIME_TYPE
+		);
+	} catch {
+		// best-effort — a missing worker marker just falls back to workerId 1
+	}
+
+	const flushedAt = Date.now();
+	for (const recording of _tabs.values()) {
+		if (recording.events.length === 0) continue;
+		try {
+			const payload = JSON.stringify({
+				workerId: _workerId,
+				tabId: recording.tabId,
+				tabIndex: recording.tabIndex,
+				events: recording.events,
+				openedAt: recording.openedAt,
+				// A tab still open when the scenario ends (typically the main tab)
+				// stayed relevant through to the flush, not just its last DOM event.
+				closedAt: recording.closedAt ?? flushedAt
+			});
+			const gz = zlib.gzipSync(Buffer.from(payload, 'utf8'));
+			await attach(gz, RRWEB_MIME_TYPE);
+		} catch {
+			// a failed recording flush shouldn't fail the scenario
+		}
+	}
+}
+
+export async function teardown(): Promise<void> {
+	await _browser?.close();
+}
+
+// Pickle steps carry no keyword (Cucumber normalizes Given/When/Then/And/But
+// away during Gherkin → Pickle compilation) — recover it by walking the
+// gherkinDocument for the AST node the pickle step was compiled from.
+function resolveStepKeyword(gherkinDocument: any, pickleStep: any): string {
+	const astNodeId = pickleStep?.astNodeIds?.[0];
+	if (!astNodeId) return '';
+	const steps: any[] = [];
+	for (const child of gherkinDocument?.feature?.children ?? []) {
+		if (child.background) steps.push(...child.background.steps);
+		if (child.scenario) steps.push(...child.scenario.steps);
+		for (const ruleChild of child.rule?.children ?? []) {
+			if (ruleChild.background) steps.push(...ruleChild.background.steps);
+			if (ruleChild.scenario) steps.push(...ruleChild.scenario.steps);
+		}
+	}
+	return steps.find((s) => s.id === astNodeId)?.keyword?.trim() ?? '';
+}
+
+/**
+ * Registers Plum's own Before/BeforeStep/After hooks. Call once from your
+ * own tests/utils/hooks.ts — Cucumber supports multiple Before/After hooks,
+ * so your own hooks can still be added alongside this.
+ */
+export function registerHooks(): void {
+	Before(async ({ pickle }: ITestCaseHookParameter) => {
+		const tags = pickle.tags.map((t) => t.name).join(' ');
+		console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
+		await setup();
+	});
+
+	BeforeStep(async function ({
+		pickleStep,
+		gherkinDocument
+	}: {
+		pickleStep: any;
+		gherkinDocument: any;
+	}) {
+		const keyword = resolveStepKeyword(gherkinDocument, pickleStep);
+		const text = pickleStep?.text ?? '';
+		await markStepStart(keyword ? `${keyword} ${text}` : text);
+	});
+
+	After(async function () {
+		await flushRecordings(this.attach.bind(this));
+		await teardown();
+	});
+}

package/backend/config/scripts/run-tests.js

@@ -29,6 +29,19 @@ let testExitCode = 0;
 
 try {
 	const testsRoot = (process.env.TESTS_ROOT || 'tests').replace(/\\/g, '/');
+	const testsRootAbsForSync = path.isAbsolute(testsRoot)
+		? testsRoot
+		: path.resolve(process.cwd(), testsRoot);
+
+	// tests/utils/browser.ts and hooks.ts import Plum's recording wiring from
+	// here — always overwritten from whatever Plum version is actually running
+	// this script, so it's never stale and never something a customer can
+	// accidentally lose track of by not re-running an update command. Safe to
+	// force unconditionally: nothing customer-owned ever lives in this folder.
+	const plumModulesSrc = path.join(__dirname, '..', '..', '_scaffold', 'utils', 'plum-modules');
+	const plumModulesDest = path.join(testsRootAbsForSync, 'utils', 'plum-modules');
+	fs.rmSync(plumModulesDest, { recursive: true, force: true });
+	fs.cpSync(plumModulesSrc, plumModulesDest, { recursive: true });
 
 	// Dispatched tests run from an external dir (e.g. a temp dir on a node) that has
 	// no node_modules of its own — point Node at the backend's modules so imports

package/backend/services/reportService.js

@@ -11,9 +11,8 @@ const { isScheduledTrigger, normaliseTrigger } = require('../constants/triggers'
 const { DEFAULT_BROWSER } = require('../constants/defaults');
 const { REPORT_STATUS } = require('../constants/jobStatus');
 
-// Matched by string literal in backend/tests/utils/browser.ts (flushRecordings) —
-// the two runtimes don't share a module, mirroring how 'image/png' is already
-// duplicated between the two files.
+// Matched by string literal in backend/_scaffold/utils/plum-modules/runtime.ts
+// (flushRecordings) — the two runtimes don't share a module.
 const RRWEB_MIME_TYPE = 'application/x-plum-rrweb+json';
 // Small, always-attached marker (independent of whether any tab actually
 // recorded events) so a scenario's worker is always recoverable for grouping,

package/bin/plum.js

@@ -62,6 +62,114 @@ function scaffoldPluginsFile() {
 	clack.log.success('plum.plugins.json created.');
 }
 
+// Files under tests/ that Plum's own scaffold originally wrote — `plum init`
+// only writes these once, so a project scaffolded before a Plum upgrade keeps
+// running whatever version shipped at init time (e.g. an old screenshot-based
+// browser.ts after Plum has moved to rrweb recording) unless something
+// explicitly re-syncs them.
+//
+// These are also exactly the files real projects most often rewrite entirely
+// with their own setup/teardown/cleanup logic — a project's browser.ts can
+// end up exporting things Plum's own template never did (extra page-object
+// helpers, auth header routing, multi-context session handling), which other
+// files in that project then import and depend on. A blind overwrite of a
+// file like that doesn't just discard "unsupported edits" — it silently
+// breaks every file that imports what used to be there, and can disable
+// cleanup logic another system relies on for a clean state. A backup makes
+// that recoverable, but "recoverable after your suite breaks" is still a bad
+// default, so this never overwrites unless explicitly told to.
+const INFRA_SCAFFOLD_FILES = ['utils/browser.ts', 'utils/hooks.ts'];
+
+// Nothing customer-owned ever lives here — it's the same folder run-tests.js
+// force-refreshes before every test run — so unlike INFRA_SCAFFOLD_FILES this
+// is always safe to overwrite unconditionally, no diffing or backup needed.
+// Re-syncing it here too (not just at test-run time) means `plum update` /
+// `plum sync-scaffold` alone are enough to leave a project actually working,
+// without requiring a test run first.
+const PLUM_MANAGED_DIR = 'utils/plum-modules';
+
+function syncPlumModulesDir(testsDir) {
+	const src = path.join(scaffoldTestsPath, PLUM_MANAGED_DIR);
+	const dest = path.join(testsDir, PLUM_MANAGED_DIR);
+	if (!fs.existsSync(src)) return;
+	fs.rmSync(dest, { recursive: true, force: true });
+	fse.copySync(src, dest);
+}
+
+// Reports which INFRA_SCAFFOLD_FILES differ from the installed Plum version's
+// scaffold. With force:true, re-syncs them into the tests/ directory,
+// backing up whatever it overwrites — otherwise this never touches a file,
+// only reports on it, since diffing alone can't tell "untouched and stale"
+// apart from "extensively customized to depend on this exact content."
+// Always re-syncs PLUM_MANAGED_DIR regardless of force, since that part is
+// never customer-owned.
+function syncScaffoldInfraFiles(testsDir, { force = false } = {}) {
+	if (!fs.existsSync(testsDir)) {
+		clack.log.warn(`No \`tests/\` folder found at ${testsDir} — skipping scaffold sync.`);
+		return;
+	}
+
+	syncPlumModulesDir(testsDir);
+
+	let changed = 0;
+	let stale = 0;
+	for (const relPath of INFRA_SCAFFOLD_FILES) {
+		const src = path.join(scaffoldTestsPath, relPath);
+		const dest = path.join(testsDir, relPath);
+		if (!fs.existsSync(src) || !fs.existsSync(dest)) continue;
+
+		const current = fs.readFileSync(dest, 'utf8');
+		const latest = fs.readFileSync(src, 'utf8');
+		if (current === latest) continue;
+
+		// A file that already imports plum-modules/runtime has adopted the
+		// current pattern and will keep differing from the bare scaffold
+		// forever once a customer adds their own code around it — that's
+		// expected and not something to warn about every time. Only a file
+		// that never picked up the import at all needs pointing somewhere.
+		const alreadyWired = current.includes('plum-modules/runtime');
+
+		if (!force) {
+			stale++;
+			if (alreadyWired) {
+				clack.log.info(
+					`${relPath} is customized but already wired to plum-modules/ — nothing to do.`
+				);
+				continue;
+			}
+			clack.log.warn(
+				`${relPath} doesn't import Plum's recording wiring — reports for this project won't ` +
+					`include session replay until it's added. This file is never auto-overwritten, so add it ` +
+					`yourself:\n` +
+					(relPath === 'utils/hooks.ts'
+						? `    Near the top of tests/${relPath}:\n` +
+							`      import * as plum from './plum-modules/runtime';\n` +
+							`      plum.registerHooks();\n` +
+							`    Keep your own Before/After/BeforeStep hooks below that line — Cucumber runs every registered hook.`
+						: `    Near the top of tests/${relPath}:\n` +
+							`      import * as plum from './plum-modules/runtime';\n` +
+							`    Then point your helpers at it, e.g.:\n` +
+							`      export const page = () => plum.page();\n` +
+							`      export const context = () => plum.context();\n` +
+							`      export const browser = () => plum.browser();`)
+			);
+			continue;
+		}
+
+		const backupPath = `${dest}.bak-${Date.now()}`;
+		fs.copyFileSync(dest, backupPath);
+		fs.copyFileSync(src, dest);
+		changed++;
+		clack.log.success(
+			`Updated ${relPath} (previous version backed up to ${path.basename(backupPath)})`
+		);
+	}
+
+	if (changed === 0 && stale === 0) {
+		clack.log.info('Test scaffold wiring is already up to date.');
+	}
+}
+
 // Install user plugins listed in plum.plugins.json into the backend
 function installPlugins() {
 	const pluginsPath = path.join(process.cwd(), 'plum.plugins.json');
@@ -511,6 +619,31 @@ async function serverUpdate() {
 	// logic no matter how new the just-installed files on disk actually are.
 	for (const dir of getInstalls('server')) {
 		if (!fs.existsSync(path.join(dir, '.plum-server.json'))) continue;
+
+		// Runs before the restart confirm below, and regardless of its answer —
+		// this only ever touches plum-modules/ (never customer-owned, see
+		// syncScaffoldInfraFiles) plus a warn-only check on browser.ts/hooks.ts,
+		// so there's nothing here that restarting the server is a prerequisite
+		// for, or that declining the restart should skip.
+		if (fs.existsSync(path.join(dir, 'tests'))) {
+			syncScaffoldInfraFiles(path.join(dir, 'tests'));
+		}
+
+		// This registry is global to the machine, not scoped to the directory
+		// `plum update` was run from — an unrelated project on the same machine
+		// as a registered server would otherwise silently boot that server's
+		// Docker stack. Ask first whenever there's someone to ask; a
+		// non-interactive run (CI, cron, systemd) has no one to ask and keeps
+		// the previous unconditional behavior.
+		if (interactiveAllowed()) {
+			const proceed = await clack.confirm({
+				message: `Found a registered server at ${dir} — restart it?`,
+				initialValue: true
+			});
+			if (clack.isCancel(proceed)) cancelAndExit();
+			if (!proceed) continue;
+		}
+
 		clack.log.step(`Rebuilding server at ${dir}…`);
 		try {
 			execSync('plum server restart', { stdio: 'inherit', cwd: dir });
@@ -523,6 +656,24 @@ async function serverUpdate() {
 	for (const dir of getInstalls('node')) {
 		const nodeCfg = loadNodeConfig(dir);
 		if (!nodeCfg.id) continue;
+
+		// Same reasoning as the server loop above: runs regardless of whether
+		// the restart below gets confirmed.
+		if (fs.existsSync(path.join(dir, 'tests'))) {
+			syncScaffoldInfraFiles(path.join(dir, 'tests'));
+		}
+
+		// This registry spans the whole machine, not just the directory
+		// `plum update` was run from.
+		if (interactiveAllowed()) {
+			const proceed = await clack.confirm({
+				message: `Found a registered node at ${dir} — restart it?`,
+				initialValue: true
+			});
+			if (clack.isCancel(proceed)) cancelAndExit();
+			if (!proceed) continue;
+		}
+
 		// Always attempt the restart rather than gating on the local PID
 		// registry: that registry goes stale (manager restarts, pre-existing
 		// installs from before this tracking existed, etc.), and skipping the
@@ -1093,6 +1244,14 @@ switch (command) {
 		await serverUpdate();
 		break;
 
+	case 'sync-scaffold': {
+		clack.intro(pc.bgMagenta(pc.white('  🟣 Plum — Sync Test Scaffold  ')));
+		const force = anyFlags(process.argv.slice(3), ['--force']);
+		syncScaffoldInfraFiles(userTestsPath, { force });
+		clack.outro(pc.green('Done.'));
+		break;
+	}
+
 	case 'run-test': {
 		const runHelpArgs = process.argv.slice(3);
 		if (anyFlags(runHelpArgs, ['--help', '-h'])) {
@@ -1299,7 +1458,13 @@ switch (command) {
 		console.log('  server stop          Stop the server (data preserved)');
 		console.log('  server reconfig      Re-enter server settings without starting');
 		console.log(
-			'  update               Update Plum and restart whichever is running (server/node)'
+			'  update               Update Plum, restart whichever is running (server/node), and check tests/ wiring for updates'
+		);
+		console.log(
+			'  sync-scaffold        Check browser.ts/hooks.ts in tests/ against the installed Plum version'
+		);
+		console.log(
+			'    --force            Overwrite files that differ (previous version backed up first)'
 		);
 		console.log('  node start           Start a runner node (interactive), then open runner menu');
 		console.log('    --primary <url>    Primary Plum server to auto-register with');

package/frontend/.svelte-kit/ambient.d.ts

@@ -58,41 +58,42 @@ declare module '$env/static/private' {
 	export const VIKUNJA_API_KEY: string;
 	export const USER: string;
 	export const COMMAND_MODE: string;
-	export const npm_config_globalconfig: string;
 	export const OUTLINE_BASE_URL: string;
+	export const npm_config_globalconfig: string;
 	export const CLAUDE_CODE_SSE_PORT: string;
 	export const SSH_AUTH_SOCK: string;
 	export const VSCODE_PROFILE_INITIALIZED: string;
 	export const __CF_USER_TEXT_ENCODING: string;
 	export const npm_execpath: string;
 	export const PATH: string;
-	export const npm_package_json: string;
+	export const npm_package_bin_plum: string;
 	export const npm_config_engine_strict: string;
 	export const _: string;
-	export const npm_config_userconfig: string;
-	export const npm_config_init_module: string;
+	export const npm_package_json: string;
 	export const USER_ZDOTDIR: string;
 	export const __CFBundleIdentifier: string;
-	export const npm_command: string;
+	export const npm_config_init_module: string;
+	export const npm_config_userconfig: string;
 	export const PWD: string;
-	export const npm_lifecycle_event: string;
-	export const EDITOR: string;
+	export const npm_command: string;
 	export const OUTLINE_API_KEY: string;
-	export const npm_package_name: string;
+	export const EDITOR: string;
+	export const npm_lifecycle_event: string;
 	export const LANG: string;
-	export const npm_config_npm_version: string;
+	export const npm_package_name: string;
 	export const VSCODE_GIT_ASKPASS_EXTRA_ARGS: string;
 	export const XPC_FLAGS: string;
+	export const npm_config_npm_version: string;
 	export const npm_config_node_gyp: string;
-	export const npm_package_version: string;
 	export const XPC_SERVICE_NAME: string;
+	export const npm_package_version: string;
 	export const VSCODE_INJECTION: string;
 	export const SHLVL: string;
 	export const HOME: string;
 	export const VSCODE_GIT_ASKPASS_MAIN: string;
 	export const CLAUDE_CODE_EXECPATH: string;
-	export const npm_config_cache: string;
 	export const LOGNAME: string;
+	export const npm_config_cache: string;
 	export const npm_lifecycle_script: string;
 	export const VSCODE_GIT_IPC_HANDLE: string;
 	export const COREPACK_ENABLE_AUTO_PIN: string;
@@ -103,10 +104,9 @@ declare module '$env/static/private' {
 	export const OSLogRateLimit: string;
 	export const CLAUDECODE: string;
 	export const CLAUDE_CODE_MESSAGING_SOCKET: string;
-	export const npm_node_execpath: string;
-	export const npm_config_prefix: string;
 	export const COLORTERM: string;
-	export const NODE_ENV: string;
+	export const npm_config_prefix: string;
+	export const npm_node_execpath: string;
 }
 
 /**
@@ -165,41 +165,42 @@ declare module '$env/dynamic/private' {
 		VIKUNJA_API_KEY: string;
 		USER: string;
 		COMMAND_MODE: string;
-		npm_config_globalconfig: string;
 		OUTLINE_BASE_URL: string;
+		npm_config_globalconfig: string;
 		CLAUDE_CODE_SSE_PORT: string;
 		SSH_AUTH_SOCK: string;
 		VSCODE_PROFILE_INITIALIZED: string;
 		__CF_USER_TEXT_ENCODING: string;
 		npm_execpath: string;
 		PATH: string;
-		npm_package_json: string;
+		npm_package_bin_plum: string;
 		npm_config_engine_strict: string;
 		_: string;
-		npm_config_userconfig: string;
-		npm_config_init_module: string;
+		npm_package_json: string;
 		USER_ZDOTDIR: string;
 		__CFBundleIdentifier: string;
-		npm_command: string;
+		npm_config_init_module: string;
+		npm_config_userconfig: string;
 		PWD: string;
-		npm_lifecycle_event: string;
-		EDITOR: string;
+		npm_command: string;
 		OUTLINE_API_KEY: string;
-		npm_package_name: string;
+		EDITOR: string;
+		npm_lifecycle_event: string;
 		LANG: string;
-		npm_config_npm_version: string;
+		npm_package_name: string;
 		VSCODE_GIT_ASKPASS_EXTRA_ARGS: string;
 		XPC_FLAGS: string;
+		npm_config_npm_version: string;
 		npm_config_node_gyp: string;
-		npm_package_version: string;
 		XPC_SERVICE_NAME: string;
+		npm_package_version: string;
 		VSCODE_INJECTION: string;
 		SHLVL: string;
 		HOME: string;
 		VSCODE_GIT_ASKPASS_MAIN: string;
 		CLAUDE_CODE_EXECPATH: string;
-		npm_config_cache: string;
 		LOGNAME: string;
+		npm_config_cache: string;
 		npm_lifecycle_script: string;
 		VSCODE_GIT_IPC_HANDLE: string;
 		COREPACK_ENABLE_AUTO_PIN: string;
@@ -210,10 +211,9 @@ declare module '$env/dynamic/private' {
 		OSLogRateLimit: string;
 		CLAUDECODE: string;
 		CLAUDE_CODE_MESSAGING_SOCKET: string;
-		npm_node_execpath: string;
-		npm_config_prefix: string;
 		COLORTERM: string;
-		NODE_ENV: string;
+		npm_config_prefix: string;
+		npm_node_execpath: string;
 		[key: `PUBLIC_${string}`]: undefined;
 		[key: `${string}`]: string | undefined;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "plum-e2e",
-	"version": "2.9.0",
+	"version": "2.9.2",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/silverlunah/plum.git"