plum-e2e 1.0.3 → 1.0.5

package/README.md

@@ -1,5 +1,66 @@
 ![alt-text="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>
+</p>
+
+## 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!
+
+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.
+
 **_I. How to Run:_**
+
+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`
+   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
+
+## Basic Structure
+
+After you run `plum init`, these files will be created inside your project directory.
+
+<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
+</pre>
+
+## Tutorial
+
+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.
+
+## For Developers/Contributors
+
+For people that want to contribute to the project
+
+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
+
+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)

package/backend/_scaffold/pages/LoginPage.ts

@@ -0,0 +1,24 @@
+// loginPage.ts
+import test, { Page } from '@playwright/test';
+import { SAMPLE_CONSTANT } from '../utils/constants';
+import { Utils } from '../utils/utils';
+
+export class LoginPage {
+	private page: Page;
+	private utils: Utils;
+
+	constructor(page: Page) {
+		this.page = page;
+		this.utils = new Utils(this.page);
+	}
+
+	async goToLoginPage() {
+		console.log(SAMPLE_CONSTANT);
+		await this.utils.goToPage(process.env.BASE_URL as string);
+		await this.page.waitForTimeout(3000);
+	}
+
+	async skipTest() {
+		test.skip();
+	}
+}

package/backend/_scaffold/step_definitions/{LoginSteps.js → LoginSteps.ts}

@@ -1,4 +1,4 @@
-const { Given, When, Then } = require('@cucumber/cucumber');
+import { Given } from '@cucumber/cucumber';
 
 Given('I am in Demo Sauce Login page', async function () {
 	await this.loginPage.goToLoginPage();

package/backend/_scaffold/utils/constants.ts

@@ -0,0 +1 @@
+export const SAMPLE_CONSTANT = 'this is a constant';

package/backend/_scaffold/utils/hooks.ts

@@ -0,0 +1,36 @@
+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 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);
+});
+
+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();
+});

package/backend/_scaffold/utils/utils.ts

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

package/backend/_scaffold/utils/world.ts

@@ -0,0 +1,25 @@
+import { IWorldOptions, setWorldConstructor, World } from '@cucumber/cucumber';
+import { Browser, Page, BrowserContext } from 'playwright';
+import { LoginPage } from '../pages/LoginPage';
+import { Utils } from './utils';
+
+export class CustomWorld extends World {
+	browser!: Browser;
+	context!: BrowserContext;
+	page!: Page;
+
+	loginPage!: LoginPage;
+	utils!: Utils;
+
+	constructor(options: IWorldOptions) {
+		super(options);
+	}
+
+	initPages(page: Page) {
+		this.utils = new Utils(page);
+		this.loginPage = new LoginPage(page);
+		// Add other pages here
+	}
+}
+
+setWorldConstructor(CustomWorld);

package/backend/config/scripts/run-tests.js

@@ -16,19 +16,32 @@
  */
 
 const { execSync } = require('child_process');
-const tag = process.env.TAG; // Read the TAG environment variable
+const tag = process.env.TAG;
 
 try {
-	// Run the tests with the tag filter, only if a tag is provided
-	const cucumberCommand = tag
-		? `cucumber-js tests/features/**/*.feature --format json:reports/cucumber_report.json --tags "${tag}"`
-		: `cucumber-js tests/features/**/*.feature --format json:reports/cucumber_report.json`;
+	const baseCommand = [
+		'npx',
+		'cross-env',
+		'TS_NODE_TRANSPILE_ONLY=true',
+		'cucumber-js',
+		'tests/features/**/*.feature',
+		'--require-module',
+		'ts-node/register',
+		'--require',
+		'tests/step_definitions/**/*.ts',
+		'--format',
+		'json:reports/cucumber_report.json'
+	];
 
+	if (tag) {
+		baseCommand.push('--tags', `"${tag}"`);
+	}
+
+	const cucumberCommand = baseCommand.join(' ');
 	execSync(cucumberCommand, { stdio: 'inherit' });
 } catch (error) {
 	console.error('Tests failed:', error.message);
 } finally {
-	// Always run the report generation after tests (even if they fail)
 	try {
 		execSync('node config/scripts/generate-report.js', { stdio: 'inherit' });
 	} catch (error) {

package/backend/cucumber.json

@@ -1,6 +1,7 @@
 {
 	"default": {
-		"require": ["tests/step_definitions/*.js", "tests/utils/hooks.js"],
-		"featurePaths": ["tests/features/**/*.feature"]
+		"require": ["tests/step_definitions/*.ts", "tests/utils/hooks.ts"],
+		"featurePaths": ["tests/features/**/*.feature"],
+		"requireModule": ["ts-node/register"]
 	}
 }