plum-e2e 2.6.8 → 2.7.1

package/backend/websockets/socketHandler.js

@@ -1,31 +1,25 @@
 /*
  * 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/.
+ * Licensed under the MIT License. See LICENSE file in the project root for details.
  */
 
 const { spawn } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { randomUUID } = require('crypto');
 const runnerService = require('../services/runnerService');
 const reportService = require('../services/reportService');
 const settingsService = require('../services/settingsService');
 const notificationService = require('../services/notificationService');
+const activeRunsService = require('../services/activeRunsService');
 const { startSsPoller } = require('../lib/screenshotPoller');
 const { runWithRetries } = require('../lib/retryRunner');
 const { TRIGGER_TYPE, BUILT_IN_RUNNER_ID, TRIGGER_REMOTE } = require('../constants/triggers');
+const { DEFAULT_BROWSER } = require('../constants/defaults');
+const { PLUM_MODE_NODE } = require('../constants/env');
+const { SOCKET_EVENTS } = require('../constants/socketEvents');
+const { JOB_STATUS, REPORT_STATUS } = require('../constants/jobStatus');
 const { getTestIdsForTag, chunkTests, buildTagExpression } = require('../lib/testChunker');
 const { readCucumberReportFile } = require('../lib/reportFilename');
 const { getTestSuites } = require('../services/testService');
@@ -37,21 +31,34 @@ const socketHandler = (io) => {
 
 		// Track processes spawned for this socket connection so we can cancel them
 		const activeProcs = new Set();
+		// The in-progress manual run's id started from this connection, if any — used so
+		// 'cancel-test' can unregister/broadcast without a second run-id handshake.
+		let currentManualRunId = null;
 
-		socket.on('run-test', async (payload, legacyWorkers) => {
-			let tag, workers, browser, runners, testRunId, notifyDiscord, notifySlack;
+		socket.on(SOCKET_EVENTS.RUN_TEST, async (payload, legacyWorkers) => {
+			let tag,
+				workers,
+				browser,
+				runners,
+				testRunId,
+				notifyDiscord,
+				notifySlack,
+				runTitle,
+				startedBy;
 			if (typeof payload === 'string') {
 				tag = payload;
 				workers = Number(legacyWorkers) > 1 ? Number(legacyWorkers) : 1;
-				browser = 'chromium';
+				browser = DEFAULT_BROWSER;
 				runners = [BUILT_IN_RUNNER_ID];
 				testRunId = null;
 				notifyDiscord = false;
 				notifySlack = false;
+				runTitle = null;
+				startedBy = null;
 			} else {
 				tag = payload.tag ?? '';
 				workers = Number(payload.workers) > 1 ? Number(payload.workers) : 1;
-				browser = payload.browser ?? 'chromium';
+				browser = payload.browser ?? DEFAULT_BROWSER;
 				runners =
 					Array.isArray(payload.runners) && payload.runners.length > 0
 						? payload.runners
@@ -59,8 +66,25 @@ const socketHandler = (io) => {
 				testRunId = payload.testRunId ?? null;
 				notifyDiscord = payload.notifyDiscord === true;
 				notifySlack = payload.notifySlack === true;
+				runTitle = payload.runTitle ?? null;
+				startedBy = payload.startedBy ?? null;
 			}
 
+			const runId = randomUUID();
+			const label = runTitle || tag || 'Manual run';
+			const meta = { tag, workers, browser, startedBy };
+			activeRunsService.registerRun(runId, { kind: TRIGGER_TYPE.MANUAL, label, meta });
+			currentManualRunId = runId;
+			// Broadcast to every OTHER connected client so coworkers see this run live —
+			// the initiating tab already has full detail via its own runnerState/socket.emit
+			// events below, so it's deliberately excluded to avoid a duplicate bottom-bar entry.
+			socket.broadcast.emit(SOCKET_EVENTS.BG_RUN_START, {
+				runId,
+				kind: TRIGGER_TYPE.MANUAL,
+				label,
+				meta
+			});
+
 			// Drop runner ids that no longer exist (e.g. a deleted runner still
 			// referenced by a stale client selection) so they can't wedge the run.
 			const validatedRunners = [];
@@ -68,7 +92,7 @@ const socketHandler = (io) => {
 				if (id === BUILT_IN_RUNNER_ID || (await runnerService.getById(id))) {
 					validatedRunners.push(id);
 				} else {
-					socket.emit('log', `[WARN] Runner ${id} no longer exists — skipping.\n`);
+					socket.emit(SOCKET_EVENTS.LOG, `[WARN] Runner ${id} no longer exists — skipping.\n`);
 				}
 			}
 			runners = validatedRunners.length > 0 ? validatedRunners : [BUILT_IN_RUNNER_ID];
@@ -85,7 +109,8 @@ const socketHandler = (io) => {
 					browser,
 					testRunId,
 					notifyDiscord,
-					notifySlack
+					notifySlack,
+					runId
 				);
 			} else {
 				runDistributed(
@@ -98,12 +123,13 @@ const socketHandler = (io) => {
 					runners,
 					testRunId,
 					notifyDiscord,
-					notifySlack
+					notifySlack,
+					runId
 				);
 			}
 		});
 
-		socket.on('cancel-test', () => {
+		socket.on(SOCKET_EVENTS.CANCEL_TEST, () => {
 			if (activeProcs.size === 0) return;
 			for (const proc of activeProcs) {
 				try {
@@ -111,8 +137,12 @@ const socketHandler = (io) => {
 				} catch {}
 			}
 			activeProcs.clear();
-			socket.emit('log', '\n[CANCELLED] Test run cancelled by user.\n');
-			socket.emit('done', 130);
+			socket.emit(SOCKET_EVENTS.LOG, '\n[CANCELLED] Test run cancelled by user.\n');
+			socket.emit(SOCKET_EVENTS.DONE, 130);
+			if (currentManualRunId) {
+				finishManualRun(socket, currentManualRunId, 130);
+				currentManualRunId = null;
+			}
 		});
 	});
 };
@@ -121,6 +151,14 @@ const socketHandler = (io) => {
 // Helpers
 // ---------------------------------------------------------------------------
 
+function finishManualRun(socket, runId, code, reportId) {
+	// unregisterRun returns false if this runId was already unregistered (e.g. a cancel
+	// already fired) — skip the broadcast so a cancelled-then-still-completing run doesn't
+	// send two conflicting bg-run-done events to every other connected client.
+	if (!activeRunsService.unregisterRun(runId)) return;
+	socket.broadcast.emit(SOCKET_EVENTS.BG_RUN_DONE, { runId, code, reportId: reportId ?? null });
+}
+
 function makeSyntheticFailReport(laneName, testIds, reason) {
 	// Build id → scenario title from local feature files so names match the real report.
 	const nameMap = {};
@@ -200,13 +238,13 @@ function runBuiltInAttempt({
 		};
 		if (workers > 1) env.PARALLEL = String(workers);
 		if (testRunId) env.TEST_RUN_ID = testRunId;
-		if (suppressSave) env.PLUM_MODE = 'node';
+		if (suppressSave) env.PLUM_MODE = PLUM_MODE_NODE;
 
 		const proc = spawn('npm', ['run', 'test'], { env, shell: true });
 		activeProcs.add(proc);
 
 		const ssPoller = startSsPoller(ssDir, ({ stepName, data }) => {
-			socket.emit('step-screenshot', { stepName, data });
+			socket.emit(SOCKET_EVENTS.STEP_SCREENSHOT, { stepName, data });
 		});
 
 		proc.stdout.on('data', (d) => onLog(d.toString()));
@@ -230,7 +268,8 @@ async function runBuiltIn(
 	browser,
 	testRunId,
 	notifyDiscord,
-	notifySlack
+	notifySlack,
+	runId
 ) {
 	const startedAt = Date.now();
 	const { maxRetries } = await settingsService.getProject();
@@ -238,7 +277,7 @@ async function runBuiltIn(
 	let logBuffer = '';
 	const onLog = (text) => {
 		logBuffer += text;
-		socket.emit('log', text);
+		socket.emit(SOCKET_EVENTS.LOG, text);
 	};
 
 	if (maxRetries === 0) {
@@ -252,9 +291,10 @@ async function runBuiltIn(
 			suppressSave: false,
 			onLog
 		});
-		socket.emit('log', `\nTest finished with code ${code}`);
-		socket.emit('done', code);
-		io.emit('report-ready');
+		socket.emit(SOCKET_EVENTS.LOG, `\nTest finished with code ${code}`);
+		socket.emit(SOCKET_EVENTS.DONE, code);
+		io.emit(SOCKET_EVENTS.REPORT_READY);
+		finishManualRun(socket, runId, code, null);
 
 		// Attach accumulated logs to the report generate-report.js just saved
 		try {
@@ -316,7 +356,7 @@ async function runBuiltIn(
 		onLog
 	});
 
-	socket.emit('log', `\nTest finished with code ${code}`);
+	socket.emit(SOCKET_EVENTS.LOG, `\nTest finished with code ${code}`);
 
 	const report = await reportService.saveReport({
 		rawCucumberJson: rawJson,
@@ -329,8 +369,9 @@ async function runBuiltIn(
 		attempts
 	});
 
-	socket.emit('done', code);
-	io.emit('report-ready');
+	socket.emit(SOCKET_EVENTS.DONE, code);
+	io.emit(SOCKET_EVENTS.REPORT_READY);
+	finishManualRun(socket, runId, code, report.id);
 
 	if (notifyDiscord || notifySlack) {
 		notificationService
@@ -362,7 +403,8 @@ async function runDistributed(
 	runnerIds,
 	testRunId,
 	notifyDiscord,
-	notifySlack
+	notifySlack,
+	runId
 ) {
 	const dispatchStartedAt = Date.now();
 	const { maxRetries } = await settingsService.getProject();
@@ -374,15 +416,16 @@ async function runDistributed(
 	const activeRunnerIds = runnerIds.slice(0, chunks.length);
 
 	if (activeRunnerIds.length === 0) {
-		socket.emit('log', '\nNo tests found matching the selected tag.\n');
-		socket.emit('done', 0);
+		socket.emit(SOCKET_EVENTS.LOG, '\nNo tests found matching the selected tag.\n');
+		socket.emit(SOCKET_EVENTS.DONE, 0);
+		finishManualRun(socket, runId, 0, null);
 		return;
 	}
 
 	if (activeRunnerIds.length < runnerIds.length) {
 		const skipped = runnerIds.length - activeRunnerIds.length;
 		socket.emit(
-			'log',
+			SOCKET_EVENTS.LOG,
 			`[INFO] ${skipped} runner(s) not used — fewer tests than runners selected.\n`
 		);
 	}
@@ -396,7 +439,7 @@ async function runDistributed(
 	);
 
 	socket.emit(
-		'runner-lanes-init',
+		SOCKET_EVENTS.RUNNER_LANES_INIT,
 		laneInfos.map((l, i) => ({ id: l.id, name: l.name, testCount: chunks[i].length }))
 	);
 
@@ -412,11 +455,14 @@ async function runDistributed(
 		if (code !== 0) overallCode = code;
 		collectedReports[idx] = reportContent;
 		laneAttempts[idx] = attempts;
-		socket.emit('runner-lane-status', { id: laneId, status: code === 0 ? 'done' : 'error' });
+		socket.emit(SOCKET_EVENTS.RUNNER_LANE_STATUS, {
+			id: laneId,
+			status: code === 0 ? JOB_STATUS.DONE : JOB_STATUS.ERROR
+		});
 		doneCount++;
 
 		if (doneCount === total) {
-			socket.emit('log', `\nAll runners finished (exit ${overallCode})`);
+			socket.emit(SOCKET_EVENTS.LOG, `\nAll runners finished (exit ${overallCode})`);
 
 			reportService
 				.saveCombinedReport({
@@ -435,8 +481,12 @@ async function runDistributed(
 					// Result is authoritative from the merged report, not the exit code —
 					// a node's non-test failure (e.g. a failed report fetch) must not flip
 					// a passing run to "fail" in the live UI.
-					socket.emit('done', { code: saved.status === 'PASS' ? 0 : 1, reportId: saved.id });
-					io.emit('report-ready');
+					socket.emit(SOCKET_EVENTS.DONE, {
+						code: saved.status === REPORT_STATUS.PASS ? 0 : 1,
+						reportId: saved.id
+					});
+					io.emit(SOCKET_EVENTS.REPORT_READY);
+					finishManualRun(socket, runId, saved.status === REPORT_STATUS.PASS ? 0 : 1, saved.id);
 
 					if (notifyDiscord || notifySlack) {
 						notificationService
@@ -455,7 +505,8 @@ async function runDistributed(
 				})
 				.catch((e) => {
 					console.error('[runner] Failed to save combined report:', e.message);
-					socket.emit('done', { code: overallCode, reportId: null });
+					socket.emit(SOCKET_EVENTS.DONE, { code: overallCode, reportId: null });
+					finishManualRun(socket, runId, overallCode, null);
 				});
 		}
 	}
@@ -470,7 +521,7 @@ async function runDistributed(
 			const laneId = lane.id;
 			const onLog = (text) => {
 				laneLogs[laneId] += text;
-				socket.emit('runner-lane-log', { id: laneId, log: text });
+				socket.emit(SOCKET_EVENTS.RUNNER_LANE_LOG, { id: laneId, log: text });
 			};
 
 			const spawnBuiltInLaneAttempt = (currentTag) =>
@@ -484,7 +535,7 @@ async function runDistributed(
 						TRIGGER: TRIGGER_REMOTE,
 						BROWSER: browser,
 						REPORT_RUNNERS: String(workers),
-						PLUM_MODE: 'node',
+						PLUM_MODE: PLUM_MODE_NODE,
 						PLUM_SS_DIR: ssDir
 					};
 					if (workers > 1) env.PARALLEL = String(workers);
@@ -493,7 +544,7 @@ async function runDistributed(
 					activeProcs.add(proc);
 
 					const ssPoller = startSsPoller(ssDir, ({ stepName, data }) => {
-						socket.emit('runner-lane-screenshot', { id: laneId, stepName, data });
+						socket.emit(SOCKET_EVENTS.RUNNER_LANE_SCREENSHOT, { id: laneId, stepName, data });
 					});
 
 					proc.stdout.on('data', (d) => onLog(d.toString()));
@@ -522,7 +573,7 @@ async function runDistributed(
 			const laneId = lane.id;
 			const onLog = (log) => {
 				laneLogs[laneId] += log;
-				socket.emit('runner-lane-log', { id: laneId, log });
+				socket.emit(SOCKET_EVENTS.RUNNER_LANE_LOG, { id: laneId, log });
 			};
 
 			const spawnRemoteLaneAttempt = (currentTag) =>
@@ -538,7 +589,7 @@ async function runDistributed(
 							resolve({ code, rawJson: JSON.parse(raw) });
 						},
 						({ stepName, data }) => {
-							socket.emit('runner-lane-screenshot', { id: laneId, stepName, data });
+							socket.emit(SOCKET_EVENTS.RUNNER_LANE_SCREENSHOT, { id: laneId, stepName, data });
 						}
 					);
 				});

package/bin/plum.js

@@ -1,19 +1,7 @@
 #!/usr/bin/env node
 /*
  * 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/.
+ * Licensed under the MIT License. See LICENSE file in the project root for details.
  */
 
 import { execSync, spawn } from 'child_process';
@@ -1283,6 +1271,19 @@ switch (command) {
 	}
 
 	case 'mcp': {
+		// Claude launches `plum mcp` directly, skipping every other command
+		// (`server start`, `node start`, `run-test`) that would otherwise have
+		// already called ensureBackendDeps/prepareEnv. Without this guard, a
+		// stale/missing backend/node_modules (e.g. after `npm i -g plum-e2e@latest`
+		// wipes it) makes the MCP server fail outright on its own requires.
+		try {
+			const { ensureBackendDeps } = runnerProcessLib();
+			ensureBackendDeps();
+		} catch (e) {
+			console.error(`Could not verify backend dependencies: ${e.message}`);
+			process.exit(1);
+		}
+
 		const mcpScript = path.join(plumRoot, 'backend', 'mcp', 'server.js');
 		spawn(process.execPath, [mcpScript], {
 			stdio: 'inherit',

package/bin/postinstall.js

@@ -0,0 +1,34 @@
+/*
+ * This file is part of Plum.
+ * Licensed under the MIT License. See LICENSE file in the project root for details.
+ */
+
+/**
+ * Runs on every `npm install` of this package (including `npm i -g plum-e2e`
+ * and re-installs on update), so `plum mcp` and other backend-dependent
+ * commands work immediately without the user first having to run `plum
+ * server start` or `plum node start` — the only commands that used to trigger
+ * a backend `npm install` on their own.
+ *
+ * Best-effort: a failure here must not fail the overall `npm install`, so
+ * errors are logged, not thrown.
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+try {
+	const { ensureBackendDeps } = require(
+		path.join(__dirname, '..', 'backend', 'lib', 'runnerProcess.js')
+	);
+	ensureBackendDeps();
+} catch (e) {
+	console.warn(`[plum] Could not install backend dependencies automatically: ${e.message}`);
+	console.warn(
+		'[plum] If `plum mcp` fails to start, run `npm install` inside its backend/ folder.'
+	);
+}

package/bin/scaffold-tests.js

@@ -1,18 +1,6 @@
 /*
  * 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/.
+ * Licensed under the MIT License. See LICENSE file in the project root for details.
  */
 
 import fs from 'fs';

package/docker-compose.node.yml

@@ -1,18 +1,6 @@
 #
 # 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/.
+# Licensed under the MIT License. See LICENSE file in the project root for details.
 #
 
 # Runner node — backend + postgres only, no frontend UI.

package/docker-compose.yml

@@ -1,18 +1,6 @@
 #
 # 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/.
+# Licensed under the MIT License. See LICENSE file in the project root for details.
 #
 
 services: