plum-e2e 1.3.1 → 1.3.3

package/backend/lib/serverConfig.js

@@ -0,0 +1,112 @@
+/*
+ * 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/.
+ */
+
+/**
+ * Source-of-truth config for the `plum server` flow. `.env` and the generated
+ * docker-compose override are derived from this file, so reconfiguring URLs and
+ * ports happens in one place.
+ *
+ * Uses only Node builtins so it can be imported from the published `bin/plum.js`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { detectLanIp } = require('./nodeRegister');
+
+const CONFIG_FILENAME = '.plum-server.json';
+
+function defaults() {
+	const backendPort = '3001';
+	return {
+		baseUrl: 'https://www.saucedemo.com/v1/',
+		headless: false,
+		backendPort,
+		frontendPort: '5173',
+		primaryPublicUrl: `http://${detectLanIp()}:${backendPort}`
+	};
+}
+
+function configPath(dir) {
+	return path.join(dir, CONFIG_FILENAME);
+}
+
+/** Seeds baseUrl/headless from an existing .env so first-run prompts reflect it. */
+function readEnvSeed(dir) {
+	try {
+		const txt = fs.readFileSync(path.join(dir, '.env'), 'utf8');
+		const seed = {};
+		const baseUrl = txt.match(/^BASE_URL=(.*)$/m);
+		if (baseUrl) seed.baseUrl = baseUrl[1].trim();
+		const headless = txt.match(/^IS_HEADLESS=(.*)$/m);
+		if (headless) seed.headless = headless[1].trim() === 'true';
+		return seed;
+	} catch {
+		return {};
+	}
+}
+
+function loadServerConfig(dir) {
+	const base = { ...defaults(), ...readEnvSeed(dir) };
+	try {
+		return { ...base, ...JSON.parse(fs.readFileSync(configPath(dir), 'utf8')) };
+	} catch {
+		return base;
+	}
+}
+
+function saveServerConfig(dir, cfg) {
+	fs.writeFileSync(configPath(dir), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+
+/** Writes the root .env consumed by the backend/tests from the server config. */
+function writeEnvFile(dir, { baseUrl, headless }) {
+	const content = `BASE_URL=${baseUrl}\nIS_HEADLESS=${headless ? 'true' : 'false'}\n`;
+	fs.writeFileSync(path.join(dir, '.env'), content, 'utf8');
+}
+
+/**
+ * Builds docker-compose.override.yml. Containers keep their internal ports
+ * (3001/5173); only the host side is remapped. The frontend is told where to
+ * reach the backend via VITE_API_URL (read by Vite at dev runtime).
+ */
+function buildOverrideYaml({ testsAbs, reportsAbs, backendPort, frontendPort }) {
+	return (
+		[
+			'services:',
+			'  backend:',
+			'    ports:',
+			`      - "${backendPort}:3001"`,
+			'    volumes:',
+			`      - "${reportsAbs}:/app/reports"`,
+			`      - "${testsAbs}:/app/tests"`,
+			'  frontend:',
+			'    ports:',
+			`      - "${frontendPort}:5173"`,
+			'    environment:',
+			`      VITE_API_URL: "http://localhost:${backendPort}"`
+		].join('\n') + '\n'
+	);
+}
+
+module.exports = {
+	CONFIG_FILENAME,
+	defaults,
+	loadServerConfig,
+	saveServerConfig,
+	writeEnvFile,
+	buildOverrideYaml
+};

package/backend/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "plum-backend",
-	"version": "1.2.1",
+	"version": "1.3.3",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "plum-backend",
-			"version": "1.2.1",
+			"version": "1.3.3",
 			"license": "ISC",
 			"dependencies": {
 				"@clack/prompts": "^1.5.1",

package/backend/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "plum-backend",
-	"version": "1.3.1",
+	"version": "1.3.3",
 	"main": "index.js",
 	"scripts": {
 		"init": "node services/envService.js",
 		"create-step": "node config/scripts/create-step.mjs",
 		"create-env": "node services/envService.js",
 		"test": "node config/scripts/run-tests.js",
-		"add-local-runner": "node scripts/add-local-runner.js",
+		"manage-runners": "node scripts/manage-runners.mjs",
 		"create-test": "node scripts/create-test.js"
 	},
 	"keywords": [],

package/backend/scripts/manage-runners.mjs

@@ -0,0 +1,297 @@
+/*
+ * 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/.
+ */
+
+/**
+ * Interactive manager for local node runners.
+ *
+ * Registers new runners with the Plum primary and starts / stops / restarts the
+ * node processes that back local runners, all from one menu.
+ *
+ * Usage:  node scripts/manage-runners.mjs
+ *    or:  npm run manage-runners     (from the backend directory)
+ *
+ * Env:    PLUM_API_URL   primary server API base (default http://localhost:3001)
+ */
+
+import * as clack from '@clack/prompts';
+import pc from 'picocolors';
+import runnerProcess from '../lib/runnerProcess.js';
+import nodeRegister from '../lib/nodeRegister.js';
+
+const { isLocalUrl, parsePort, pruneDead, statusOf, prepareEnv, startNode, stopNode } =
+	runnerProcess;
+const { generateToken, registerWithPrimary } = nodeRegister;
+
+const API_URL = process.env.PLUM_API_URL || 'http://localhost:3001';
+
+const cancelled = (v) => clack.isCancel(v);
+
+async function fetchRunners() {
+	const res = await fetch(`${API_URL}/runners`);
+	if (!res.ok) throw new Error(`HTTP ${res.status}`);
+	const body = await res.json();
+	return body.runners ?? [];
+}
+
+async function pingRunner(id) {
+	try {
+		const res = await fetch(`${API_URL}/runners/${id}/ping`, { method: 'POST' });
+		const body = await res.json().catch(() => ({}));
+		return body.ok === true;
+	} catch {
+		return false;
+	}
+}
+
+async function deleteRunner(id) {
+	const res = await fetch(`${API_URL}/runners/${id}`, { method: 'DELETE' });
+	if (!res.ok) {
+		const body = await res.json().catch(() => ({}));
+		throw new Error(body.error || `HTTP ${res.status}`);
+	}
+}
+
+/**
+ * Resolves the display + control state for every runner: reachability (ping),
+ * whether we own a live process for it, and whether we can control it at all.
+ */
+async function describeRunners() {
+	const runners = await fetchRunners();
+	pruneDead();
+
+	return Promise.all(
+		runners.map(async (r) => {
+			const online = await pingRunner(r.id);
+			const local = isLocalUrl(r.url);
+			const managed = statusOf(r.id) === 'running';
+			let state;
+			if (managed) state = 'managed';
+			else if (online) state = 'unmanaged';
+			else state = 'stopped';
+			return { ...r, online, local, managed, state };
+		})
+	);
+}
+
+function statusBadge(r) {
+	const dot = r.online ? pc.green('●') : pc.dim('○');
+	let detail;
+	if (!r.local) detail = pc.dim('remote');
+	else if (r.managed) detail = pc.green('running');
+	else if (r.online) detail = pc.yellow('running (unmanaged)');
+	else detail = pc.dim('stopped');
+	return `${dot} ${detail}`;
+}
+
+/**
+ * Installs backend deps + the Playwright browser so a freshly started node can
+ * actually launch a browser. Runs with inherited stdio (outside any spinner) so
+ * npm/playwright progress is visible. A failure is surfaced but non-fatal — the
+ * operator can retry or fix it manually.
+ */
+function prepareNodeEnv(browser) {
+	clack.log.step(`Preparing node environment (deps + ${browser ?? 'browser'})...`);
+	try {
+		prepareEnv(browser);
+		clack.log.success(pc.green('Environment ready.'));
+		return true;
+	} catch (e) {
+		clack.log.warn(pc.yellow(`Environment prep failed: ${e.message}`));
+		return false;
+	}
+}
+
+async function runAction(r) {
+	const options = [];
+
+	if (!r.local) {
+		clack.log.info(
+			pc.dim(`"${r.name}" runs on another machine — it can be pinged but not controlled here.`)
+		);
+		options.push({ value: 'ping', label: 'Ping' });
+	} else if (r.managed) {
+		options.push(
+			{ value: 'stop', label: pc.red('Stop') },
+			{ value: 'restart', label: pc.yellow('Restart') },
+			{ value: 'log', label: 'Show log path' },
+			{ value: 'ping', label: 'Ping' }
+		);
+	} else if (r.online) {
+		clack.log.info(
+			pc.dim(
+				`"${r.name}" is up but was not started by this manager — stop it from its own terminal.`
+			)
+		);
+		options.push({ value: 'ping', label: 'Ping' });
+	} else {
+		options.push({ value: 'start', label: pc.green('Start') }, { value: 'ping', label: 'Ping' });
+	}
+
+	options.push(
+		{ value: 'delete', label: pc.red('Delete') },
+		{ value: 'back', label: pc.dim('← Back') }
+	);
+
+	const action = await clack.select({ message: `${r.name} — ${r.url}`, options });
+	if (cancelled(action) || action === 'back') return;
+
+	const port = parsePort(r.url);
+
+	if (action === 'start') {
+		prepareNodeEnv(r.browser);
+		const entry = startNode({ id: r.id, port, token: r.token });
+		clack.log.success(pc.green(`Started "${r.name}" on port ${port} (pid ${entry.pid})`));
+	} else if (action === 'stop') {
+		const ok = stopNode(r.id);
+		clack.log.success(ok ? pc.green(`Stopped "${r.name}"`) : pc.dim(`"${r.name}" was not running`));
+	} else if (action === 'restart') {
+		const s = clack.spinner();
+		s.start(`Restarting "${r.name}"...`);
+		stopNode(r.id);
+		await new Promise((resolve) => setTimeout(resolve, 600));
+		const entry = startNode({ id: r.id, port, token: r.token });
+		s.stop(pc.green(`Restarted "${r.name}" (pid ${entry.pid})`));
+	} else if (action === 'log') {
+		const entry = runnerProcess.loadRegistry()[r.id];
+		clack.note(entry?.logFile ?? '(no log file)', 'Log file');
+	} else if (action === 'ping') {
+		const s = clack.spinner();
+		s.start(`Pinging "${r.name}"...`);
+		const online = await pingRunner(r.id);
+		s.stop(online ? pc.green(`"${r.name}" is reachable`) : pc.red(`"${r.name}" is unreachable`));
+	} else if (action === 'delete') {
+		const confirmed = await clack.confirm({
+			message: `Delete runner "${r.name}"? This removes it from the server.`,
+			initialValue: false
+		});
+		if (cancelled(confirmed) || !confirmed) return;
+		const s = clack.spinner();
+		s.start(`Deleting "${r.name}"...`);
+		if (r.managed) stopNode(r.id);
+		try {
+			await deleteRunner(r.id);
+			s.stop(pc.green(`Deleted "${r.name}"`));
+		} catch (e) {
+			s.stop(pc.red(`Could not delete "${r.name}": ${e.message}`));
+		}
+	}
+}
+
+async function addRunner() {
+	const suggested = `node-${generateToken().slice(0, 6)}`;
+
+	const name = await clack.text({ message: 'Runner name', placeholder: suggested, defaultValue: suggested });
+	if (cancelled(name)) return;
+
+	const port = await clack.text({
+		message: 'Local port the node listens on',
+		placeholder: '3002',
+		defaultValue: '3002'
+	});
+	if (cancelled(port)) return;
+
+	const browser = await clack.select({
+		message: 'Default browser',
+		options: [
+			{ value: 'chromium', label: 'Chrome' },
+			{ value: 'firefox', label: 'Firefox' },
+			{ value: 'webkit', label: 'WebKit' }
+		],
+		initialValue: 'chromium'
+	});
+	if (cancelled(browser)) return;
+
+	const defToken = process.env.NODE_TOKEN || generateToken();
+	const token = await clack.text({ message: 'Auth token', placeholder: defToken, defaultValue: defToken });
+	if (cancelled(token)) return;
+
+	// Dev nodes run as a bare process on the host; the dockerized primary reaches
+	// them via host.docker.internal.
+	const url = `http://host.docker.internal:${port}`;
+
+	const s = clack.spinner();
+	s.start(`Registering "${name}" with the primary...`);
+	let id;
+	try {
+		const res = await registerWithPrimary({ primary: API_URL, name, url, token, browser });
+		id = res.id;
+		s.stop(res.reused ? pc.green(`Reusing existing runner "${name}"`) : pc.green(`Registered "${name}" (id ${id})`));
+	} catch (e) {
+		s.stop(pc.red(`Could not register "${name}": ${e.message}`));
+		return;
+	}
+
+	prepareNodeEnv(browser);
+
+	const startNow = await clack.confirm({ message: 'Start this runner now?' });
+	if (!cancelled(startNow) && startNow) {
+		const entry = startNode({ id, port, token });
+		clack.log.success(pc.green(`Started "${name}" on port ${port} (pid ${entry.pid})`));
+	}
+}
+
+async function main() {
+	clack.intro(pc.bgMagenta(pc.white('  🟣 Plum — Manage Runners  ')));
+
+	for (;;) {
+		const s = clack.spinner();
+		s.start(`Loading runners from ${API_URL}...`);
+		let runners;
+		try {
+			runners = await describeRunners();
+			s.stop(`Runners at ${API_URL}`);
+		} catch (e) {
+			s.stop(pc.red(`Could not reach Plum server at ${API_URL}`));
+			clack.log.error(e.message);
+			clack.outro(pc.dim('Is the primary server running? (docker compose up -d)'));
+			process.exit(1);
+		}
+
+		if (runners.length === 0) clack.log.info(pc.dim('No runners registered yet.'));
+
+		const choice = await clack.select({
+			message: runners.length ? 'Select a runner' : 'No runners yet',
+			options: [
+				...runners.map((r) => ({
+					value: r.id,
+					label: r.name,
+					hint: statusBadge(r)
+				})),
+				{ value: '__add__', label: pc.green('+ Add new runner') },
+				{ value: '__refresh__', label: pc.cyan('↻ Refresh') },
+				{ value: '__quit__', label: pc.dim('Quit') }
+			]
+		});
+
+		if (cancelled(choice) || choice === '__quit__') break;
+		if (choice === '__refresh__') continue;
+		if (choice === '__add__') {
+			await addRunner();
+			continue;
+		}
+
+		const runner = runners.find((r) => r.id === choice);
+		if (runner) await runAction(runner);
+	}
+
+	clack.outro(pc.magenta('Done.'));
+}
+
+main().catch((err) => {
+	clack.log.error(err.message);
+	process.exit(1);
+});

package/backend/server.js

@@ -18,8 +18,6 @@
 const http = require('http');
 const { Server } = require('socket.io');
 const app = require('./app');
-const socketHandler = require('./websockets/socketHandler.js');
-const cronService = require('./services/cronService');
 const server = http.createServer(app);
 const io = new Server(server, { cors: { origin: '*' } });
 const path = require('path');
@@ -42,11 +40,16 @@ if (!fs.existsSync(testsDir)) {
 const isNodeMode = process.env.PLUM_MODE === 'node';
 const port = parseInt(process.env.PORT || '3001', 10);
 
-socketHandler(io);
-if (!isNodeMode) cronService.setSocketIO(io);
+let cronService = null;
+if (!isNodeMode) {
+	const socketHandler = require('./websockets/socketHandler.js');
+	cronService = require('./services/cronService');
+	socketHandler(io);
+	cronService.setSocketIO(io);
+}
 
 async function start() {
-	if (!isNodeMode) await cronService.init();
+	if (cronService) await cronService.init();
 
 	server.listen(port, async () => {
 		console.log(`Backend running on port ${port}${isNodeMode ? ' (node/runner mode)' : ''}`);

package/backend/services/reportService.js

@@ -48,6 +48,18 @@ function collectScreenshotFiles(content) {
 	return files;
 }
 
+/**
+ * Stable identity for a Cucumber feature across distributed lanes. Dispatched
+ * runs report an absolute temp uri (…/plum-job-<uuid>/features/Login.feature)
+ * that differs per runner; the suffix from `features/` onward is stable.
+ */
+function featureMergeKey(feature) {
+	const uri = (feature.uri ?? '').replace(/\\/g, '/');
+	const idx = uri.lastIndexOf('/features/');
+	if (idx !== -1) return uri.slice(idx + 1);
+	return uri || feature.id || feature.name;
+}
+
 function deleteScreenshotFiles(content) {
 	for (const file of collectScreenshotFiles(content)) {
 		const p = path.join(SCREENSHOTS_DIR, file);
@@ -249,7 +261,11 @@ const saveCombinedReport = async ({ reports, runners, overallCode, tag, triggerT
 			continue;
 		}
 		for (const feature of parsed) {
-			const key = feature.uri ?? feature.id ?? feature.name;
+			// Each lane runs from its own temp dir, so the same feature reports a
+			// different absolute uri per runner. Key on the path from `features/`
+			// onward (falling back to name) so one feature's scenarios from every
+			// lane merge into a single entry instead of one duplicate per runner.
+			const key = featureMergeKey(feature);
 			if (featureMap.has(key)) {
 				featureMap.get(key).elements.push(...(feature.elements ?? []));
 			} else {

package/backend/services/runnerService.js

@@ -113,10 +113,20 @@ async function fetchReportContent(runner, jobId, onLog) {
  * @param {(exitCode: number, reportContent: string|null) => void} onDone
  */
 async function dispatchAndPoll(runnerId, { tags, browser, workers }, onLog, onDone) {
+	// The async poll callback can overlap if a tick takes longer than the interval;
+	// guard so the run resolves exactly once and can't be finalised while a lane
+	// is still in flight.
+	let settled = false;
+	const finish = (code, content) => {
+		if (settled) return;
+		settled = true;
+		onDone(code, content);
+	};
+
 	const runner = await getById(runnerId);
 	if (!runner) {
 		onLog(`[ERROR] Runner ${runnerId} not found\n`);
-		onDone(1, null);
+		finish(1, null);
 		return;
 	}
 
@@ -135,14 +145,17 @@ async function dispatchAndPoll(runnerId, { tags, browser, workers }, onLog, onDo
 		jobId = (await res.json()).jobId;
 	} catch (e) {
 		onLog(`[ERROR] Could not reach runner "${runner.name}": ${e.message}\n`);
-		onDone(1, null);
+		finish(1, null);
 		return;
 	}
 
 	onLog(`Connected to runner "${runner.name}" — job ${jobId}\n`);
 
 	let logOffset = 0;
+	let polling = false;
 	const poll = setInterval(async () => {
+		if (polling) return;
+		polling = true;
 		try {
 			const res = await fetch(`${runner.url}/api/execute/${jobId}?offset=${logOffset}`, {
 				headers: { Authorization: `Bearer ${runner.token}` },
@@ -159,10 +172,12 @@ async function dispatchAndPoll(runnerId, { tags, browser, workers }, onLog, onDo
 			if (body.status === 'done' || body.status === 'error') {
 				clearInterval(poll);
 				const content = await fetchReportContent(runner, jobId, onLog);
-				onDone(body.exitCode ?? (body.status === 'done' ? 0 : 1), content);
+				finish(body.exitCode ?? (body.status === 'done' ? 0 : 1), content);
 			}
 		} catch {
 			// transient polling error — keep trying
+		} finally {
+			polling = false;
 		}
 	}, 2500);
 }

package/backend/websockets/socketHandler.js

@@ -46,6 +46,18 @@ const socketHandler = (io) => {
 						: [BUILT_IN_RUNNER_ID];
 			}
 
+			// 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 = [];
+			for (const id of runners) {
+				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`);
+				}
+			}
+			runners = validatedRunners.length > 0 ? validatedRunners : [BUILT_IN_RUNNER_ID];
+
 			const isSingleBuiltIn = runners.length === 1 && runners[0] === BUILT_IN_RUNNER_ID;
 
 			if (isSingleBuiltIn) {
@@ -132,7 +144,6 @@ async function runDistributed(io, socket, activeProcs, tag, workers, browser, ru
 
 		if (doneCount === total) {
 			socket.emit('log', `\nAll runners finished (exit ${overallCode})`);
-			socket.emit('done', overallCode);
 
 			reportService
 				.saveCombinedReport({
@@ -143,8 +154,17 @@ async function runDistributed(io, socket, activeProcs, tag, workers, browser, ru
 					triggerType: TRIGGER_TYPE.MANUAL,
 					browser
 				})
-				.then(() => io.emit('report-ready'))
-				.catch((e) => console.error('[runner] Failed to save combined report:', e.message));
+				.then((saved) => {
+					// 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');
+				})
+				.catch((e) => {
+					console.error('[runner] Failed to save combined report:', e.message);
+					socket.emit('done', { code: overallCode, reportId: null });
+				});
 		}
 	}