plum-e2e 2.3.0 → 2.4.0

package/README.md

@@ -78,21 +78,21 @@ 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 (alias: `plum start`) |
-| `plum server stop`            | Stop the server and preserve data (alias: `plum stop`)   |
-| `plum server reconfig`        | Re-enter server settings without starting                |
-| `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 create-step`            | Interactively scaffold a new step definition             |
-| `plum node start`             | Configure, register, and start a runner node             |
-| `plum node stop`              | Stop the runner node started from this folder            |
-| `plum node reconfig`          | Re-enter node settings and re-register                   |
-| `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 (alias: `plum start`)           |
+| `plum server stop`            | Stop the server and preserve data (alias: `plum stop`)             |
+| `plum server reconfig`        | Re-enter server settings without starting                          |
+| `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 create-step`            | Interactively scaffold a new step definition                       |
+| `plum node start`             | Set up connectivity, start a runner node, and open the runner menu |
+| `plum node stop`              | Stop the runner node started from this folder                      |
+| `plum node reconfig`          | Re-enter node settings and re-register                             |
+| `plum manage-runners`         | Open the interactive runner management menu                        |
 
 ---
 

package/backend/app.js

@@ -44,6 +44,7 @@ if (process.env.PLUM_MODE !== 'node') {
 	app.use('/test-suites', require('./routes/test-suites.routes'));
 	app.use('/test-cases', require('./routes/test-cases.routes'));
 	app.use('/test-runs', require('./routes/test-runs.routes'));
+	app.use('/trigger', require('./routes/trigger.routes'));
 }
 
 module.exports = app;

package/backend/constants/triggers.js

@@ -23,7 +23,8 @@
  */
 const TRIGGER_TYPE = Object.freeze({
 	MANUAL: 'manual-trigger',
-	CLI: 'command-line-trigger'
+	CLI: 'command-line-trigger',
+	MCP: 'mcp-trigger'
 });
 
 /**
@@ -43,6 +44,7 @@ const BUILT_IN_RUNNER_ID = 'built-in';
 const NON_SCHEDULED_TRIGGERS = new Set([
 	TRIGGER_TYPE.MANUAL,
 	TRIGGER_TYPE.CLI,
+	TRIGGER_TYPE.MCP,
 	TRIGGER_REMOTE,
 	'undefined'
 ]);

package/backend/lib/serverConfig.js

@@ -25,18 +25,14 @@
 
 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}`
+		backendPort: '3001',
+		frontendPort: '5173'
 	};
 }
 
@@ -44,13 +40,11 @@ function configPath(dir) {
 	return path.join(dir, CONFIG_FILENAME);
 }
 
-/** Seeds baseUrl/headless from an existing .env so first-run prompts reflect it. */
+/** Seeds headless from an existing .env so the first-run prompt reflects 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;
@@ -69,13 +63,28 @@ function loadServerConfig(dir) {
 }
 
 function saveServerConfig(dir, cfg) {
-	fs.writeFileSync(configPath(dir), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+	const { headless, backendPort, frontendPort } = cfg;
+	fs.writeFileSync(
+		configPath(dir),
+		JSON.stringify({ headless, backendPort, frontendPort }, 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');
+/** Updates IS_HEADLESS in the root .env, preserving all other entries. */
+function writeEnvFile(dir, { headless }) {
+	const envPath = path.join(dir, '.env');
+	let content = '';
+	try {
+		content = fs.readFileSync(envPath, 'utf8');
+	} catch {}
+	const line = `IS_HEADLESS=${headless ? 'true' : 'false'}`;
+	if (/^IS_HEADLESS=/m.test(content)) {
+		content = content.replace(/^IS_HEADLESS=.*/m, line);
+	} else {
+		content = content.endsWith('\n') ? content + line + '\n' : content + '\n' + line + '\n';
+	}
+	fs.writeFileSync(envPath, content, 'utf8');
 }
 
 /**

package/backend/mcp/server.js

@@ -0,0 +1,385 @@
+/*
+ * 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/.
+ */
+
+/**
+ * Plum MCP Server
+ *
+ * Exposes Plum's Test Repository and test runner to Claude over stdio.
+ *
+ * Configuration (env vars):
+ *   PLUM_API_URL   — Plum backend base URL (default: http://localhost:3001)
+ *   PLUM_API_KEY   — Must match PLUM_MCP_KEY set in backend/.env
+ */
+
+const path = require('path');
+
+// Use absolute paths to bypass the SDK's wildcard export mapping
+const sdkCjs = path.resolve(
+	__dirname,
+	'..',
+	'node_modules',
+	'@modelcontextprotocol',
+	'sdk',
+	'dist',
+	'cjs'
+);
+const { McpServer } = require(path.join(sdkCjs, 'server', 'mcp.js'));
+const { StdioServerTransport } = require(path.join(sdkCjs, 'server', 'stdio.js'));
+const { z } = require('zod');
+
+const API_URL = (process.env.PLUM_API_URL || 'http://localhost:3001').replace(/\/$/, '');
+const API_KEY = process.env.PLUM_API_KEY || '';
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function api(method, path, body) {
+	const res = await fetch(`${API_URL}${path}`, {
+		method,
+		headers: {
+			'Content-Type': 'application/json',
+			Authorization: `ApiKey ${API_KEY}`
+		},
+		body: body !== undefined ? JSON.stringify(body) : undefined
+	});
+	const json = await res.json().catch(() => ({}));
+	if (!res.ok) {
+		throw new Error(json.error || `HTTP ${res.status} ${method} ${path}`);
+	}
+	return json;
+}
+
+const get = (path) => api('GET', path);
+const post = (path, body) => api('POST', path, body);
+const put = (path, body) => api('PUT', path, body);
+
+// ---------------------------------------------------------------------------
+// Polling helper for test runs
+// ---------------------------------------------------------------------------
+
+async function pollJob(jobId, { maxMs = 600_000, intervalMs = 5_000 } = {}) {
+	const deadline = Date.now() + maxMs;
+	while (Date.now() < deadline) {
+		await new Promise((r) => setTimeout(r, intervalMs));
+		const job = await get(`/trigger/${jobId}`);
+		if (job.status !== 'running') return job;
+	}
+	return { status: 'timeout', jobId };
+}
+
+// ---------------------------------------------------------------------------
+// Report summary helper
+// ---------------------------------------------------------------------------
+
+function summariseReport(report) {
+	const features = report.content?.features ?? [];
+	const allScenarios = features.flatMap((f) => f.scenarios ?? []);
+	const total = allScenarios.length;
+	const passed = allScenarios.filter((s) => s.status === 'passed').length;
+	const failed = allScenarios.filter((s) => s.status === 'failed').length;
+
+	const failedDetails = allScenarios
+		.filter((s) => s.status === 'failed')
+		.map((s) => {
+			const failedStep = (s.steps ?? []).find((st) => st.status === 'failed');
+			return {
+				scenario: s.name,
+				feature: features.find((f) => (f.scenarios ?? []).includes(s))?.name ?? '',
+				failedStep: failedStep?.name ?? '',
+				error: failedStep?.error ?? ''
+			};
+		});
+
+	return {
+		id: report.id,
+		status: report.status,
+		browser: report.browser,
+		tags: report.tags,
+		createdAt: report.createdAt,
+		summary: { total, passed, failed },
+		failures: failedDetails
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Server setup
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+	name: 'plum',
+	version: '1.0.0'
+});
+
+// -- Test Repository: Suites -------------------------------------------------
+
+server.tool(
+	'list_test_suites',
+	'List all test suites in the Plum Test Repository.',
+	{
+		page: z.number().int().positive().optional().describe('Page number (default 1)'),
+		limit: z.number().int().positive().max(100).optional().describe('Results per page (default 20)')
+	},
+	async ({ page = 1, limit = 20 }) => {
+		const data = await get(`/test-suites?page=${page}&limit=${limit}`);
+		return {
+			content: [
+				{
+					type: 'text',
+					text: JSON.stringify(data, null, 2)
+				}
+			]
+		};
+	}
+);
+
+server.tool(
+	'get_test_suite',
+	'Get a test suite by ID, including all its test cases.',
+	{
+		suiteId: z.string().describe('The suite ID (e.g. the database UUID, not the displayId)')
+	},
+	async ({ suiteId }) => {
+		const data = await get(`/test-suites/${suiteId}`);
+		return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+	}
+);
+
+server.tool(
+	'create_test_suite',
+	'Create a new test suite in the Plum Test Repository.',
+	{
+		name: z.string().min(1).describe('Suite name, e.g. "User Authentication"'),
+		description: z.string().optional().describe('What this suite covers'),
+		priority: z
+			.enum(['Critical', 'High', 'Medium', 'Low'])
+			.optional()
+			.describe('Suite priority (default Medium)')
+	},
+	async ({ name, description, priority }) => {
+		const data = await post('/test-suites', { name, description, priority });
+		return { content: [{ type: 'text', text: JSON.stringify(data.suite, null, 2) }] };
+	}
+);
+
+// -- Test Repository: Cases -------------------------------------------------
+
+server.tool(
+	'create_test_case',
+	'Create a test case inside an existing test suite.',
+	{
+		suiteId: z.string().describe('UUID of the parent test suite'),
+		title: z.string().min(1).describe('Case title, e.g. "User can log in with valid credentials"'),
+		description: z.string().optional().describe('Scope, assumptions, or edge cases'),
+		priority: z.enum(['Critical', 'High', 'Medium', 'Low']).optional()
+	},
+	async ({ suiteId, title, description, priority }) => {
+		const data = await post('/test-cases', { suiteId, title, description, priority });
+		return { content: [{ type: 'text', text: JSON.stringify(data.testCase, null, 2) }] };
+	}
+);
+
+server.tool(
+	'set_test_steps',
+	'Set (replace) the manual test steps for a test case. Each step has an action, optional test data, and optional expected output.',
+	{
+		caseId: z.string().describe('UUID of the test case'),
+		steps: z
+			.array(
+				z.object({
+					action: z.string().describe('What the tester does'),
+					testData: z.string().optional().describe('Specific input or data to use'),
+					expectedOutput: z.string().optional().describe('What should happen')
+				})
+			)
+			.describe('Ordered list of steps. Replaces any existing steps.')
+	},
+	async ({ caseId, steps }) => {
+		const data = await put(`/test-cases/${caseId}/steps`, { steps });
+		return { content: [{ type: 'text', text: JSON.stringify(data.steps, null, 2) }] };
+	}
+);
+
+// -- Test Runner ------------------------------------------------------------
+
+server.tool(
+	'run_tests',
+	[
+		'Trigger a Plum test run and wait for results. Returns a pass/fail summary.',
+		'',
+		'For PR testing: pass baseUrl to override the default BASE_URL for this run only.',
+		'If the app runs on localhost, use host.docker.internal instead (e.g. http://host.docker.internal:3000)',
+		'so the Plum Docker container can reach it.',
+		'',
+		'Tag filter examples: "@login" "@TC-001 or @TC-002" "@smoke and not @slow"',
+		'Leave tag blank to run all tests.'
+	].join('\n'),
+	{
+		tag: z
+			.string()
+			.optional()
+			.describe('Cucumber tag expression to filter scenarios. Leave blank to run all.'),
+		browser: z
+			.enum(['chromium', 'firefox'])
+			.optional()
+			.describe('Browser to run tests in (default chromium)'),
+		workers: z
+			.number()
+			.int()
+			.positive()
+			.max(10)
+			.optional()
+			.describe('Number of parallel workers (default 1)'),
+		baseUrl: z
+			.string()
+			.url()
+			.optional()
+			.describe(
+				'Override the app URL for this run only. Use host.docker.internal instead of localhost.'
+			),
+		testRunId: z
+			.string()
+			.optional()
+			.describe(
+				'Link results to a Plum Test Run. Automated entries will be marked pass/fail automatically.'
+			)
+	},
+	async ({ tag, browser, workers, baseUrl, testRunId }) => {
+		const { jobId } = await post('/trigger', { tag, browser, workers, baseUrl, testRunId });
+
+		const job = await pollJob(jobId);
+
+		if (job.status === 'timeout') {
+			return {
+				content: [
+					{
+						type: 'text',
+						text: `Tests are still running after 10 minutes. Job ID: ${jobId}\nUse get_run_status("${jobId}") to check later.`
+					}
+				]
+			};
+		}
+
+		if (!job.reportId) {
+			return {
+				content: [
+					{
+						type: 'text',
+						text: `Tests finished with exit code ${job.exitCode} but no report was found. The run may have been cancelled or produced no output.`
+					}
+				]
+			};
+		}
+
+		const report = await get(`/reports/${job.reportId}`);
+		const summary = summariseReport(report.report ?? report);
+
+		const lines = [
+			`Status: ${summary.status?.toUpperCase()}`,
+			`Scenarios: ${summary.summary.total} total, ${summary.summary.passed} passed, ${summary.summary.failed} failed`,
+			`Browser: ${summary.browser}`,
+			`Tags: ${summary.tags || 'all tests'}`,
+			''
+		];
+
+		if (summary.failures.length > 0) {
+			lines.push('Failed scenarios:');
+			for (const f of summary.failures) {
+				lines.push(`  ✗ ${f.feature} › ${f.scenario}`);
+				if (f.failedStep) lines.push(`    Step: ${f.failedStep}`);
+				if (f.error) lines.push(`    Error: ${f.error.split('\n')[0]}`);
+			}
+		} else {
+			lines.push('All scenarios passed.');
+		}
+
+		lines.push('', `Report ID: ${summary.id}`);
+
+		return { content: [{ type: 'text', text: lines.join('\n') }] };
+	}
+);
+
+server.tool(
+	'get_run_status',
+	'Check the status of a test run that was started with run_tests. Returns status, exit code, and report ID when done.',
+	{
+		jobId: z.string().uuid().describe('Job ID returned by run_tests')
+	},
+	async ({ jobId }) => {
+		const job = await get(`/trigger/${jobId}`);
+		return { content: [{ type: 'text', text: JSON.stringify(job, null, 2) }] };
+	}
+);
+
+// -- Reports ----------------------------------------------------------------
+
+server.tool(
+	'list_reports',
+	'List recent Plum test reports.',
+	{
+		limit: z.number().int().positive().max(50).optional().describe('Number of reports (default 10)')
+	},
+	async ({ limit = 10 }) => {
+		const data = await get(`/reports?limit=${limit}`);
+		return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+	}
+);
+
+server.tool(
+	'get_report_summary',
+	'Get a human-readable summary of a Plum test report, including a list of failed scenarios.',
+	{
+		reportId: z.number().int().describe('Numeric report ID')
+	},
+	async ({ reportId }) => {
+		const data = await get(`/reports/${reportId}`);
+		const summary = summariseReport(data.report ?? data);
+		const lines = [
+			`Report #${summary.id} — ${summary.status?.toUpperCase()}`,
+			`Date: ${summary.createdAt}`,
+			`Browser: ${summary.browser}`,
+			`Tags: ${summary.tags || 'all tests'}`,
+			`Scenarios: ${summary.summary.total} total, ${summary.summary.passed} passed, ${summary.summary.failed} failed`,
+			''
+		];
+		if (summary.failures.length > 0) {
+			lines.push('Failures:');
+			for (const f of summary.failures) {
+				lines.push(`  ✗ ${f.feature} › ${f.scenario}`);
+				if (f.failedStep) lines.push(`    Step: ${f.failedStep}`);
+				if (f.error) lines.push(`    Error: ${f.error.split('\n')[0]}`);
+			}
+		} else {
+			lines.push('All scenarios passed.');
+		}
+		return { content: [{ type: 'text', text: lines.join('\n') }] };
+	}
+);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+async function main() {
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+main().catch((err) => {
+	console.error(err);
+	process.exit(1);
+});

package/backend/middleware/jwtAuth.js

@@ -16,9 +16,27 @@
  */
 
 const { verifyToken } = require('../services/userService');
+const prisma = require('../services/prisma');
 
 function jwtAuth(req, res, next) {
 	const auth = req.headers.authorization;
+
+	// MCP API key — resolves to the first admin user so createdById is always valid
+	const mcpKey = process.env.PLUM_MCP_KEY;
+	if (mcpKey && auth === `ApiKey ${mcpKey}`) {
+		prisma.user
+			.findFirst({ where: { role: 'admin' }, select: { id: true } })
+			.then((admin) => {
+				req.user = { userId: admin?.id ?? null };
+				next();
+			})
+			.catch(() => {
+				req.user = { userId: null };
+				next();
+			});
+		return;
+	}
+
 	if (!auth || !auth.startsWith('Bearer ')) {
 		return res.status(401).json({ error: 'Unauthorized' });
 	}