plum-e2e 2.9.3 → 2.9.6

package/README.md

@@ -79,33 +79,25 @@ 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, 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.
+| 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 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,11 +15,229 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-import type { Page, BrowserContext, Browser } from 'playwright';
-import * as plum from './plum-modules/runtime';
+// Wires up Plum's session recording — removing or reordering code here can silently break report replay.
 
-export const page = (): Page => plum.page();
-export const context = (): BrowserContext => plum.context();
-export const browser = (): Browser => plum.browser();
+import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as zlib from 'zlib';
 
-// Add your own page/context helpers below.
+// 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();
+}
+
+// ---------------------------------------------------------------------------
+// Your code below this line. Everything above wires up Plum's session
+// recording — leave it as-is. Add your own page/context helpers here, built
+// on the exported page()/context() above (e.g. a helper for a second tab or
+// a second browser context).
+// ---------------------------------------------------------------------------

package/backend/_scaffold/utils/hooks.ts

@@ -15,9 +15,59 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-import * as plum from './plum-modules/runtime';
+// Wires up Plum's session recording — removing or reordering code here can silently break report replay.
 
-plum.registerHooks();
+import { Before, After, BeforeStep, ITestCaseHookParameter } from '@cucumber/cucumber';
+import { setup, teardown, flushRecordings, markStepStart } from './browser';
+import dotenv from 'dotenv';
 
-// Add your own custom Before/After/BeforeStep hooks below — Cucumber runs
-// every registered hook, so these run alongside Plum's own.
+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();
+});
+
+// ---------------------------------------------------------------------------
+// Your code below this line. Everything above wires up Plum's session
+// recording — leave it as-is. Add your own Before/After/BeforeStep hooks
+// here; Cucumber runs every registered hook, so yours run alongside Plum's.
+// ---------------------------------------------------------------------------

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

@@ -29,19 +29,6 @@ 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,8 +11,9 @@ const { isScheduledTrigger, normaliseTrigger } = require('../constants/triggers'
 const { DEFAULT_BROWSER } = require('../constants/defaults');
 const { REPORT_STATUS } = require('../constants/jobStatus');
 
-// Matched by string literal in backend/_scaffold/utils/plum-modules/runtime.ts
-// (flushRecordings) — the two runtimes don't share a module.
+// 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.
 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,114 +62,6 @@ 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');
@@ -620,15 +512,6 @@ async function serverUpdate() {
 	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
@@ -657,12 +540,6 @@ async function serverUpdate() {
 		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()) {
@@ -1244,14 +1121,6 @@ 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'])) {
@@ -1458,13 +1327,7 @@ 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, 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)'
+			'  update               Update Plum and restart whichever is running (server/node)'
 		);
 		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/package.json

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

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

@@ -1,24 +0,0 @@
-# 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

@@ -1,290 +0,0 @@
-/*
- * 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();
-	});
-}