plum-e2e 1.2.3 → 1.3.0

package/CLAUDE.md

@@ -0,0 +1,201 @@
+# Plum — Claude Code Instructions
+
+## Stack
+
+- **Frontend**: SvelteKit 5, port 5173. ESM, no TypeScript.
+- **Backend**: Express + Socket.io, port 3001. CommonJS (`require`/`module.exports`).
+- **Database**: PostgreSQL via Prisma ORM (`backend/services/prisma.js`).
+- **Infrastructure**: Docker Compose. `docker-compose.yml` (standard), `docker-compose.node.yml` (multi-node).
+
+---
+
+## Frontend Standards
+
+### CSS
+
+- All design tokens are in `frontend/src/lib/styles/tokens.css` as CSS custom properties (`--accent`, `--bg`, `--text`, etc.).
+- Never use Tailwind. Never use inline `style=` attributes for themeable values.
+- Component styles go in the component's `<style>` block (scoped by default in Svelte).
+- When adding a new token color, add it to `tokens.css` first, then reference `var(--your-token)`.
+
+### Constants and utilities
+
+- Shared constants live in `frontend/src/lib/constants.js`: `API_BASE`, `BROWSERS`, `TRIGGER_TYPES`, `WORKER_OPTIONS`, `REPORTS_PER_PAGE`, `COPY_TIMEOUT_MS`, `TOAST_TIMEOUT_MS`.
+- Format/display utilities live in `frontend/src/lib/utils/format.js`: `isScheduled`, `triggerLabel`, `triggerVariant`, `stagger`, `fmtDuration`.
+- Never hardcode the API URL — always use `API_BASE` from constants.
+- Never hardcode magic numbers that belong in constants.
+
+### API layer
+
+- All backend calls go through `frontend/src/lib/api/` modules (e.g., `reports.js`, `runners.js`).
+- Each module exports typed async functions. Route pages import from there, not from raw `fetch`.
+
+### Components
+
+Reuse shared components before creating new ones:
+
+| Component      | Path                                       | Purpose                          |
+| -------------- | ------------------------------------------ | -------------------------------- |
+| `EmptyState`   | `$lib/components/ui/EmptyState.svelte`     | Zero-item states                 |
+| `ConfirmModal` | `$lib/components/ui/ConfirmModal.svelte`   | Destructive action confirmations |
+| `Toast`        | `$lib/components/ui/Toast.svelte`          | Transient feedback messages      |
+| `BrowserIcon`  | `$lib/components/icons/BrowserIcon.svelte` | Browser logo icons               |
+
+### State management
+
+- Global runtime state lives in `frontend/src/lib/stores/runner.js` (`runnerState`, `runnerConfig`, `panelExpanded`, etc.).
+- `reportsVersion` and `testsVersion` are increment-to-refresh signals — increment them to trigger dependent reactive blocks without page reloads.
+
+### Route pages
+
+- Pages are thin: they load data and delegate display to components.
+- `+page.js` (load function) handles server-side or initial data fetching.
+- No business logic inside route page files.
+
+---
+
+## Backend Standards
+
+### File layout
+
+```
+backend/
+  app.js            — Express setup, middleware, static routes
+  routes/           — Thin HTTP handlers only
+  services/         — All business logic
+  websockets/       — Socket.io event handlers
+  lib/              — Pure utility functions
+  constants/        — Shared constant definitions
+  config/scripts/   — CLI scripts (generate-report, install, etc.)
+  prisma/           — Schema and migrations
+```
+
+### Routes
+
+Routes delegate immediately to services. No business logic in route handlers.
+
+```js
+// Good
+router.get('/:id', async (req, res, next) => {
+  try {
+    const report = await reportService.getReportDetail(Number(req.params.id));
+    if (!report) return res.status(404).json({ error: 'Not found' });
+    res.json(report);
+  } catch (e) { next(e); }
+});
+
+// Bad — business logic in the route
+router.get('/:id', async (req, res) => {
+  const row = await prisma.report.findUnique({ where: { id: ... }, include: { ... } });
+  const features = row.content.features.map(f => { /* transform */ });
+  res.json(features);
+});
+```
+
+### Services
+
+- Services own all DB queries, data transformation, and side effects (file I/O, etc.).
+- Use `backend/services/prisma.js` as the shared Prisma client — do not create new instances.
+- Services return plain JS objects, not Prisma model instances with extra methods.
+
+### Constants
+
+- Trigger types and runner IDs live in `backend/constants/triggers.js`.
+- Never use raw string literals for values that are used in more than one place.
+
+### Screenshots / file storage
+
+- Screenshot files are stored in `reports/screenshots/` (resolved at runtime via `REPORTS_DIR`).
+- Express serves them via `app.use('/screenshots', express.static(SCREENSHOTS_DIR))`.
+- DB stores only the filename, not the path or full URL.
+- Frontend constructs the full URL with `screenshotUrl(filename)` from `$lib/api/reports.js`.
+
+---
+
+## Comments
+
+Default: **no comments**.
+
+Add a comment only when the **WHY** is non-obvious — a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise a future reader.
+
+Never write comments that:
+
+- Explain what the code does (well-named identifiers already do that)
+- Describe the current task or fix ("added for the live page", "handles issue #123")
+- Are multi-line docblocks explaining parameters
+
+The GPL license header at the top of every file is a legal requirement — do not remove it.
+
+---
+
+## General Rules
+
+- **No Tailwind, no Bootstrap, no utility-class frameworks.**
+- **No hardcoded URLs or magic strings** — use constants.
+- **No premature abstractions** — three similar lines is better than a helper created for two cases.
+- **No backwards-compat hacks** — rename, re-export, or add `_unused` prefixes only when explicitly asked.
+- **No error handling for scenarios that cannot happen** — trust internal guarantees; only validate at system boundaries (user input, external APIs).
+- **No half-finished implementations** — if a feature cannot be completed, say so before starting.
+- **Prefer editing existing files** over creating new ones.
+
+---
+
+## Database
+
+- All schema changes require a Prisma migration file in `backend/prisma/migrations/`.
+- Run `npx prisma migrate deploy` (or rebuild Docker) to apply.
+- Report content is stored as JSONB in the `Report.content` column — never reconstruct report metadata from filenames.
+- The `getAllReports()` service function deliberately excludes `content` for list performance — only `getReportDetail(id)` fetches it.
+
+---
+
+## Docker
+
+- Rebuild after any backend dependency or schema change: `docker-compose up --build -d`
+- The backend container runs `prisma migrate deploy` on startup before starting Express.
+- Frontend dev server (`npm run dev`) runs outside Docker for fast HMR.
+
+---
+
+## Windows Compatibility
+
+Plum runs on Windows. Every script and service must work on Windows without modification.
+
+### `spawn` — always use `{ shell: true }` for npm/npx/docker
+
+On Windows, `npm`, `npx`, and `docker` are `.cmd` wrappers, not binaries. Without `shell: true`, `spawn` cannot find them.
+
+```js
+// Good
+spawn('npm', ['run', 'test'], { env, shell: true });
+
+// Bad — breaks on Windows
+spawn('npm', ['run', 'test'], { env });
+```
+
+`execSync` and `exec` use the system shell by default, so they are fine without `shell: true`.
+
+### Spawning Node.js — use `process.execPath`, not `'node'`
+
+```js
+// Good
+spawn(process.execPath, [scriptPath], { stdio: 'inherit' });
+
+// Bad — 'node' may not be in PATH or may resolve to the wrong version
+spawn('node', [scriptPath]);
+```
+
+### File paths — always use `path.join()` or `path.resolve()`
+
+Never build paths by concatenating strings with `/`. Use `path.join()` everywhere.
+
+When a path is written into a YAML or config file (e.g., docker-compose override), normalise Windows backslashes: `absPath.replace(/\\/g, '/')`.
+
+### Forbidden Unix-only APIs in Node.js scripts
+
+Never call these from `.js` scripts — they do not exist on Windows:
+
+- `chmod` / `chown` — use `fs` permissions APIs if needed
+- `which` — use `which` npm package or check `PATH` manually
+- `curl` / `wget` — use Node.js `fetch` or `https` module
+- Shell operators (`&&`, `||`, `$(cmd)`) inside strings passed to `execSync` — split into separate `execSync` calls instead

package/README.md

@@ -1,4 +1,4 @@
-![Plum social preview](https://repository-images.githubusercontent.com/936477779/e928fce3-6d4c-4609-92a0-0a1091c99752)
+![Plum social preview](https://repository-images.githubusercontent.com/936477779/3accb0f2-72b4-447c-b255-d171f6284104)
 
 <p align="center">
   <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>
@@ -15,130 +15,159 @@
 
 ## Requirements
 
-- [Node.js](https://nodejs.org) (v18+)
-- [Docker](https://www.docker.com) — only needed for `plum start`
+- [Node.js](https://nodejs.org) v18 or higher
+- [Docker](https://www.docker.com) — required for `plum server start` and `plum node start`
 
 ---
 
-## Quick Start
+## 1. Installation
+
+### Install Plum globally
 
 ```bash
 npm install -g plum-e2e
-mkdir my-tests && cd my-tests
-plum init
 ```
 
----
-
-## Setup & Configuration
+> The `-g` flag is required. Plum is a CLI tool — it must be installed globally to use `plum` commands anywhere on your machine.
 
-### `plum init`
+### Initialize a new project
 
-Scaffolds a new project in the current directory. Run this once after creating your project folder.
+Create a folder for your tests and run `plum init` inside it:
 
 ```bash
+mkdir my-tests
+cd my-tests
 plum init
 ```
 
-Creates the following structure:
+This sets up your project with a working test scaffold:
 
-<pre>
-╠═ 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>
+```
+my-tests/
+├── tests/
+│   ├── features/          — Gherkin .feature files (your test cases)
+│   ├── step_definitions/  — TypeScript step implementations
+│   ├── pages/             — Page Object Models
+│   └── utils/             — Browser setup, hooks, shared helpers
+├── .env                   — Base URL and browser settings
+├── .gitignore             — Pre-configured to exclude reports/
+├── plum.plugins.json      — Add extra npm packages for your tests
+└── tsconfig.json          — IDE type resolution (no local install needed)
+```
 
-Also installs all Plum dependencies and the [Cucumber VS Code extension](https://marketplace.visualstudio.com/items?itemName=cucumberopen.cucumber-official) for step definition linking.
+The `tests/` folder includes working example tests against [SauceDemo](https://www.saucedemo.com/v1/) so you can run something immediately.
 
----
+### Configure your target URL
 
-### `.env` — Environment Config
-
-Plum creates a `.env` in your project root. Edit it to point at your app:
+Open `.env` and set your application's URL:
 
 ```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`) |
-
----
+| Variable      | Description                                          |
+| ------------- | ---------------------------------------------------- |
+| `BASE_URL`    | The URL Playwright opens at the start of tests       |
+| `IS_HEADLESS` | `true` to run headlessly, `false` to see the browser |
 
-### `plum.plugins.json` — Adding Packages
+### Add extra packages (optional)
 
-If your tests need extra npm packages (e.g. a faker library, an assertion helper), add them to `plum.plugins.json`:
+If your tests need additional npm packages, add them to `plum.plugins.json`:
 
 ```json
 {
 	"dependencies": {
-		"@faker-js/faker": "^9.0.0",
-		"dayjs": "^1.11.0"
+		"@faker-js/faker": "^9.0.0"
 	}
 }
 ```
 
-Plum installs these automatically before running tests. Commit this file so your whole team shares the same dependencies.
+Plum installs these automatically before each run. Commit this file so your whole team uses the same packages.
 
 ---
 
-## Development Commands
+## 2. Starting the Server
 
-### `plum dev` — Run Tests Locally
+Plum includes a full web UI for triggering tests, viewing reports, and scheduling runs.
 
-Runs tests directly on your machine without Docker. This is the fastest way to write and debug tests.
+### Start
 
 ```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
+plum server start
 ```
 
-> Syncs your `tests/` folder into Plum, installs dependencies, and runs Cucumber.
+or the shorthand:
 
----
+```bash
+plum start
+```
+
+Once running, open **http://localhost:5173** in your browser.
 
-### `plum start` — Run via Docker
+> Docker must be running before you use this command. Plum builds and starts the backend, database, and UI automatically.
 
-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.
+### Stop
 
 ```bash
-plum start
+plum server stop
+```
+
+or the shorthand:
+
+```bash
+plum stop
 ```
 
-> Requires Docker to be running. Automatically rebuilds if you've changed plugins or config.
+> Your data (reports, schedules, settings) is preserved in the database volume. Only the running containers are stopped.
 
 ---
 
-### `plum create-step` — Generate a Step
+## 3. Writing Tests
 
-Interactive prompt that generates a new step definition and its Page Object method.
+Plum uses [Cucumber](https://cucumber.io) and [Gherkin](https://cucumber.io/docs/gherkin/) to write human-readable test cases.
 
-```bash
-plum create-step
+### Cucumber Basics
+
+Gherkin is a plain-English language for writing test scenarios. Each test lives in a `.feature` file and follows this structure:
+
+```gherkin
+@suite-login
+Feature: Login
+
+  @test-login-1
+  Scenario: User can log in with valid credentials
+    Given I am on the login page
+    When I enter valid credentials
+    Then I should see the dashboard
 ```
 
-Follow the prompts to describe the action — Plum writes the boilerplate so you just fill in the implementation.
+**Key concepts:**
+
+| Term               | What it is                                                             |
+| ------------------ | ---------------------------------------------------------------------- |
+| `Feature`          | A group of related scenarios (one per file)                            |
+| `Scenario`         | A single test case                                                     |
+| `Given`            | Sets up the initial state                                              |
+| `When`             | Performs an action                                                     |
+| `Then`             | Asserts the expected outcome                                           |
+| `Background`       | Steps that run before every scenario in a file                         |
+| `Scenario Outline` | A parameterized scenario that runs once per row in an `Examples` table |
+| `@tag`             | A label used to run specific tests or suites                           |
+
+**Useful links:**
+
+- [Gherkin syntax reference](https://cucumber.io/docs/gherkin/reference/)
+- [Cucumber step definitions](https://cucumber.io/docs/cucumber/step-definitions/)
+- [Playwright documentation](https://playwright.dev/docs/intro)
 
 ---
 
-## Writing a Test
+### Project Structure
 
 Tests follow a three-layer structure: **Feature → Step Definition → Page Object**.
 
-### 1. Feature File
+#### Feature File — what to test
 
 ```gherkin
 # tests/features/Login.feature
@@ -149,13 +178,13 @@ Feature: Login
   @test-login-1
   Scenario: User can log in with valid credentials
     Given I am on the login page
-    When I log in with valid credentials
+    When I enter valid credentials
     Then I should see the dashboard
 ```
 
-Use tags (`@suite-login`, `@test-login-1`) to filter which tests to run.
+Tags (`@suite-login`, `@test-login-1`) let you run specific tests or entire suites. Every suite and scenario should have its own tag.
 
-### 2. Page Object
+#### Page Object — how to interact with the page
 
 ```typescript
 // tests/pages/LoginPage.ts
@@ -167,8 +196,8 @@ export class LoginPage {
 		await page().goto(process.env.BASE_URL as string);
 	}
 
-	static async login(email: string, password: string) {
-		await page().fill('#email', email);
+	static async enterCredentials(username: string, password: string) {
+		await page().fill('#username', username);
 		await page().fill('#password', password);
 		await page().click('button[type="submit"]');
 	}
@@ -179,9 +208,9 @@ export class LoginPage {
 }
 ```
 
-Methods are **static** — they use `page()` internally so you never pass a page instance around.
+Methods are `static` and use the `page()` helper from `utils/browser.ts` — you never pass a page instance around.
 
-### 3. Step Definition
+#### Step Definition — connects Gherkin to code
 
 ```typescript
 // tests/step_definitions/LoginSteps.ts
@@ -193,8 +222,8 @@ Given('I am on the login page', async () => {
 	await LoginPage.goToLoginPage();
 });
 
-When('I log in with valid credentials', async () => {
-	await LoginPage.login('user@example.com', 'password');
+When('I enter valid credentials', async () => {
+	await LoginPage.enterCredentials('user@example.com', 'password123');
 });
 
 Then('I should see the dashboard', async () => {
@@ -204,47 +233,165 @@ Then('I should see the dashboard', async () => {
 
 ---
 
+### Generate a Step
+
+Use `plum create-step` to interactively scaffold a new step definition and page object method:
+
+```bash
+plum create-step
+```
+
+Follow the prompts — Plum writes the boilerplate, you fill in the implementation.
+
+---
+
+### Run Tests Locally
+
+Use `plum dev` to run tests directly on your machine without Docker:
+
+```bash
+plum dev                         # run all tests
+plum dev @test-login-1           # run a single scenario
+plum dev @suite-login            # run an entire suite
+plum dev --parallel 4            # run all tests across 4 workers
+plum dev --parallel 4 @suite-login  # run a suite in parallel
+```
+
+> `plum dev` syncs your tests, installs dependencies, and runs Cucumber. No Docker needed.
+
+---
+
+## 4. Runner Setup
+
+Runners are additional machines that can execute tests in parallel alongside the primary server. This lets you distribute a large test suite across multiple nodes.
+
+### Add a local runner node
+
+On the machine that will act as a runner, navigate to your Plum project and run:
+
+```bash
+plum node start --token your-secret-token
+```
+
+| Flag      | Description                                                                     |
+| --------- | ------------------------------------------------------------------------------- |
+| `--token` | A secret token the primary server must send to authenticate. Keep this private. |
+
+> The runner starts a Docker container on port `3001` by default. Make sure Docker is running.
+
+### Register the runner in the UI
+
+Once the node is running:
+
+1. Open the Plum UI at **http://localhost:5173**
+2. Go to **Settings → Runners**
+3. Click **Add Runner** and enter the node's URL, token, and a name
+
+The runner will appear in the UI and can be selected when triggering tests.
+
+### Stop a runner node
+
+```bash
+plum node stop
+```
+
+---
+
 ## 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 |
+| 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 dev`                    | Run all tests locally without Docker                     |
+| `plum dev @tag`               | Run tests matching a tag                                 |
+| `plum dev --parallel N`       | Run tests across N parallel workers                      |
+| `plum create-step`            | Interactively scaffold a new step definition             |
+| `plum node start --token <t>` | Start a runner node on this machine                      |
+| `plum node stop`              | Stop the runner node                                     |
 
 ---
 
-## For Contributors
+## Development
 
-> Only relevant if you're developing Plum itself.
+> This section is for contributors developing Plum itself. If you're a user, the sections above are all you need.
+
+### Clone and install
 
 ```bash
 git clone https://github.com/silverlunah/plum.git
 cd plum
-npm run init        # installs root + backend + frontend dependencies
+npm run init
 ```
 
-### Backend
+`npm run init` installs all dependencies across the monorepo (root, backend, and frontend) in one command.
+
+### Start the stack
+
+```bash
+npm run docker:up    # build and start all services (detached)
+npm run docker:down  # stop all services
+```
+
+The UI will be available at **http://localhost:5173** after `docker:up` completes.
+
+> After any backend dependency or schema change, re-run `npm run docker:up` to rebuild the containers.
+
+### Backend — writing and running tests
+
+All test development happens inside the `backend/` directory, where the Playwright + Cucumber runner lives:
 
 ```bash
 cd backend
-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
+**Run tests:**
 
 ```bash
-npm run docker:up    # build and start all services in detached mode
-npm run docker:down  # stop all services
+npm test                     # run all tests
+npm test -- @test-1          # run a specific scenario by tag
+npm test -- @suite-login     # run an entire suite
+npm test -- --parallel 4     # run all tests in parallel
 ```
 
+**Generate a step definition:**
+
+```bash
+npm run create-step
+```
+
+Interactive prompt that creates a new step and its page object method.
+
+**Scaffold a new test:**
+
+```bash
+npm run create-test
+```
+
+Interactive prompt that creates a new `.feature` file, page object, and step definition file from a template — ready for you to implement.
+
+### Test file locations
+
+```
+backend/tests/
+  features/          — Gherkin .feature files
+  step_definitions/  — TypeScript step implementations
+  pages/             — Page Object Models
+  utils/             — Browser setup, hooks, helpers
+```
+
+### Frontend
+
+The frontend dev server runs outside Docker for fast hot module replacement:
+
+```bash
+cd frontend
+npm run dev
+```
+
+Available at **http://localhost:5173**. The backend (via Docker) serves API requests at **http://localhost:3001**.
+
 ---
 
 <p align="center">