plum-e2e 2.8.6 → 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,68 +15,12 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-import { chromium, firefox, webkit, Browser, BrowserContext, Page } from 'playwright';
-import * as fs from 'fs';
-import * as path from 'path';
+// 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';
 
-let _browser: Browser;
-let _context: BrowserContext;
-let _page: Page;
-let _ssCounter = 0;
+const runtime = require(process.env.PLUM_RUNTIME_PATH as string);
 
-export const page = (): Page => _page;
-
-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();
-	_page = await _context.newPage();
-}
-
-export async function screenshotStep(
-	attach: (data: Buffer, mime: string) => Promise<void>
-): Promise<void> {
-	if (!_page) return;
-	try {
-		const screenshot = await _page.screenshot({ type: 'png' });
-		await attach(screenshot, 'image/png');
-	} catch {
-		// page may be navigating or already closed
-	}
-}
-
-export async function streamLiveScreenshot(stepName: string): Promise<void> {
-	const ssDir = process.env.PLUM_SS_DIR;
-	if (!ssDir || !_page) return;
-	try {
-		const seq = `${String(Date.now()).padStart(16, '0')}-${String(++_ssCounter).padStart(4, '0')}`;
-		const screenshot = await _page.screenshot({ type: 'jpeg', quality: 70 });
-		fs.writeFileSync(
-			path.join(ssDir, `${seq}.ss.json`),
-			JSON.stringify({ stepName, data: screenshot.toString('base64') })
-		);
-	} catch {
-		// ignore — live streaming is best-effort
-	}
-}
-
-export async function teardown(
-	attach: (data: Buffer, mime: string) => Promise<void>,
-	failed: boolean
-): Promise<void> {
-	if (failed && _page) {
-		const screenshotDir = 'reports/screenshots';
-		if (!fs.existsSync(screenshotDir)) {
-			fs.mkdirSync(screenshotDir, { recursive: true });
-		}
-		const screenshotPath = path.join(screenshotDir, `screenshot_${Date.now()}.png`);
-		await _page.screenshot({ path: screenshotPath });
-		const screenshotData = fs.readFileSync(screenshotPath);
-		await attach(screenshotData, 'image/png');
-		fs.unlinkSync(screenshotPath);
-	}
-	await _browser?.close();
-}
+export const page = (): Page => runtime.page();
+export const context = (): BrowserContext => runtime.context();

package/backend/_scaffold/utils/hooks.ts

@@ -15,24 +15,9 @@
  * along with Plum. If not, see https://www.gnu.org/licenses/.
  */
 
-import { Before, After, AfterStep, ITestCaseHookParameter } from '@cucumber/cucumber';
-import { setup, teardown, screenshotStep, streamLiveScreenshot } from './browser';
-import dotenv from 'dotenv';
+// 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();
 
-dotenv.config();
-
-Before(async ({ pickle }: ITestCaseHookParameter) => {
-	const tags = pickle.tags.map((t) => t.name).join(' ');
-	console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
-	await setup();
-});
-
-AfterStep(async function ({ pickleStep, result }: { pickleStep: any; result: any }) {
-	if (result?.status === 'SKIPPED') return;
-	await screenshotStep(this.attach.bind(this));
-	await streamLiveScreenshot(pickleStep?.text ?? '');
-});
-
-After(async function (scenario: ITestCaseHookParameter) {
-	await teardown(this.attach.bind(this), scenario.result?.status === 'FAILED');
-});
+// Add your own custom Before/After/BeforeStep hooks below — Cucumber runs
+// every registered hook, so these run alongside Plum's own.

package/backend/app.js

@@ -3,10 +3,8 @@
  * Licensed under the MIT License. See LICENSE file in the project root for details.
  */
 
-const path = require('path');
 const express = require('express');
 const cors = require('cors');
-const { SCREENSHOTS_DIR } = require('./lib/reportFilename');
 const { isNodeMode } = require('./constants/env');
 const app = express();
 
@@ -16,9 +14,6 @@ app.use(cors({ origin: '*' }));
 // before a real test suite does.
 app.use(express.json({ limit: '500mb' }));
 
-// Serve screenshot files written during report processing
-app.use('/screenshots', express.static(SCREENSHOTS_DIR));
-
 // Routes
 const nodeRoutes = require('./routes/node.routes');
 app.use('/api', nodeRoutes);

package/backend/config/scripts/generate-report.js

@@ -36,7 +36,7 @@ if (!process.env.DATABASE_URL) {
 		const reportService = require('../../services/reportService');
 		const triggerType = normaliseTrigger(process.env.TRIGGER);
 		const rawTag = process.env.TAG || '@all-tests';
-		const nodeCount = Math.max(
+		const workerCount = Math.max(
 			1,
 			parseInt(process.env.REPORT_RUNNERS || process.env.PARALLEL || '1', 10) || 1
 		);
@@ -45,7 +45,7 @@ if (!process.env.DATABASE_URL) {
 			rawCucumberJson: raw,
 			tags: rawTag,
 			triggerType,
-			nodeCount,
+			workerCount,
 			browser: process.env.BROWSER || DEFAULT_BROWSER,
 			runnerName: process.env.RUNNER_NAME || null,
 			runnerId: process.env.RUNNER_ID || null,

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/constants/socketEvents.js

@@ -15,23 +15,26 @@ const SOCKET_EVENTS = Object.freeze({
 	CANCEL_TEST: 'cancel-test',
 	LOG: 'log',
 	DONE: 'done',
-	STEP_SCREENSHOT: 'step-screenshot',
 
 	// Multi-lane distributed run (single interactive run, several runners)
 	RUNNER_LANES_INIT: 'runner-lanes-init',
 	RUNNER_LANE_LOG: 'runner-lane-log',
 	RUNNER_LANE_STATUS: 'runner-lane-status',
-	RUNNER_LANE_SCREENSHOT: 'runner-lane-screenshot',
 
 	// Background runs (cron / REST / MCP triggered, no single owning socket)
 	BG_RUN_START: 'bg-run-start',
 	BG_RUN_LOG: 'bg-run-log',
 	BG_RUN_DONE: 'bg-run-done',
-	BG_RUN_SCREENSHOT: 'bg-run-screenshot',
 	BG_RUN_LANES_INIT: 'bg-run-lanes-init',
 	BG_RUN_LANE_LOG: 'bg-run-lane-log',
 	BG_RUN_LANE_STATUS: 'bg-run-lane-status',
-	BG_RUN_LANE_SCREENSHOT: 'bg-run-lane-screenshot',
+
+	// Live rrweb streaming — one shape for every run type, always
+	// carrying a lane id (BUILT_IN_RUNNER_ID for the plain single-run case) and
+	// a workerId, so a single built-in run with --parallel workers is finally
+	// attributable per worker instead of one flat interleaved stream.
+	RUNNER_LANE_RRWEB_BATCH: 'runner-lane-rrweb-batch',
+	BG_RUN_LANE_RRWEB_BATCH: 'bg-run-lane-rrweb-batch',
 
 	// Global notifications (any client, not tied to a specific run)
 	REPORT_READY: 'report-ready'

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/backend/lib/reportFilename.js

@@ -7,7 +7,6 @@ const path = require('path');
 const fs = require('fs');
 
 const REPORTS_DIR = path.resolve(process.cwd(), 'reports');
-const SCREENSHOTS_DIR = path.join(REPORTS_DIR, 'screenshots');
 
 /**
  * Reads the transient cucumber_report.json written by the most recent local test run.
@@ -22,4 +21,4 @@ function readCucumberReportFile() {
 	}
 }
 
-module.exports = { REPORTS_DIR, SCREENSHOTS_DIR, readCucumberReportFile };
+module.exports = { REPORTS_DIR, readCucumberReportFile };

package/backend/lib/{screenshotPoller.js → rrwebPoller.js}

@@ -6,20 +6,23 @@
 const fs = require('fs');
 const path = require('path');
 
-function startSsPoller(ssDir, onScreenshot) {
+// The test process runs several levels below whatever calls this, with no
+// direct pipe back, so rrweb batches live-stream by small files dropped and
+// picked up here.
+function startRRwebPoller(ssDir, onRRwebBatch) {
 	const seenFiles = new Set();
 	return setInterval(() => {
 		try {
 			const files = fs
 				.readdirSync(ssDir)
-				.filter((f) => f.endsWith('.ss.json'))
+				.filter((f) => f.endsWith('.rrweb.json'))
 				.sort();
 			for (const f of files) {
 				if (seenFiles.has(f)) continue;
 				seenFiles.add(f);
 				const filePath = path.join(ssDir, f);
 				const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-				onScreenshot(data);
+				onRRwebBatch?.(data);
 				try {
 					fs.unlinkSync(filePath);
 				} catch {}
@@ -28,4 +31,4 @@ function startSsPoller(ssDir, onScreenshot) {
 	}, 400);
 }
 
-module.exports = { startSsPoller };
+module.exports = { startRRwebPoller };

package/backend/lib/serverBootstrap.js

@@ -43,10 +43,12 @@ function wireRealtimeServices(io, isNodeMode) {
 	if (isNodeMode) return { cronService: null, backupCronService: null };
 
 	const socketHandler = require('../websockets/socketHandler.js');
+	const nodeSocketHandler = require('../websockets/nodeSocketHandler.js');
 	const cronService = require('../services/cronService');
 	const backupCronService = require('../services/backupCronService');
 
 	socketHandler(io);
+	nodeSocketHandler(io);
 	cronService.setSocketIO(io);
 	require('../routes/trigger.routes').setSocketIO(io);
 
@@ -125,6 +127,7 @@ function handleNodeModeStartup(port) {
 
 async function handleFullModeStartup(io, testsDir) {
 	syncAutomatedFlags();
+	cleanupLegacyScreenshots();
 
 	const chokidar = await loadChokidar();
 	if (!chokidar) return;
@@ -133,6 +136,17 @@ async function handleFullModeStartup(io, testsDir) {
 	watchReports(chokidar, io);
 }
 
+// Report rows no longer reference screenshot files (replaced by rrweb
+// recordings), so any leftover files on disk are dead weight. Safe to run
+// every startup: a second pass on an already-gone directory is a no-op.
+function cleanupLegacyScreenshots() {
+	const screenshotsDir = path.join(process.cwd(), 'reports', 'screenshots');
+	if (!fs.existsSync(screenshotsDir)) return;
+	fs.rm(screenshotsDir, { recursive: true, force: true }, (err) => {
+		if (!err) console.log('🧹 Removed legacy screenshots directory');
+	});
+}
+
 function syncAutomatedFlags() {
 	// Sync automated flags from feature files on every startup
 	require('../services/reportService')

package/backend/logs/runner-cmtbz5b1l0000mr0110b27w5k.log

@@ -0,0 +1,8 @@
+/*
+This file is part of Plum.
+Licensed under the MIT License. See LICENSE file in the project root for details.
+*/
+📂 Loading tests from: /Users/silverlunah/Projects/plum/backend/tests
+Backend running on port 3099 (node/runner mode)
+(node:10858) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
+(Use `node --trace-deprecation ...` to show where the warning was created)