plum-e2e 2.9.0 → 2.9.1

package/README.md

@@ -79,25 +79,26 @@ 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, auto-restart whatever is running (server or node), and re-sync `tests/utils/browser.ts`/`hooks.ts` from the installed version |
+| `plum sync-scaffold`          | Re-sync `tests/utils/browser.ts`/`hooks.ts` from the installed Plum version without a full update (old copies are backed up, never lost)   |
+| `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                                                                                                |
 
 ---
 

package/backend/_scaffold/utils/browser.ts

@@ -15,222 +15,12 @@
  * 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.
+// Thin pass-through to Plum's own recording wiring, kept inside the installed
+// Plum package rather than copied here — this file exists so page objects
+// have a stable `page()`/`context()` to import.
+import type { Page, BrowserContext } from 'playwright';
 
-import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as zlib from 'zlib';
+const runtime = require(process.env.PLUM_RUNTIME_PATH as string);
 
-// 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();
-}
+export const page = (): Page => runtime.page();
+export const context = (): BrowserContext => runtime.context();

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.
+// Thin pass-through to Plum's own recording wiring, kept inside the installed
+// Plum package rather than copied here.
+require(process.env.PLUM_RUNTIME_PATH as string).registerHooks();
 
-import { Before, After, BeforeStep, ITestCaseHookParameter } from '@cucumber/cucumber';
-import { setup, teardown, flushRecordings, markStepStart } from './browser';
-import dotenv from 'dotenv';
-
-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/config/scripts/run-tests.js

@@ -112,7 +112,11 @@ try {
 			// When running from a temp dir there is no tsconfig.json above it, so
 			// ts-node falls back to defaults that may conflict with the Node version.
 			// Point it at the backend tsconfig explicitly.
-			...(execCwd && { TS_NODE_PROJECT: path.resolve(__dirname, '..', '..', 'tsconfig.json') })
+			...(execCwd && { TS_NODE_PROJECT: path.resolve(__dirname, '..', '..', 'tsconfig.json') }),
+			// tests/utils/browser.ts and hooks.ts are a thin pass-through to this —
+			// an absolute path works the same whether cwd is backend/ (local run) or
+			// a temp dir with no relation to backend/ (a dispatched node run).
+			PLUM_RUNTIME_PATH: path.resolve(__dirname, '..', '..', 'lib', 'plumTestRuntime.js')
 		}
 	});
 } catch (error) {

package/backend/lib/plumTestRuntime.js

@@ -0,0 +1,262 @@
+/*
+ * This file is part of Plum.
+ * Licensed under the MIT License. See LICENSE file in the project root for details.
+ */
+
+// The actual implementation behind tests/utils/browser.ts and hooks.ts.
+// Customer test projects only get a thin pass-through to this module (see
+// backend/_scaffold/utils/) — keeping the real wiring here means every
+// `npm install -g plum-e2e@latest` picks up fixes/changes immediately,
+// without needing to re-sync anything into an existing customer project.
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const dotenv = require('dotenv');
+const { chromium, firefox, webkit } = require('playwright');
+const { Before, After, BeforeStep } = require('@cucumber/cucumber');
+
+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'
+);
+
+let _browser;
+let _context;
+let _page;
+let _liveRRwebCounter = 0;
+let _liveRRwebTimer = null;
+let _tabs = new Map();
+let _tabCounter = 0;
+let _workerId = 1;
+
+const page = () => _page;
+const context = () => _context;
+
+function tabIdForIndex(index) {
+	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) {
+	const tabIndex = _tabCounter++;
+	const recording = {
+		tabId: tabIdForIndex(tabIndex),
+		tabIndex,
+		events: [],
+		openedAt: Date.now(),
+		closedAt: null,
+		liveFlushedCount: 0
+	};
+	_tabs.set(pg, recording);
+	pg.on('close', () => {
+		recording.closedAt = Date.now();
+	});
+}
+
+async function setup() {
+	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) => {
+		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.
+		if (window.self !== window.top) return;
+		if (window.rrwebRecord) {
+			window.rrwebRecord.record({
+				emit: (event) => {
+					// 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() {
+	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.
+async function markStepStart(stepName) {
+	if (!_page) return;
+	try {
+		await _page.evaluate((name) => {
+			if (window.rrwebRecord?.record?.addCustomEvent) {
+				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.
+async function flushRecordings(attach) {
+	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
+		}
+	}
+}
+
+async function teardown() {
+	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, pickleStep) {
+	const astNodeId = pickleStep?.astNodeIds?.[0];
+	if (!astNodeId) return '';
+	const steps = [];
+	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 the
+// project's own tests/utils/hooks.ts — Cucumber supports multiple Before/After
+// hooks, so a customer's own hooks can still be added alongside this.
+function registerHooks() {
+	Before(async ({ pickle }) => {
+		const tags = pickle.tags.map((t) => t.name).join(' ');
+		console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
+		await setup();
+	});
+
+	BeforeStep(async function ({ pickleStep, gherkinDocument }) {
+		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();
+	});
+}
+
+module.exports = {
+	page,
+	context,
+	setup,
+	teardown,
+	flushRecordings,
+	markStepStart,
+	registerHooks
+};

package/bin/plum.js

@@ -62,6 +62,48 @@ function scaffoldPluginsFile() {
 	clack.log.success('plum.plugins.json created.');
 }
 
+// Files under tests/ that are Plum's own wiring rather than customer content —
+// `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. Never touches customer-owned files
+// (features/, pages/, step_definitions/, utils/constants.ts, utils/utils.ts).
+const INFRA_SCAFFOLD_FILES = ['utils/browser.ts', 'utils/hooks.ts'];
+
+// Re-syncs INFRA_SCAFFOLD_FILES from the installed Plum version's scaffold
+// into an existing tests/ directory, backing up anything it overwrites so a
+// customer's own edits to these files (unsupported, but possible) aren't
+// silently lost.
+function syncScaffoldInfraFiles(testsDir) {
+	if (!fs.existsSync(testsDir)) {
+		clack.log.warn(`No \`tests/\` folder found at ${testsDir} — skipping scaffold sync.`);
+		return;
+	}
+
+	let updated = 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;
+
+		const backupPath = `${dest}.bak-${Date.now()}`;
+		fs.copyFileSync(dest, backupPath);
+		fs.copyFileSync(src, dest);
+		updated++;
+		clack.log.success(
+			`Updated ${relPath} (previous version backed up to ${path.basename(backupPath)})`
+		);
+	}
+
+	if (updated === 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 +553,9 @@ 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;
+		if (fs.existsSync(path.join(dir, 'tests'))) {
+			syncScaffoldInfraFiles(path.join(dir, 'tests'));
+		}
 		clack.log.step(`Rebuilding server at ${dir}…`);
 		try {
 			execSync('plum server restart', { stdio: 'inherit', cwd: dir });
@@ -523,6 +568,9 @@ async function serverUpdate() {
 	for (const dir of getInstalls('node')) {
 		const nodeCfg = loadNodeConfig(dir);
 		if (!nodeCfg.id) continue;
+		if (fs.existsSync(path.join(dir, 'tests'))) {
+			syncScaffoldInfraFiles(path.join(dir, 'tests'));
+		}
 		// 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 +1141,12 @@ switch (command) {
 		await serverUpdate();
 		break;
 
+	case 'sync-scaffold':
+		clack.intro(pc.bgMagenta(pc.white('  🟣 Plum — Sync Test Scaffold  ')));
+		syncScaffoldInfraFiles(userTestsPath);
+		clack.outro(pc.green('Done.'));
+		break;
+
 	case 'run-test': {
 		const runHelpArgs = process.argv.slice(3);
 		if (anyFlags(runHelpArgs, ['--help', '-h'])) {
@@ -1299,7 +1353,10 @@ 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 re-sync tests/ wiring'
+		);
+		console.log(
+			'  sync-scaffold        Re-sync browser.ts/hooks.ts in tests/ from the installed Plum version'
 		);
 		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.1",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/silverlunah/plum.git"