plum-e2e 1.1.1 → 1.2.1

package/README.md

@@ -1,26 +1,26 @@
-![alt-text="social-preview"](https://repository-images.githubusercontent.com/936477779/e928fce3-6d4c-4609-92a0-0a1091c99752)
+![Plum social preview](https://repository-images.githubusercontent.com/936477779/e928fce3-6d4c-4609-92a0-0a1091c99752)
 
 <p align="center">
-  📖 <a href="https://github.com/silverlunah/plum/wiki">Wiki</a> |
-  📦 <a href="https://www.npmjs.com/package/plum-e2e">npm</a>
+  <a href="https://www.npmjs.com/package/plum-e2e"><img src="https://img.shields.io/npm/v/plum-e2e?color=7c3aed&label=plum-e2e" alt="npm version" /></a>
+  <a href="https://github.com/silverlunah/plum/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue" alt="license" /></a>
+  <a href="https://github.com/silverlunah/plum/wiki"><img src="https://img.shields.io/badge/docs-wiki-informational" alt="docs" /></a>
 </p>
 
-## Welcome to Plum!
-
-Plum is a ready-to-use E2E test automation environment that combines [Playwright](https://playwright.dev) and [Cucumber](https://cucumber.io). Write tests in [Gherkin](https://cucumber.io/docs/gherkin/) format, run them from the CLI or through a UI, and view reports — all in one place.
+<p align="center">
+  A ready-to-use E2E test automation environment built on <a href="https://playwright.dev">Playwright</a> + <a href="https://cucumber.io">Cucumber</a>.<br/>
+  Write tests in Gherkin, run them from the CLI or UI, and view reports — all in one place.
+</p>
 
 ---
 
-## For Users
+## Requirements
 
-> People who want to use Plum as a test environment for their website.
+- [Node.js](https://nodejs.org) (v18+)
+- [Docker](https://www.docker.com) — only needed for `plum start`
 
-### Prerequisites
-
-- [Node.js](https://nodejs.org)
-- [Docker](https://www.docker.com) (required for `plum start`)
+---
 
-### Setup
+## Quick Start
 
 ```bash
 npm install -g plum-e2e
@@ -28,38 +28,117 @@ mkdir my-tests && cd my-tests
 plum init
 ```
 
-`plum init` creates the following in your project directory and installs the [Cucumber VS Code extension](https://marketplace.visualstudio.com/items?itemName=cucumberopen.cucumber-official) for step definition linking:
+---
+
+## Setup & Configuration
+
+### `plum init`
+
+Scaffolds a new project in the current directory. Run this once after creating your project folder.
+
+```bash
+plum init
+```
+
+Creates the following structure:
 
 <pre>
-╠═ tests
-║  ╠═ features           : Gherkin feature files — your test cases
-║  ╠═ step_definitions   : TypeScript step implementations
-║  ╠═ pages              : Page Object Models
-║  ╚═ utils              : Shared utilities (browser setup, constants, etc.)
-╠═ .vscode
-║  ╚═ settings.json      : Cucumber extension config (step definition linking)
-╚═ .env                  : Environment config (BASE_URL, IS_HEADLESS)
+╠═ tests/
+║  ╠═ features/          — Gherkin .feature files (your test cases)
+║  ╠═ step_definitions/  — TypeScript step implementations
+║  ╠═ pages/             — Page Object Models
+║  ╚═ utils/             — Browser setup, hooks, shared helpers
+╠═ .vscode/
+║  ╚═ settings.json      — Cucumber extension config (step linking)
+╠═ .env                  — Environment config (BASE_URL, IS_HEADLESS)
+╠═ .gitignore            — Pre-configured to ignore .plum/ and reports/
+╚═ plum.plugins.json     — Add extra npm packages for your tests here
 </pre>
 
-### Commands
+Also installs all Plum dependencies and the [Cucumber VS Code extension](https://marketplace.visualstudio.com/items?itemName=cucumberopen.cucumber-official) for step definition linking.
+
+---
+
+### `.env` — Environment Config
 
-| Command                       | Description                                                                |
-| ----------------------------- | -------------------------------------------------------------------------- |
-| `plum init`                   | Scaffold the `tests/` folder and `.env` file in your project directory     |
-| `plum dev [tag]`              | Run tests locally without Docker. Pass a tag to filter (e.g. `@test-1`)    |
-| `plum dev --parallel N [tag]` | Run tests in parallel with N workers (e.g. `plum dev --parallel 4`)        |
-| `plum start`                  | Start the full stack via Docker and open the UI at `http://localhost:5173` |
-| `plum create-step`            | Interactive prompt to generate a step definition and page object           |
+Plum creates a `.env` in your project root. Edit it to point at your app:
+
+```env
+BASE_URL=https://your-app.com
+IS_HEADLESS=false
+```
+
+| Variable      | Description                                              |
+| ------------- | -------------------------------------------------------- |
+| `BASE_URL`    | The base URL Playwright navigates to during tests        |
+| `IS_HEADLESS` | Run the browser headlessly (`true`) or visibly (`false`) |
 
 ---
 
-### Writing a Test
+### `plum.plugins.json` — Adding Packages
 
-Tests follow a three-layer structure: **Feature → Step Definition → Page Object**.
+If your tests need extra npm packages (e.g. a faker library, an assertion helper), add them to `plum.plugins.json`:
+
+```json
+{
+	"dependencies": {
+		"@faker-js/faker": "^9.0.0",
+		"dayjs": "^1.11.0"
+	}
+}
+```
+
+Plum installs these automatically before running tests. Commit this file so your whole team shares the same dependencies.
+
+---
+
+## Development Commands
+
+### `plum dev` — Run Tests Locally
+
+Runs tests directly on your machine without Docker. This is the fastest way to write and debug tests.
+
+```bash
+plum dev                        # run all tests
+plum dev @test-login-1          # run a single scenario by tag
+plum dev @suite-login           # run a whole suite by tag
+plum dev --parallel 4           # run all tests across 4 workers
+plum dev --parallel 4 @suite-x  # run a suite in parallel
+```
+
+> Syncs your `tests/` folder into Plum, installs dependencies, and runs Cucumber.
 
-#### 1. Feature File
+---
 
-Create a `.feature` file in `tests/features/`. Tags are used to filter which tests to run.
+### `plum start` — Run via Docker
+
+Starts the full Plum stack (backend + UI) in Docker. Use this when you want the web interface at `http://localhost:5173` to trigger, monitor, and schedule tests.
+
+```bash
+plum start
+```
+
+> Requires Docker to be running. Automatically rebuilds if you've changed plugins or config.
+
+---
+
+### `plum create-step` — Generate a Step
+
+Interactive prompt that generates a new step definition and its Page Object method.
+
+```bash
+plum create-step
+```
+
+Follow the prompts to describe the action — Plum writes the boilerplate so you just fill in the implementation.
+
+---
+
+## Writing a Test
+
+Tests follow a three-layer structure: **Feature → Step Definition → Page Object**.
+
+### 1. Feature File
 
 ```gherkin
 # tests/features/Login.feature
@@ -74,9 +153,9 @@ Feature: Login
     Then I should see the dashboard
 ```
 
-#### 2. Page Object Model
+Use tags (`@suite-login`, `@test-login-1`) to filter which tests to run.
 
-Create a `.ts` file in `tests/pages/`. Methods are **static** — they use `page()` internally so you never need to pass a page instance around.
+### 2. Page Object
 
 ```typescript
 // tests/pages/LoginPage.ts
@@ -100,9 +179,9 @@ export class LoginPage {
 }
 ```
 
-#### 3. Step Definition
+Methods are **static** — they use `page()` internally so you never pass a page instance around.
 
-Create a `.ts` file in `tests/step_definitions/`. Just import the page and call its static methods directly.
+### 3. Step Definition
 
 ```typescript
 // tests/step_definitions/LoginSteps.ts
@@ -123,59 +202,52 @@ Then('I should see the dashboard', async () => {
 });
 ```
 
-#### Running your test
+---
 
-```bash
-plum dev @test-login-1   # run a single scenario
-plum dev @suite-login    # run the whole suite
-plum dev                 # run all tests
-```
+## Command Reference
 
----
+| Command                 | When to use                                  |
+| ----------------------- | -------------------------------------------- |
+| `plum init`             | First-time setup in a new project folder     |
+| `plum dev`              | Run all tests locally                        |
+| `plum dev @tag`         | Run tests matching a tag locally             |
+| `plum dev --parallel N` | Run tests across N parallel workers locally  |
+| `plum start`            | Start the full UI stack via Docker           |
+| `plum create-step`      | Interactively scaffold a new step definition |
 
-## For Developers
+---
 
-> People who want to contribute to or develop Plum itself.
+## For Contributors
 
-### Setup
+> Only relevant if you're developing Plum itself.
 
 ```bash
 git clone https://github.com/silverlunah/plum.git
 cd plum
-npm run init
+npm run init        # installs root + backend + frontend dependencies
 ```
 
-`npm run init` installs all dependencies across the root, backend, and frontend.
-
-### Backend Local Commands
-
-Run these from the `backend/` directory:
-
-| Command                    | Description                                                      |
-| -------------------------- | ---------------------------------------------------------------- |
-| `npm run init`             | Create `.env` and copy scaffold into `backend/tests/`            |
-| `npm test [-- tag]`        | Run tests from `backend/tests/` directly                         |
-| `npm test -- --parallel N` | Run tests in parallel with N workers                             |
-| `npm run create-step`      | Interactive prompt to generate a step definition and page object |
+### Backend
 
 ```bash
 cd backend
-npm run init                  # sets up .env and tests/ for local development
-npm test                      # run all tests
-npm test -- @test-1           # run a specific test by tag
-npm test -- --parallel 4      # run tests in parallel
-npm run create-step           # generate a new step and page interactively
+npm run init              # set up .env and local test scaffold
+npm test                  # run all tests
+npm test -- @test-1       # run a specific test by tag
+npm test -- --parallel 4  # run tests in parallel
+npm run create-step       # generate a step definition interactively
 ```
 
 ### Docker
 
 ```bash
-npm run docker:up    # build and start all services
+npm run docker:up    # build and start all services in detached mode
 npm run docker:down  # stop all services
 ```
 
 ---
 
-## Other
-
-Plum is completely free to use! But if you want to share some love, here's my [PayPal](https://www.paypal.me/silverlunah) or [Wise](https://wise.com/pay/me/janneserjosee)
+<p align="center">
+  Plum is free to use. If you'd like to show some love:<br/>
+  <a href="https://www.paypal.me/silverlunah">PayPal</a> · <a href="https://wise.com/pay/me/janneserjosee">Wise</a>
+</p>

package/backend/Dockerfile

@@ -15,7 +15,7 @@
 # along with Plum. If not, see https://www.gnu.org/licenses/.
 #
 
-FROM mcr.microsoft.com/playwright:v1.41.1
+FROM mcr.microsoft.com/playwright:v1.50.0
 WORKDIR /app
 
 COPY package.json package-lock.json ./
@@ -24,7 +24,9 @@ RUN npx playwright install --with-deps
 
 COPY . .
 
+RUN npx prisma generate
 RUN npm run create-env && sed -i 's/^IS_HEADLESS=false/IS_HEADLESS=true/' .env
 
 EXPOSE 3001
-CMD ["node", "server.js"]
+RUN chmod +x /app/entrypoint.sh
+ENTRYPOINT ["/bin/sh", "/app/entrypoint.sh"]

package/backend/_scaffold/utils/browser.ts

@@ -28,6 +28,7 @@ export async function teardown(
 		await _page.screenshot({ path: screenshotPath });
 		const screenshotData = fs.readFileSync(screenshotPath);
 		await attach(screenshotData, 'image/png');
+		fs.unlinkSync(screenshotPath);
 	}
 	await _browser?.close();
 }

package/backend/app.js

@@ -26,12 +26,14 @@ app.use(express.json());
 const testRoutes = require('./routes/tests.routes');
 const reportRoutes = require('./routes/reports.routes');
 const cronRoutes = require('./routes/cron.routes');
-const scheduleRoutes = require('./routes/schedules.routes');
+const settingsRoutes = require('./routes/settings.routes');
+const backupRoutes = require('./routes/backup.routes');
 
 app.use('/tests', testRoutes);
 app.use('/reports', reportRoutes);
 app.use('/cron-jobs', cronRoutes);
 app.use('/reports', express.static('reports'));
-app.use('/schedules', scheduleRoutes);
+app.use('/settings', settingsRoutes);
+app.use('/backup', backupRoutes);
 
 module.exports = app;

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

@@ -17,42 +17,12 @@
 
 const fs = require('fs');
 const path = require('path');
-const { reportsHistory } = require('../settings.json');
-
 const reportsDir = 'reports';
 const screenshotsDir = path.join(reportsDir, 'screenshots');
-const maxReports = reportsHistory;
 
 if (!fs.existsSync(reportsDir)) fs.mkdirSync(reportsDir, { recursive: true });
 if (!fs.existsSync(screenshotsDir)) fs.mkdirSync(screenshotsDir, { recursive: true });
 
-// Clean up old timestamped report JSON files
-const existingReports = fs
-	.readdirSync(reportsDir)
-	.filter((f) => f.endsWith('.json') && (f.startsWith('PASS_') || f.startsWith('FAIL_')))
-	.sort(
-		(a, b) =>
-			fs.statSync(path.join(reportsDir, b)).mtime - fs.statSync(path.join(reportsDir, a)).mtime
-	);
-
-while (existingReports.length >= maxReports) {
-	fs.unlinkSync(path.join(reportsDir, existingReports.pop()));
-}
-
-// Clean up old screenshots
-const existingScreenshots = fs
-	.readdirSync(screenshotsDir)
-	.filter((f) => f.endsWith('.png') || f.endsWith('.jpg'))
-	.sort(
-		(a, b) =>
-			fs.statSync(path.join(screenshotsDir, b)).mtime -
-			fs.statSync(path.join(screenshotsDir, a)).mtime
-	);
-
-while (existingScreenshots.length >= maxReports) {
-	fs.unlinkSync(path.join(screenshotsDir, existingScreenshots.pop()));
-}
-
 // Determine PASS/FAIL from cucumber JSON output
 const jsonReportFile = path.join(reportsDir, 'cucumber_report.json');
 let status = 'PASS';
@@ -86,6 +56,44 @@ const reportFileName = `${status}_cucumber_report_${process.env.TRIGGER}_${tag}_
 if (fs.existsSync(jsonReportFile)) {
 	fs.copyFileSync(jsonReportFile, path.join(reportsDir, reportFileName));
 	console.log(`Report saved: ${reportFileName}`);
+
+	// Persist metadata to database
+	(async () => {
+		try {
+			const { PrismaClient } = require('@prisma/client');
+			const prisma = new PrismaClient();
+
+			const triggerType = process.env.TRIGGER || 'command-line-trigger';
+			const builtInTriggers = ['manual-trigger', 'command-line-trigger', 'undefined'];
+			let cronJobId = null;
+
+			if (!builtInTriggers.includes(triggerType)) {
+				const job = await prisma.cronJob.findUnique({ where: { taskName: triggerType } });
+				if (job) cronJobId = job.id;
+			}
+
+			const rawTag = process.env.TAG || '@all-tests';
+			const tags = rawTag.replace(/^\(|\)$/g, '');
+
+			await prisma.report.upsert({
+				where: { fileName: reportFileName },
+				create: {
+					fileName: reportFileName,
+					status,
+					tags,
+					triggerType,
+					runners: runnerCount,
+					cronJobId
+				},
+				update: {}
+			});
+
+			await prisma.$disconnect();
+			console.log('Report metadata saved to database.');
+		} catch (e) {
+			console.error('Could not save report metadata to DB:', e.message);
+		}
+	})();
 } else {
 	console.log('Skipping report save — no cucumber_report.json.');
 }

package/{.prettierignore → backend/entrypoint.sh}

@@ -1,4 +1,4 @@
-#
+#!/bin/sh
 # This file is part of Plum.
 #
 # Plum is free software: you can redistribute it and/or modify
@@ -13,9 +13,10 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Plum. If not, see https://www.gnu.org/licenses/.
-#
+set -e
+
+echo "Running database migrations..."
+npx prisma migrate deploy
 
-# Package Managers
-package-lock.json
-pnpm-lock.yaml
-yarn.lock
+echo "Starting server..."
+exec node server.js