playwright-cucumber-ts-steps 0.1.6 → 1.0.0

package/README.md

@@ -1,17 +1,22 @@
 # 🎭 playwright-cucumber-ts-steps
 
-[![npm version](https://img.shields.io/npm/v/playwright-cucumber-ts-steps.svg)](https://www.npmjs.com/package/playwright-cucumber-ts-steps)
-[![license](https://img.shields.io/npm/l/playwright-cucumber-ts-steps.svg)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/blob/main/LICENSE)
-[![build](https://img.shields.io/github/actions/workflow/status/qaPaschalE/playwright-cucumber-ts-steps/ci.yml?branch=main)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/actions)
-[![types](https://img.shields.io/npm/types/playwright-cucumber-ts-steps.svg)](https://www.npmjs.com/package/playwright-cucumber-ts-steps)
-[![GitHub issues](https://img.shields.io/github/issues/qaPaschalE/playwright-cucumber-ts-steps)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/issues)
-[![GitHub stars](https://img.shields.io/github/stars/qaPaschalE/playwright-cucumber-ts-steps)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/stargazers)
+[![NPM](https://nodei.co/npm/playwright-cucumber-ts-steps.png?downloads=true&downloadRank=true&stars=true&height=3)](https://nodei.co/npm/playwright-cucumber-ts-steps/)
 
-> A collection of reusable Playwright step definitions for Cucumber in TypeScript, designed to streamline end-to-end testing across web, API, and mobile applications.
+<table align="center" style="margin-bottom:30px;"><tr><td align="center" width="9999" heigth="9999" >
+ <img src="https://github.com/qaPaschalE/k6-cucumber-steps/blob/main/assets/paschal%20logo%20(2).png?raw=true" alt="paschal Logo" style="margin-top:25px;" align="center"/>
+</td></tr></table>
 
-Here's the updated **README** with all the latest features and corrections integrated into your `playwright-cucumber-ts-steps` package:
+[![npm](https://img.shields.io/npm/v/playwright-cucumber-ts-steps?logo=npm)](https://www.npmjs.com/package/playwright-cucumber-ts-steps)
+[![License](https://img.shields.io/github/license/qaPaschalE/playwright-cucumber-ts-steps?logo=github)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E=18-green?logo=node.js)](https://nodejs.org/)
+[![Build Status](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/actions)
+[![TypeScript](https://img.shields.io/badge/types-TypeScript-blue?logo=typescript)](https://www.npmjs.com/package/playwright-cucumber-ts-steps)
+[![Issues](https://img.shields.io/github/issues/qaPaschalE/playwright-cucumber-ts-steps?logo=github)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/issues)
+[![Stars](https://img.shields.io/github/stars/qaPaschalE/playwright-cucumber-ts-steps?logo=github)](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/stargazers)
 
----
+> A collection of reusable Playwright step definitions for Cucumber in TypeScript, designed to streamline end-to-end testing across web, API, and mobile applications.
+
+> **Note:** This package is designed for advanced Cucumber+Playwright+TypeScript setups. For basic Playwright usage, see the [official Playwright docs](https://playwright.dev/).
 
 ## ✨ Features
 
@@ -54,6 +59,10 @@ npm install --save-dev @playwright/test @cucumber/cucumber typescript ts-node
 npx playwright install
 ```
 
+## 📘 Step Definition Documentation
+
+👉 [View Steps Documentation](https://qapaschale.github.io/playwright-cucumber-ts-steps/) and [examples](https://github.com/qaPaschale/playwright-cucumber-ts-steps/tree/master/playwright/e2e).
+
 ---
 
 ## 🛠️ Usage
@@ -229,8 +238,9 @@ const ARTIFACT_DIR = process.env.TEST_ARTIFACT_DIR || "test-artifacts";
 const defaultWorldParams = {
   artifactDir: ARTIFACT_DIR,
   payloadDir: "payloads",
-  enableScreenshots: process.env.ENABLE_SCREENSHOTS !== "false",
-  enableVideos: process.env.ENABLE_VIDEOS !== "false",
+  enableTrace: process.env.ENABLE_TRACE || "fail", // "false" | "fail" | "all"
+  enableScreenshots: process.env.ENABLE_SCREENSHOTS || "fail", // "false" | "fail" | "all"
+  enableVideos: process.env.ENABLE_VIDEOS || "all", // "false" | "fail" | "all"
   enableVisualTest: process.env.ENABLE_VISUAL_TEST === "true",
   device: process.env.MOBILE_DEVICE || undefined, // e.g., "Pixel 5"
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-cucumber-ts-steps",
-  "version": "0.1.6",
+  "version": "1.0.0",
   "description": "A collection of reusable Playwright step definitions for Cucumber in TypeScript, designed to streamline end-to-end testing across web, API, and mobile applications.",
   "type": "commonjs",
   "main": "lib/index.js",
@@ -26,7 +26,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "docs": "typedoc src",
+    "docs": "typedoc",
+    "docs:deploy": "gh-pages -d temp-docs",
     "prepare": "husky",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
@@ -79,6 +80,10 @@
     "@cucumber/cucumber": "*",
     "@playwright/test": "*"
   },
+  "files": [
+    "lib/",
+    "src/"
+  ],
   "dependencies": {
     "@cucumber/tag-expressions": "^6.2.0",
     "@faker-js/faker": "^9.8.0",
@@ -96,10 +101,12 @@
     "eslint": "^9.29.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-plugin-import": "^2.32.0",
+    "gh-pages": "^6.3.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.2",
     "prettier": "^3.5.3",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.5",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.34.1"
   }

package/src/actions/clickSteps.ts

@@ -0,0 +1,429 @@
+// e2e/step_definitions/common/actions/clickSteps.ts
+import { When, DataTable } from "@cucumber/cucumber";
+import { parseClickOptions } from "../helpers/utils/optionsUtils";
+import { CustomWorld } from "../helpers/world";
+
+/**
+ * Clicks on the previously stored element.
+ *
+ * ```gherkin
+ * When I click
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click
+ * ```
+ * @remarks
+ * Requires a previous step that stores an element.
+ * @category Click Steps
+ */
+export async function When_I_click(this: CustomWorld, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  if (!this.element) throw new Error("❌ No stored element to click.");
+  await this.element.click(options);
+  this.log?.("🖱️ Clicked on stored element");
+}
+When("I click", When_I_click);
+
+/**
+ * Clicks on an element matching the given selector.
+ *
+ * ```gherkin
+ * When I click on element {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on element ".my-class"
+ * ```
+ * @remarks
+ * Stores the clicked element for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_element(this: CustomWorld, selector: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const element = this.getLocator(selector);
+  await element.click(options);
+  this.element = element;
+  this.log?.(`🖱️ Clicked on element "${selector}"`);
+}
+When("I click on element {string}", When_I_click_on_element);
+
+/**
+ * Clicks on a button with the given label.
+ *
+ * ```gherkin
+ * When I click on button {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on button "Submit"
+ * ```
+ * @remarks
+ * Stores the clicked button for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_button(this: CustomWorld, label: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const button = await this.page.getByRole("button", { name: label });
+  await button.click(options);
+  this.element = button;
+  this.log?.(`🖱️ Clicked on button "${label}"`);
+}
+When("I click on button {string}", When_I_click_on_button);
+
+/**
+ * Clicks on a link with the given text.
+ *
+ * ```gherkin
+ * When I click on link {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on link "Home"
+ * ```
+ * @remarks
+ * Stores the clicked link for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_link(this: CustomWorld, text: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const link = await this.page.getByRole("link", { name: text });
+  await link.click(options);
+  this.element = link;
+  this.log?.(`✅ Clicked on link "${text}"`);
+}
+When("I click on link {string}", When_I_click_on_link);
+
+/**
+ * Clicks on a label with the given text.
+ *
+ * ```gherkin
+ * When I click on label {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on label "Username"
+ * ```
+ * @remarks
+ * Stores the clicked label for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_label(this: CustomWorld, labelText: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const label = await this.page.getByLabel(labelText);
+  await label.click(options);
+  this.element = label;
+  this.log?.(`🏷️ Clicked on label "${labelText}"`);
+}
+When("I click on label {string}", When_I_click_on_label);
+
+/**
+ * Clicks on an element containing the given text (not exact match). Supports aliasing with @alias.
+ *
+ * ```gherkin
+ * When I click on text {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on text "Welcome"
+ * When I click on text "@username"
+ * ```
+ * @remarks
+ * Stores the clicked element for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_text(this: CustomWorld, rawText: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+
+  let text = rawText;
+  if (rawText.startsWith("@")) {
+    const alias = rawText.slice(1);
+    text = this.data[alias];
+    if (!text) throw new Error(`❌ No value found for alias "@${alias}"`);
+  }
+
+  const locator = this.page.getByText(text, { exact: false });
+  await locator.first().waitFor({ state: "visible", timeout: 5000 });
+  await locator.first().click(options);
+
+  this.element = locator.first();
+  this.log?.(`🖱️ Clicked on text "${text}"`);
+}
+When("I click on text {string}", When_I_click_on_text);
+
+/**
+ * Clicks on an element containing the exact given text.
+ *
+ * ```gherkin
+ * When I click on exact text {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on exact text "Log out"
+ * ```
+ * @remarks
+ * Stores the clicked element for later use.
+ * @category Click Steps
+ */
+export async function When_I_click_on_exact_text(
+  this: CustomWorld,
+  exactText: string,
+  ...rest: any[]
+) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const locator = this.page.getByText(exactText, { exact: true });
+  await locator.waitFor({ state: "visible", timeout: 5000 });
+  await locator.click(options);
+  this.element = locator;
+  this.log?.(`🖱️ Clicked on exact text "${exactText}"`);
+}
+When("I click on exact text {string}", When_I_click_on_exact_text);
+
+/**
+ * Clicks all previously stored elements.
+ *
+ * ```gherkin
+ * When I click all
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click all
+ * ```
+ * @remarks
+ * Requires a previous step that stores elements.
+ * @category Click Steps
+ */
+export async function When_I_click_all(this: CustomWorld, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  if (!this.elements) throw new Error("❌ No stored elements to click.");
+  const count = await this.elements.count();
+  if (count === 0) throw new Error("⚠️ No elements found to click.");
+  for (let i = 0; i < count; i++) {
+    const el = this.elements.nth(i);
+    await el.waitFor({ state: "visible", timeout: 5000 });
+    await el.click(options);
+    this.log?.(`🖱️ Clicked element #${i + 1}`);
+  }
+  this.log?.(`✅ Clicked all ${count} elements.`);
+}
+When("I click all", When_I_click_all);
+
+/**
+ * Double-clicks on an element containing the given text.
+ *
+ * ```gherkin
+ * When I double click on text {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I double click on text "Edit"
+ * ```
+ * @remarks
+ * Uses the previously stored element if available.
+ * @category Click Steps
+ */
+export async function When_I_double_click_on_text(this: CustomWorld, text: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const element = this.element || this.page.getByText(text);
+  await element.dblclick(options);
+  this.log?.(`🖱️ Double-clicked on text "${text}"`);
+}
+When("I double click on text {string}", When_I_double_click_on_text);
+
+/**
+ * Double-clicks at the given page coordinates.
+ *
+ * ```gherkin
+ * When I double click position {int} {int}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I double click position 100 200
+ * ```
+ * @category Click Steps
+ */
+export async function When_I_double_click_position(
+  this: CustomWorld,
+  x: number,
+  y: number,
+  ...rest: any[]
+) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  await this.page.mouse.dblclick(x, y, options);
+  this.log?.(`🖱️ Double-clicked at (${x}, ${y})`);
+}
+When("I double click position {int} {int}", When_I_double_click_position);
+
+/**
+ * Double-clicks on the previously stored element.
+ *
+ * ```gherkin
+ * When I double click
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I double click
+ * ```
+ * @remarks
+ * Requires a previous step that stores an element.
+ * @category Click Steps
+ */
+export async function When_I_double_click(this: CustomWorld, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  if (!this.element) throw new Error("❌ No stored element to double-click.");
+  await this.element.dblclick(options);
+  this.log?.("🖱️ Double-clicked on stored element");
+}
+When("I double click", When_I_double_click);
+
+/**
+ * Right-clicks on the previously stored element.
+ *
+ * ```gherkin
+ * When I right click
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I right click
+ * ```
+ * @remarks
+ * Requires a previous step that stores an element.
+ * @category Click Steps
+ */
+export async function When_I_right_click(this: CustomWorld, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  if (!this.element) throw new Error("❌ No stored element to right-click.");
+  await this.element.click({ button: "right", ...options });
+  this.log?.("🖱️ Right-clicked on stored element");
+}
+When("I right click", When_I_right_click);
+
+/**
+ * Right-clicks on an element containing the given text.
+ *
+ * ```gherkin
+ * When I right click on text {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I right click on text "Options"
+ * ```
+ * @category Click Steps
+ */
+export async function When_I_right_click_on_text(this: CustomWorld, text: string, ...rest: any[]) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  const element = this.page.getByText(text);
+  await element.click({ button: "right", ...options });
+  this.log?.(`🖱️ Right-clicked on text "${text}"`);
+}
+When("I right click on text {string}", When_I_right_click_on_text);
+
+/**
+ * Right-clicks at the given page coordinates.
+ *
+ * ```gherkin
+ * When I right click position {int} {int}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I right click position 50 50
+ * ```
+ * @category Click Steps
+ */
+export async function When_I_right_click_position(
+  this: CustomWorld,
+  x: number,
+  y: number,
+  ...rest: any[]
+) {
+  const maybeTable = rest[0];
+  const options = maybeTable?.rowsHash ? parseClickOptions(maybeTable) : {};
+  await this.page.mouse.click(x, y, { button: "right", ...options });
+  this.log?.(`🖱️ Right-clicked at (${x}, ${y})`);
+}
+When("I right click position {int} {int}", When_I_right_click_position);
+
+/**
+ * Clicks all stored elements (alternative signature).
+ *
+ * ```gherkin
+ * When I click all
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click all
+ * ```
+ * @remarks
+ * Requires a previous step that stores elements.
+ * @category Click Steps
+ */
+export async function When_I_click_all_alt(this: CustomWorld, dataTable?: DataTable) {
+  const options = parseClickOptions(dataTable);
+
+  if (!this.elements) {
+    throw new Error("❌ No elements stored. Use a 'find' step before 'I click all'.");
+  }
+
+  const count = await this.elements.count();
+  if (count === 0) {
+    throw new Error("⚠️ Stored elements are empty. Nothing to click.");
+  }
+
+  for (let i = 0; i < count; i++) {
+    const element = this.elements.nth(i);
+    await element.waitFor({ state: "visible", timeout: 5000 });
+    await element.click(options);
+    this.log?.(`🖱️ Clicked element #${i + 1}`);
+  }
+
+  this.log?.(`✅ Clicked all ${count} stored elements.`);
+}
+When("I click all", When_I_click_all_alt);
+
+/**
+ * Clicks on an element matching the given selector (regex step).
+ *
+ * ```gherkin
+ * When I click on selector {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I click on selector ".my-selector"
+ * ```
+ * @category Click Steps
+ */
+export async function When_I_click_on_selector(this: CustomWorld, selector: string) {
+  const locator = this.getLocator(selector);
+  await locator.click();
+  this.log?.(`🖱️ Clicked on selector: ${selector}`);
+}
+When(/^I click on selector "([^"]+)"$/, When_I_click_on_selector);

package/src/actions/cookieSteps.ts

@@ -0,0 +1,95 @@
+// e2e/step_definitions/common/actions/cookieSteps.ts
+import { When } from "@cucumber/cucumber";
+
+/**
+ * @step
+ * @description Clears all cookies in the current browser context.
+ * @example
+ * When I clear all cookies
+ */
+When("I clear all cookies", async function () {
+  await this.page.context().clearCookies();
+  this.log("Cleared all cookies");
+});
+
+/**
+ * @step
+ * @description Clears all cookies in the current browser context (alias).
+ * @example
+ * When I clear cookies
+ */
+When("I clear cookies", async function () {
+  await this.page.context().clearCookies();
+  this.log("Cleared cookies (alias)");
+});
+
+/**
+ * @step
+ * @description Clears a specific cookie by name.
+ * @example
+ * When I clear cookie "session_id"
+ */
+When("I clear cookie {string}", async function (name: string) {
+  await this.page.context().addCookies([
+    {
+      name,
+      value: "",
+      domain: new URL(this.page.url()).hostname,
+      path: "/",
+      expires: 0,
+    },
+  ]);
+  this.log(`Cleared cookie: ${name}`);
+});
+
+/**
+ * @step
+ * @description Logs all cookies in the current browser context to the console.
+ * @example
+ * When I log all cookies
+ */
+When("I log all cookies", async function () {
+  const cookies = await this.page.context().cookies();
+  console.log("Cookies:", cookies);
+});
+
+/**
+ * @step
+ * @description Sets a cookie with the given name and value for the current domain.
+ * @example
+ * When I set cookie "session_id" to "abc123"
+ * @remarks
+ * The cookie is set for the current page's domain and path "/".
+ * @category Cookie Steps
+ */
+export async function When_I_set_cookie(this: any, name: string, value: string) {
+  const url = new URL(this.page.url());
+  await this.page.context().addCookies([
+    {
+      name,
+      value,
+      domain: url.hostname,
+      path: "/",
+      expires: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+      httpOnly: false,
+      secure: false,
+      sameSite: "Lax",
+    },
+  ]);
+  this.log?.(`Set cookie: ${name}=${value}`);
+}
+When("I set cookie {string} to {string}", When_I_set_cookie);
+
+/**
+ * @step
+ * @description Gets a cookie value by name and logs it.
+ * @example
+ * When I get cookie "session_id"
+ * @category Cookie Steps
+ */
+export async function When_I_get_cookie(this: any, name: string) {
+  const cookies = await this.page.context().cookies();
+  const found = cookies.find((c: any) => c.name === name);
+  this.log?.(`Cookie "${name}": ${found ? found.value : "not found"}`);
+}
+When("I get cookie {string}", When_I_get_cookie);

package/src/actions/debugSteps.ts

@@ -0,0 +1,21 @@
+// e2e/step_definitions/common/actions/debugSteps.ts
+import { When } from "@cucumber/cucumber";
+
+/**
+ * Pauses the test execution for debugging with a custom message.
+ *
+ * ```gherkin
+ * When I debug with message {string}
+ * ```
+ *
+ * @example
+ * ```gherkin
+ * When I debug with message "Check login form"
+ * ```
+ * @category Debug Steps
+ */
+export async function When_I_debug_with_message(this: any, message: string) {
+  await this.page.pause();
+  this.log?.(`Paused test for debugging: ${message}`);
+}
+When("I debug with message {string}", When_I_debug_with_message);