plum-e2e 1.0.10 → 1.1.0

package/.claude/settings.local.json

@@ -6,7 +6,22 @@
 			"Bash(git commit -m ':*)",
 			"Bash(git push:*)",
 			"Bash(gh pr:*)",
-			"Bash(node:*)"
+			"Bash(node:*)",
+			"Bash(curl *)",
+			"Bash(git pull *)",
+			"Bash(npm install *)",
+			"Bash(code --list-extensions)",
+			"Bash(git branch *)",
+			"Bash(git commit -m ' *)",
+			"mcp__ide__getDiagnostics",
+			"Bash(git rm *)",
+			"Bash(npm test *)",
+			"Bash(npm run *)",
+			"Bash(git *)",
+			"Bash(python3 -c \"import sys; print\\(sys.stdin.read\\(\\)[:200]\\)\")",
+			"Bash(python3 -c ' *)",
+			"Bash(grep -rl \"^<!--$\" /Users/silverlunah/Projects/plum/frontend/src --include=\"*.svelte\")",
+			"Bash(python3 *)"
 		]
 	}
 }

package/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+	"cucumber.glue": [
+		"backend/tests/step_definitions/**/*.ts",
+		"backend/_scaffold/step_definitions/**/*.ts"
+	],
+	"cucumber.features": [
+		"backend/tests/features/**/*.feature",
+		"backend/_scaffold/features/**/*.feature"
+	]
+}

package/README.md

@@ -7,60 +7,174 @@
 
 ## Welcome to Plum!
 
-Plum makes setting up your testing framework easy. In just a few seconds, you can run the scaffold tests and write your own tests!
+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.
 
-By combining [Playwright](https://playwright.dev) and [Cucumber](https://cucumber.io), tests are easy to write and read. The code follows a POM (Page Object Model) structure, making it scalable and easy for developers to understand, while Cucumber test cases are written in [Gherkin](https://cucumber.io/docs/gherkin/) format, making them accessible to non-developers as well.
-
-You can view, run, and schedule tests in a simple UI. You can even view the history of your runs in the reports page!
-
-**_Pre-requisite:_**
-
-1. Install Docker and ensure the Docker daemon is running.
+---
 
 ## For Users
 
-People that want to use Plum as a test environment for their website.
+> People who want to use Plum as a test environment for their website.
 
-**_I. How to Run:_**
+### Prerequisites
 
-1. `npm install -g plum-e2e`
-2. Create your project directory. Example: `mkdir my-test-folder`
-3. Go inside the folder you created `cd my-test-folder`
-4. Run `plum init`
-   1. This will initialize Plum and will create your base files:
-      1. `\tests` folder: This include sample test cases for [SauceLabs](https://www.saucedemo.com/v1/)
-      2. `.env` file: Your starting .env file. You can set the BASE_URL to your own site after you're done with the scaffold tests.
-5. There are two ways to start testing:
-   1. By running the server. Run:<br/> `plum start` to start the server
-      1. Access the UI at: http://localhost:5173/
-   2. Without running the server. Recommended while you're writing your tests. Run:<br/> `plum dev <@test-id>`. If no test ID is included, it will run all tests
+- [Node.js](https://nodejs.org)
+- [Docker](https://www.docker.com) (required for `plum start`)
 
-## Basic Structure
+### Setup
 
-After you run `plum init`, these files will be created inside your project directory.
+```bash
+npm install -g plum-e2e
+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:
 
 <pre>
 ╠═ tests
-║  ╠═ features         : Cucumber feature files, contains your test cases
-║  ╠═ step_definitions : Reference to steps in the feature files
-║  ╠═ pages            : Contains functions used in step_definitions
-║  ╚═ utils            : Utility files (Constants, utility codes, etc.)
-╚═ env.                : Your .env file
+║  ╠═ 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)
 </pre>
 
-## Tutorial
+### Commands
+
+| 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           |
+
+---
+
+### Writing a Test
+
+Tests follow a three-layer structure: **Feature → Step Definition → Page Object**.
+
+#### 1. Feature File
+
+Create a `.feature` file in `tests/features/`. Tags are used to filter which tests to run.
+
+```gherkin
+# tests/features/Login.feature
+
+@suite-login
+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
+    Then I should see the dashboard
+```
+
+#### 2. Page Object Model
+
+Create a `.ts` file in `tests/pages/`. Methods are **static** — they use `page()` internally so you never need to pass a page instance around.
+
+```typescript
+// tests/pages/LoginPage.ts
+
+import { page } from '../utils/browser';
+
+export class LoginPage {
+	static async goToLoginPage() {
+		await page().goto(process.env.BASE_URL as string);
+	}
+
+	static async login(email: string, password: string) {
+		await page().fill('#email', email);
+		await page().fill('#password', password);
+		await page().click('button[type="submit"]');
+	}
+
+	static async verifyDashboardVisible() {
+		await page().waitForSelector('#dashboard');
+	}
+}
+```
+
+#### 3. Step Definition
+
+Create a `.ts` file in `tests/step_definitions/`. Just import the page and call its static methods directly.
+
+```typescript
+// tests/step_definitions/LoginSteps.ts
+
+import { Given, When, Then } from '@cucumber/cucumber';
+import { LoginPage } from '../pages/LoginPage';
+
+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');
+});
+
+Then('I should see the dashboard', async () => {
+	await LoginPage.verifyDashboardVisible();
+});
+```
+
+#### 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
+```
+
+---
+
+## For Developers
+
+> People who want to contribute to or develop Plum itself.
+
+### Setup
+
+```bash
+git clone https://github.com/silverlunah/plum.git
+cd plum
+npm run init
+```
+
+`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 |
 
-1. For a complete guide on how to write tests, visit our [Coming Soon](https://github.com/silverlunah/plum/wiki)
-2. An easy way to learn is to check the scaffold files starting from the Feature files -> Step Definitions -> Page files and utils/world.ts for the CustomWorld initialization. Those are the main files you need to write a test case.
+```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
+```
 
-## For Developers/Contributors
+### Docker
 
-For people that want to contribute to the project
+```bash
+npm run docker:up    # build and start all services
+npm run docker:down  # stop all services
+```
 
-1. Clone the project `git clone https://github.com/silverlunah/plum.git`
-2. `cd plum`
-3. Initialize the project by:<br/>`npm run init`
-4. Check if its running:<br/> `docker compose up --build -d`
+---
 
 ## Other
 

package/backend/_scaffold/features/LoginPage.feature

@@ -1,6 +1,48 @@
-@suite-1
+@suite-login
 Feature: Demo Sauce Login
 
+  # Background runs before every scenario in this file
+  Background:
+    Given I am in Demo Sauce Login page
+
+  # ── Basic Scenario ─────────────────────────────────────────────────────────
   @test-1
-  Scenario: Verify User Can Login Using Correct Details
-    Given I am in Demo Sauce Login page
+  Scenario: User can log in with valid credentials
+    When I enter "standard_user" in username field
+    And I enter "secret_sauce" in password field
+    And I click on the login button
+    Then I should be navigated to the products page
+
+  @test-2
+  Scenario: User cannot log in with invalid credentials
+    When I enter "invalid_user" in username field
+    And I enter "invalid_password" in password field
+    And I click on the login button
+    Then the login should fail
+
+  # ── Scenario Outline ───────────────────────────────────────────────────────
+  # Runs once per row in the Examples table.
+  # Use <placeholder> in steps to reference column headers.
+  @test-3
+  Scenario Outline: User login attempts with different credentials
+    When I enter "<username>" in username field
+    And I enter "<password>" in password field
+    And I click on the login button
+    Then the login outcome should be "<outcome>"
+
+    Examples:
+      | username        | password     | outcome |
+      | standard_user   | secret_sauce | success |
+      | locked_out_user | secret_sauce | failure |
+      | invalid_user    | wrong_pass   | failure |
+
+  # ── Data Table ─────────────────────────────────────────────────────────────
+  # Pass structured data directly into a step.
+  # Access rows in your step definition via dataTable.hashes().
+  @test-4
+  Scenario: User can log in using a data table
+    When I fill in the login form:
+      | field    | value         |
+      | username | standard_user |
+      | password | secret_sauce  |
+    Then I should be navigated to the products page

package/backend/_scaffold/pages/HomepagePage.ts

@@ -0,0 +1,7 @@
+import { page } from '../utils/browser';
+
+export class HomepagePage {
+	static async iShouldBeNavigatedToTheProductsPage() {
+		await page().waitForSelector('.title');
+	}
+}

package/backend/_scaffold/pages/LoginPage.ts

@@ -1,24 +1,48 @@
-// loginPage.ts
-import test, { Page } from '@playwright/test';
+import test from '@playwright/test';
+import { page } from '../utils/browser';
 import { SAMPLE_CONSTANT } from '../utils/constants';
 import { Utils } from '../utils/utils';
 
 export class LoginPage {
-	private page: Page;
-	private utils: Utils;
+	static async goToLoginPage() {
+		console.log(SAMPLE_CONSTANT);
+		await Utils.goToPage(process.env.BASE_URL as string);
+		await page().waitForTimeout(3000);
+	}
 
-	constructor(page: Page) {
-		this.page = page;
-		this.utils = new Utils(this.page);
+	static async skipTest() {
+		test.skip();
 	}
 
-	async goToLoginPage() {
-		console.log(SAMPLE_CONSTANT);
-		await this.utils.goToPage(process.env.BASE_URL as string);
-		await this.page.waitForTimeout(3000);
+	static async iEnterUsername(username: string) {
+		await page().fill('#user-name', username);
 	}
 
-	async skipTest() {
-		test.skip();
+	static async iEnterPassword(password: string) {
+		await page().fill('#password', password);
+	}
+
+	static async iClickOnTheLoginButton() {
+		await page().click('#login-button');
+	}
+
+	static async fillLoginForm(fields: { field: string; value: string }[]) {
+		for (const { field, value } of fields) {
+			if (field === 'username') await page().fill('#user-name', value);
+			if (field === 'password') await page().fill('#password', value);
+		}
+		await page().click('#login-button');
+	}
+
+	static async verifyLoginOutcome(outcome: string) {
+		if (outcome === 'success') {
+			await page().waitForSelector('.title');
+		} else {
+			await page().waitForSelector('.error-message-container');
+		}
+	}
+
+	static async verifyLoginFailed() {
+		await page().waitForSelector('.error-message-container');
 	}
 }

package/backend/_scaffold/step_definitions/HomepageSteps.ts

@@ -0,0 +1,6 @@
+import { Then } from '@cucumber/cucumber';
+import { HomepagePage } from '../pages/HomepagePage';
+
+Then('I should be navigated to the products page', async () => {
+	await HomepagePage.iShouldBeNavigatedToTheProductsPage();
+});

package/backend/_scaffold/step_definitions/LoginSteps.ts

@@ -1,9 +1,35 @@
-import { Given } from '@cucumber/cucumber';
+import { Given, When, Then, DataTable } from '@cucumber/cucumber';
+import { LoginPage } from '../pages/LoginPage';
 
-Given('I am in Demo Sauce Login page', async function () {
-	await this.loginPage.goToLoginPage();
+Given('I am in Demo Sauce Login page', async () => {
+	await LoginPage.goToLoginPage();
 });
 
-Given('I fail this test', async function () {
+Given('I fail this test', async () => {
 	throw new Error('err');
 });
+
+When('I enter {string} in username field', async (username: string) => {
+	await LoginPage.iEnterUsername(username);
+});
+
+When('I enter {string} in password field', async (password: string) => {
+	await LoginPage.iEnterPassword(password);
+});
+
+When('I click on the login button', async () => {
+	await LoginPage.iClickOnTheLoginButton();
+});
+
+When('I fill in the login form:', async (dataTable: DataTable) => {
+	const fields = dataTable.hashes() as { field: string; value: string }[];
+	await LoginPage.fillLoginForm(fields);
+});
+
+Then('the login outcome should be {string}', async (outcome: string) => {
+	await LoginPage.verifyLoginOutcome(outcome);
+});
+
+Then('the login should fail', async () => {
+	await LoginPage.verifyLoginFailed();
+});

package/backend/_scaffold/utils/browser.ts

@@ -0,0 +1,33 @@
+import { chromium, Browser, BrowserContext, Page } from 'playwright';
+
+let _browser: Browser;
+let _context: BrowserContext;
+let _page: Page;
+
+export const page = (): Page => _page;
+
+export async function setup(): Promise<void> {
+	const isHeadless = process.env.IS_HEADLESS?.toLowerCase() !== 'false';
+	_browser = await chromium.launch({ headless: isHeadless });
+	_context = await _browser.newContext();
+	_page = await _context.newPage();
+}
+
+export async function teardown(
+	attach: (data: Buffer, mime: string) => Promise<void>,
+	failed: boolean
+): Promise<void> {
+	if (failed && _page) {
+		const screenshotDir = 'reports/screenshots';
+		const fs = await import('fs');
+		const path = await import('path');
+		if (!fs.existsSync(screenshotDir)) {
+			fs.mkdirSync(screenshotDir, { recursive: true });
+		}
+		const screenshotPath = path.join(screenshotDir, `screenshot_${Date.now()}.png`);
+		await _page.screenshot({ path: screenshotPath });
+		const screenshotData = fs.readFileSync(screenshotPath);
+		await attach(screenshotData, 'image/png');
+	}
+	await _browser?.close();
+}

package/backend/_scaffold/utils/hooks.ts

@@ -1,36 +1,15 @@
-import { Before, After, setWorldConstructor, ITestCaseHookParameter } from '@cucumber/cucumber';
-import { chromium } from 'playwright';
-import fs from 'fs';
-import path from 'path';
-import { CustomWorld } from './world';
+import { Before, After, ITestCaseHookParameter } from '@cucumber/cucumber';
+import { setup, teardown } from './browser';
 import dotenv from 'dotenv';
 
 dotenv.config();
-setWorldConstructor(CustomWorld);
 
-Before(async function (this: CustomWorld) {
-	const isHeadless = process.env.IS_HEADLESS?.toLowerCase() !== 'false';
-
-	this.browser = await chromium.launch({ headless: isHeadless });
-	this.context = await this.browser.newContext();
-	this.page = await this.context.newPage();
-
-	this.initPages(this.page);
+Before(async ({ pickle }: ITestCaseHookParameter) => {
+	const tags = pickle.tags.map((t) => t.name).join(' ');
+	console.log(`\n▶ ${pickle.name}${tags ? `  ${tags}` : ''}`);
+	await setup();
 });
 
-After(async function (this: CustomWorld, scenario: ITestCaseHookParameter) {
-	if (scenario.result?.status === 'FAILED' && this.page) {
-		const screenshotDir = path.join('reports', 'screenshots');
-		if (!fs.existsSync(screenshotDir)) {
-			fs.mkdirSync(screenshotDir, { recursive: true });
-		}
-
-		const screenshotPath = path.join(screenshotDir, `screenshot_${Date.now()}.png`);
-		await this.page.screenshot({ path: screenshotPath });
-
-		const screenshotData = fs.readFileSync(screenshotPath);
-		await this.attach(screenshotData, 'image/png');
-	}
-
-	await this.browser?.close();
+After(async function (scenario: ITestCaseHookParameter) {
+	await teardown(this.attach.bind(this), scenario.result?.status === 'FAILED');
 });

package/backend/_scaffold/utils/utils.ts

@@ -1,13 +1,7 @@
-import { Page } from '@playwright/test';
+import { page } from './browser';
 
 export class Utils {
-	private page: Page;
-
-	constructor(page: Page) {
-		this.page = page;
-	}
-
-	async goToPage(url: string) {
-		await this.page.goto(url);
+	static async goToPage(url: string) {
+		await page().goto(url);
 	}
 }

package/backend/config/scripts/create-settings.js

@@ -17,18 +17,14 @@
 
 const fs = require('fs');
 const path = require('path');
-const fse = require('fs-extra'); // fs-extra for directory copying
+const fse = require('fs-extra');
+const pc = require('picocolors');
 
-// Path to the settings.json file inside the backend/config directory
 const settingsFilePath = path.join(process.cwd(), 'config', 'settings.json');
 const scaffoldFolderPath = path.join(process.cwd(), '_scaffold');
 const userTestsFolderPath = path.join(process.cwd(), 'tests');
 
-// Check if the settings.json file exists
 if (!fs.existsSync(settingsFilePath)) {
-	console.log('⚠️ settings.json not found. Creating it with default values...');
-
-	// Default content for settings.json
 	const settingsContent = JSON.stringify(
 		{
 			reportsHistory: 20,
@@ -42,19 +38,16 @@ if (!fs.existsSync(settingsFilePath)) {
 		null,
 		2
 	);
-
-	// Write the settings to the settings.json file
 	fs.writeFileSync(settingsFilePath, settingsContent, 'utf8');
-	console.log('✅ settings.json created with default values.');
+	console.log(pc.green('✓') + ' settings.json created with default values.');
 } else {
-	console.log('⚠️ settings.json already exists. Skipping creation.');
+	console.log(pc.yellow('⚠') + ' settings.json already exists. Skipping creation.');
 }
 
-// Check if the tests folder exists, if not, copy the scaffold folder as tests
 if (!fs.existsSync(userTestsFolderPath)) {
-	console.log('🧪 `tests/` folder not found. Creating `tests/` from the scaffold folder...');
+	console.log(pc.cyan('↳') + ' tests/ not found. Creating from scaffold...');
 	fse.copySync(scaffoldFolderPath, userTestsFolderPath);
-	console.log('✅ `tests/` folder created from scaffold.');
+	console.log(pc.green('✓') + ' tests/ created from scaffold.');
 } else {
-	console.log('⚠️ `tests/` folder already exists. Skipping creation.');
+	console.log(pc.yellow('⚠') + ' tests/ already exists. Skipping creation.');
 }