playwright-cucumber-ts-steps 0.1.7 → 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.7",
+  "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

@@ -3,94 +3,212 @@ import { When, DataTable } from "@cucumber/cucumber";
 import { parseClickOptions } from "../helpers/utils/optionsUtils";
 import { CustomWorld } from "../helpers/world";
 
-When("I click", async function (this: CustomWorld, ...rest: any[]) {
+/**
+ * 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 on element {string}",
-  async function (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 button {string}",
-  async function (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", 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);
 
-When("I click on link {string}", async function (this: CustomWorld, text: string, ...rest: any[]) {
+/**
+ * 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 label {string}",
-  async function (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 text {string}",
-  async function (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 exact text {string}",
-  async function (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 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}"`);
   }
-);
 
-When("I click all", async function (this: CustomWorld, ...rest: any[]) {
+  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.");
@@ -103,83 +221,171 @@ When("I click all", async function (this: CustomWorld, ...rest: any[]) {
     this.log?.(`🖱️ Clicked element #${i + 1}`);
   }
   this.log?.(`✅ Clicked all ${count} elements.`);
-});
-
-When(
-  "I double click on text {string}",
-  async function (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 position {int} {int}",
-  async function (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 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);
 
-When("I double click", async function (this: CustomWorld, ...rest: any[]) {
+/**
+ * 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);
 
-When("I right click", async function (this: CustomWorld, ...rest: any[]) {
+/**
+ * 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 on text {string}",
-  async function (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 position {int} {int}",
-  async function (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 blur", async function (this: CustomWorld) {
-  await this.page.evaluate(() => {
-    const active = document.activeElement;
-    if (active && typeof (active as HTMLElement).blur === "function") {
-      (active as HTMLElement).blur();
-    }
-  });
-  this.log?.("🌀 Blurred active element");
-});
-
-When("I focus", async function (this: CustomWorld) {
-  if (!this.element) throw new Error("❌ No stored element to focus.");
-  await this.element.focus();
-  this.log?.("🎯 Focused stored element");
-});
-
-When("I click all", async function (this: CustomWorld, dataTable?: DataTable) {
+}
+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) {
@@ -199,9 +405,25 @@ When("I click all", async function (this: CustomWorld, dataTable?: DataTable) {
   }
 
   this.log?.(`✅ Clicked all ${count} stored elements.`);
-});
-When(/^I click on selector "([^"]+)"$/, async function (this: CustomWorld, selector: string) {
+}
+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);