playwright-cucumber-ts-steps 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chetachi (Paschal) Enyimiri 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# 🎭 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)
+
+> A collection of reusable Playwright step definitions for Cucumber in TypeScript, designed to streamline end-to-end testing across web, API, and mobile applications.
+
+---
+
+## ✨ Features
+
+- 🧩 Plug-and-play Cucumber step definitions
+- 🎯 Support for UI, API, mobile, iframe, session reuse, and visual testing
+- 🗂️ Alias and Faker support for dynamic data
+- 📸 Optional screenshot/video capture and pixel-diff comparison
+- 🤖 Built with modern Playwright + Cucumber ecosystem
+
+---
+
+## 📦 Installation
+
+```bash
+npm install playwright-cucumber-ts-steps
+```
+
+or
+
+```bash
+yarn add playwright-cucumber-ts-steps
+```
+
+---
+
+## 🧠 Prerequisites
+
+Ensure your project is already set up with:
+
+- [`@playwright/test`](https://playwright.dev/)
+- [`@cucumber/cucumber`](https://github.com/cucumber/cucumber-js)
+- TypeScript
+- Cucumber IDE plugin (Optional), but Highly recommended
+
+If not, run:
+
+```bash
+npm install --save-dev @playwright/test @cucumber/cucumber typescript ts-node
+npx playwright install
+```
+
+---
+
+## 🛠️ Usage
+
+1. **Import the step definitions** in your Cucumber environment:
+
+   ```ts
+   // e2e/steps/world.ts
+   import { setWorldConstructor } from "@cucumber/cucumber";
+   import { CustomWorld } from "playwright-cucumber-ts-steps";
+
+   setWorldConstructor(CustomWorld);
+   ```
+
+2. **Load step definitions** from the package:
+
+   ```ts
+   // e2e/steps/index.ts
+   import "playwright-cucumber-ts-steps";
+   ```
+
+   Or import specific step categories:
+
+   ```ts
+   import "playwright-cucumber-ts-steps/src/assertions";
+   import "playwright-cucumber-ts-steps/src/actions";
+   import "playwright-cucumber-ts-steps/src/forms";
+   import "playwright-cucumber-ts-steps/src/api";
+   ```
+
+3. **Use step definitions in your feature files**:
+
+   ```gherkin
+   Feature: Login
+
+     Scenario: User logs in
+       Given I visit "/login"
+       When I find input by name "Email"
+       And I type "user@example.com"
+       And I click button "Login"
+       Then I see visible text "Welcome"
+       Then I do not see URL contains "/login"
+
+   ```
+
+---
+
+## 🧪 Step Categories
+
+- ✅ **Assertions**: `I see text`, `I do not see text`, `I see button`, `I see value`, etc.
+- 🎬 **Actions**: `I click`, `I type`, `I wait`, `I switch to iframe`, etc.
+- 📄 **Forms**: `I fill the following`, aliasing, dynamic faker values
+- 🌐 **API**: Request mocking, assertions, response validation
+- 📱 **Mobile support**: Enable with `@mobile` tag (iPhone 13 emulation)
+- 👁️ **Visual testing**: Enable with `@visual` tag (pixelmatch diff)
+
+---
+
+## 🧰 Customization
+
+You can extend the base `CustomWorld` and define your own steps:
+
+```ts
+// custom-world.ts
+import { CustomWorld as BaseWorld } from "playwright-cucumber-ts-steps";
+
+export class CustomWorld extends BaseWorld {
+  // Add your custom context or helpers here
+}
+```
+
+---
+
+## 🔍 Tags & Aliases
+
+- Use aliases with `@alias` syntax:
+
+  ```gherkin
+  Given I get element by selector "[type='text_selector']"
+  And I store element text as "welcomeText"
+  Then I see "@welcomeText" in the element
+  ```
+
+- Use faker:
+
+  ```gherkin
+  // Here below "Email" represents a faker variable "Email: () => faker.internet.email()", Continue button containing text with action click, best for Forms
+
+   When I fill the following "example form page" form data:
+      | Target         | Value            |
+      | [name='email'] | Email            |
+      | Continue       | Click            |
+  ```
+
+---
+
+## 📸 Advanced Usage
+
+These features are **optional** and can be implemented in your own `hooks.ts`:
+
+- 📷 **Visual regression testing** with pixelmatch
+- 🎥 **Video recording per scenario**
+- 🔐 **Session reuse** using `storageState`
+
+To keep this package focused, no hooks or reporting setup is included directly. See [`e2e/support/hooks.ts`](./e2e/support/hooks.ts) in the example project for reference.
+
+---
+
+## 📁 Folder Structure Suggestion
+
+```text
+e2e/
+├── features/
+├── step_definitions/
+│   └── index.ts          # import from this package
+├── support/
+│   └── world.ts          # extends CustomWorld
+│   └── hooks.ts          # optional
+```
+
+---
+
+## 🧪 Example Project
+
+Want to see it in action?
+
+👉 [https://github.com/qaPaschalE/playwright-cucumber-ts-steps](https://github.com/qaPaschalE/playwright-cucumber-ts-steps)
+
+---
+
+## 🧾 License
+
+[ISC](LICENSE)
+
+---
+
+## 🙋‍♂️ Contributing
+
+Contributions, improvements, and suggestions are welcome! Feel free to open an issue or pull request.
+
+---
+
+## 💬 Questions?
+
+Open an issue on [GitHub Issues](https://github.com/qaPaschalE/playwright-cucumber-ts-steps/issues) or reach out via discussions.

package/dist/helpers/utils/fakerUtils.d.ts

@@ -0,0 +1 @@
+export declare function evaluateFaker(value: string): string;

package/dist/helpers/utils/fakerUtils.js

@@ -0,0 +1,54 @@
+import { faker } from "@faker-js/faker";
+import dayjs from "dayjs";
+const fakerMapping = {
+    "First Name": () => faker.person.middleName(),
+    Name: () => faker.person.middleName(),
+    "Last Name": () => faker.person.middleName(),
+    Email: () => faker.internet.email(),
+    "Phone Number": () => faker.string.numeric(10),
+    Number: () => faker.string.numeric(11),
+    "Complete Number": () => faker.string.numeric(11),
+    "App Colour": () => faker.color.rgb(),
+    "App Name": () => faker.commerce.productName(),
+    "Role Name": () => faker.person.jobTitle(),
+    "Company Name": () => faker.company.name(),
+    "Full Name": () => faker.person.fullName(),
+    "Disposable Email": () => faker.internet.email({ provider: "inboxkitten.com" }),
+    "ALpha Numeric": () => faker.string.numeric(11) + "e",
+    "Lorem Word": () => faker.lorem.sentences({ min: 1, max: 3 }),
+    Word: () => faker.lorem.word({ length: { min: 5, max: 11 } }),
+    "Current Date": () => dayjs().format("YYYY-MM-DD"),
+    "Current Date2": () => new Date().toISOString().split("T")[0],
+    MonthsFromNow: (months) => {
+        const monthsToAdd = parseInt(months || "0", 10);
+        return dayjs().add(monthsToAdd, "month").format("YYYY-MM-DD");
+    },
+    MonthsAgo: (months) => {
+        const monthsToSubtract = parseInt(months || "0", 10);
+        return dayjs().subtract(monthsToSubtract, "month").format("YYYY-MM-DD");
+    },
+    WeeksFromNow: (weeks) => {
+        const weeksToAdd = parseInt(weeks || "0", 10);
+        return dayjs().add(weeksToAdd, "week").format("YYYY-MM-DD");
+    },
+    WeeksAgo: (weeks) => {
+        const weeksToSubtract = parseInt(weeks || "0", 10);
+        return dayjs().subtract(weeksToSubtract, "week").format("YYYY-MM-DD");
+    },
+    DaysFromNow: (days) => {
+        const daysToAdd = parseInt(days || "0", 10);
+        return dayjs().add(daysToAdd, "day").format("YYYY-MM-DD");
+    },
+    DaysAgo: (days) => {
+        const daysToSubtract = parseInt(days || "0", 10);
+        return dayjs().subtract(daysToSubtract, "day").format("YYYY-MM-DD");
+    },
+};
+export function evaluateFaker(value) {
+    const [key, param] = value.split(":");
+    const fn = fakerMapping[key];
+    if (typeof fn === "function") {
+        return fn(param);
+    }
+    return value; // fallback to raw value if not mapped
+}

package/dist/helpers/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./fakerUtils";
+export * from "./optionsUtils";
+export * from "./resolveUtils";

package/dist/helpers/utils/index.js

@@ -0,0 +1,3 @@
+export * from "./fakerUtils";
+export * from "./optionsUtils";
+export * from "./resolveUtils";

package/dist/helpers/utils/optionsUtils.d.ts

@@ -0,0 +1,19 @@
+import type { DataTable } from "@cucumber/cucumber";
+import type { Locator } from "@playwright/test";
+type ClickOptions = Parameters<Locator["click"]>[0];
+type DblClickOptions = Parameters<Locator["dblclick"]>[0];
+type HoverOptions = Parameters<Locator["hover"]>[0];
+type FillOptions = Parameters<Locator["fill"]>[1];
+type TypeOptions = Parameters<Locator["type"]>[1];
+type CheckOptions = Parameters<Locator["check"]>[0];
+type UncheckOptions = Parameters<Locator["uncheck"]>[0];
+type SelectOptionOptions = Parameters<Locator["selectOption"]>[1];
+export declare function parseClickOptions(table?: DataTable): Partial<ClickOptions>;
+export declare function parseDblClickOptions(table?: DataTable): Partial<DblClickOptions>;
+export declare function parseHoverOptions(table?: DataTable): Partial<HoverOptions>;
+export declare function parseTypeOptions(table?: DataTable): Partial<TypeOptions>;
+export declare function parseFillOptions(table?: DataTable): Partial<FillOptions>;
+export declare function parseCheckOptions(table?: DataTable): Partial<CheckOptions>;
+export declare function parseUncheckOptions(table?: DataTable): Partial<UncheckOptions>;
+export declare function parseSelectOptions(table?: DataTable): Partial<SelectOptionOptions>;
+export {};

package/dist/helpers/utils/optionsUtils.js

@@ -0,0 +1,69 @@
+export function parseClickOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseDblClickOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseHoverOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseTypeOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseFillOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseCheckOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseUncheckOptions(table) {
+    return parseGenericOptions(table);
+}
+export function parseSelectOptions(table) {
+    return parseGenericOptions(table);
+}
+function parseGenericOptions(table) {
+    if (!table)
+        return {};
+    const options = {};
+    const rows = table.raw();
+    for (const [key, value] of rows) {
+        switch (key) {
+            case "timeout":
+            case "delay":
+            case "clickCount":
+                options[key] = Number(value);
+                break;
+            case "force":
+            case "noWaitAfter":
+            case "strict":
+            case "trial":
+                options[key] = value === "true";
+                break;
+            case "modifiers":
+                options.modifiers = value
+                    .split(",")
+                    .map((v) => v.trim());
+                break;
+            case "button":
+                if (["left", "middle", "right"].includes(value)) {
+                    options.button = value;
+                }
+                else {
+                    throw new Error(`Invalid button option: "${value}"`);
+                }
+                break;
+            case "position":
+                const [x, y] = value.split(",").map((n) => Number(n.trim()));
+                if (isNaN(x) || isNaN(y)) {
+                    throw new Error(`Invalid position format: "${value}"`);
+                }
+                options.position = { x, y };
+                break;
+            default:
+                console.warn(`[⚠️ parseGenericOptions] Unknown option "${key}"`);
+                break;
+        }
+    }
+    return options;
+}

package/dist/helpers/utils/resolveUtils.d.ts

@@ -0,0 +1,4 @@
+import type { CustomWorld } from "../world";
+export declare function resolveValue(input: string): string;
+export declare function resolveLoginValue(raw: string, world: CustomWorld): string | undefined;
+export declare function deriveSessionName(emailOrUser: string, fallback?: string): string;

package/dist/helpers/utils/resolveUtils.js

@@ -0,0 +1,54 @@
+import fs from "fs";
+import path from "path";
+// Dynamic resolver
+export function resolveValue(input) {
+    // Uppercase = environment variable (e.g. TEST_USER)
+    if (/^[A-Z0-9_]+$/.test(input)) {
+        const envVal = process.env[input];
+        if (!envVal) {
+            throw new Error(`Environment variable ${input} not found.`);
+        }
+        return envVal;
+    }
+    // Dot = JSON reference (e.g. userData.email)
+    if (input.includes(".")) {
+        const [fileName, fieldName] = input.split(".");
+        const jsonPath = path.resolve("e2e/support/helper/test-data", `${fileName}.json`);
+        if (fs.existsSync(jsonPath)) {
+            const json = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+            const value = json[fieldName];
+            if (value !== undefined)
+                return value;
+            throw new Error(`Field "${fieldName}" not found in ${fileName}.json`);
+        }
+    }
+    // Default to hardcoded value
+    return input;
+}
+export function resolveLoginValue(raw, world) {
+    // ✅ Alias: @aliasName
+    if (raw.startsWith("@")) {
+        return world.data[raw.slice(1)];
+    }
+    // ✅ JSON: user.json:key
+    if (raw.includes(".json:")) {
+        const [filename, key] = raw.split(".json:");
+        const filePath = path.resolve("test-data", `${filename}.json`);
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`JSON fixture not found: ${filename}.json`);
+        }
+        const fileData = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return fileData[key];
+    }
+    // ✅ Fallback to raw value
+    return raw;
+}
+// Determine session name from email or username
+export function deriveSessionName(emailOrUser, fallback = "default") {
+    if (!emailOrUser)
+        return `${fallback}User`;
+    const base = emailOrUser.includes("@")
+        ? emailOrUser.split("@")[0]
+        : emailOrUser;
+    return `${base}User`;
+}

package/dist/helpers/world.d.ts

@@ -0,0 +1,18 @@
+import { World, ITestCaseHookParameter } from "@cucumber/cucumber";
+import { Browser, Page, BrowserContext, Locator, FrameLocator } from "@playwright/test";
+export declare class CustomWorld extends World {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    elements?: Locator;
+    element?: Locator;
+    frame?: FrameLocator;
+    data: Record<string, any>;
+    logs: string[];
+    testName?: string;
+    init(testInfo?: ITestCaseHookParameter): Promise<void>;
+    getScope(): Page | FrameLocator;
+    exitIframe(): void;
+    log: (message: string) => void;
+    cleanup(testInfo?: ITestCaseHookParameter): Promise<void>;
+}

package/dist/helpers/world.js

@@ -0,0 +1,60 @@
+// support/world.ts
+import { setWorldConstructor, World, } from "@cucumber/cucumber";
+import { devices, } from "@playwright/test";
+import { chromium } from "playwright";
+import * as dotenv from "dotenv";
+dotenv.config();
+const isHeadless = process.env.HEADLESS !== "false";
+const slowMo = process.env.SLOWMO ? Number(process.env.SLOWMO) : 0;
+export class CustomWorld extends World {
+    constructor() {
+        super(...arguments);
+        this.data = {};
+        this.logs = [];
+        this.log = (message) => {
+            this.logs.push(message);
+            console.log(`[LOG] ${message}`);
+        };
+    }
+    async init(testInfo) {
+        const isMobile = testInfo?.pickle.tags.some((tag) => tag.name === "@mobile");
+        const device = isMobile ? devices["Pixel 5"] : undefined;
+        this.browser = await chromium.launch({ headless: isHeadless, slowMo });
+        this.context = await this.browser.newContext({
+            ...(device || {}),
+            recordVideo: { dir: "e2e/test-artifacts/videos" },
+        });
+        this.page = await this.context.newPage();
+        this.testName = testInfo?.pickle.name;
+        this.log(`🧪 Initialized context${isMobile ? " (mobile)" : ""}`);
+    }
+    getScope() {
+        return this.frame ?? this.page;
+    }
+    exitIframe() {
+        this.frame = undefined;
+        this.log("⬅️ Exited iframe, scope is now main page");
+    }
+    async cleanup(testInfo) {
+        const failed = testInfo?.result?.status === "FAILED";
+        try {
+            await this.page?.close();
+        }
+        catch (err) {
+            this.log(`⚠️ Error closing page: ${err.message}`);
+        }
+        try {
+            await this.context?.close();
+        }
+        catch (err) {
+            this.log(`⚠️ Error closing context: ${err.message}`);
+        }
+        try {
+            await this.browser?.close();
+        }
+        catch (err) {
+            this.log(`⚠️ Error closing browser: ${err.message}`);
+        }
+    }
+}
+setWorldConstructor(CustomWorld);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./src";
+export * from "./helpers/world";
+export * from "./helpers/utils";

package/dist/index.js

@@ -0,0 +1,4 @@
+// index.ts
+export * from "./src";
+export * from "./helpers/world";
+export * from "./helpers/utils";

package/helpers/utils/fakerUtils.ts

@@ -0,0 +1,68 @@
+import { faker } from "@faker-js/faker";
+import dayjs from "dayjs";
+
+// Supports optional parameters
+type FakerMapping = Record<
+  string,
+  ((param?: string) => string) | (() => string)
+>;
+
+const fakerMapping: FakerMapping = {
+  "First Name": () => faker.person.middleName(),
+  Name: () => faker.person.middleName(),
+  "Last Name": () => faker.person.middleName(),
+  Email: () => faker.internet.email(),
+  "Phone Number": () => faker.string.numeric(10),
+  Number: () => faker.string.numeric(11),
+  "Complete Number": () => faker.string.numeric(11),
+  "App Colour": () => faker.color.rgb(),
+  "App Name": () => faker.commerce.productName(),
+  "Role Name": () => faker.person.jobTitle(),
+  "Company Name": () => faker.company.name(),
+  "Full Name": () => faker.person.fullName(),
+  "Disposable Email": () =>
+    faker.internet.email({ provider: "inboxkitten.com" }),
+  "ALpha Numeric": () => faker.string.numeric(11) + "e",
+  "Lorem Word": () => faker.lorem.sentences({ min: 1, max: 3 }),
+  Word: () => faker.lorem.word({ length: { min: 5, max: 11 } }),
+  "Current Date": () => dayjs().format("YYYY-MM-DD"),
+  "Current Date2": () => new Date().toISOString().split("T")[0],
+
+  MonthsFromNow: (months?: string) => {
+    const monthsToAdd = parseInt(months || "0", 10);
+    return dayjs().add(monthsToAdd, "month").format("YYYY-MM-DD");
+  },
+  MonthsAgo: (months?: string) => {
+    const monthsToSubtract = parseInt(months || "0", 10);
+    return dayjs().subtract(monthsToSubtract, "month").format("YYYY-MM-DD");
+  },
+
+  WeeksFromNow: (weeks?: string) => {
+    const weeksToAdd = parseInt(weeks || "0", 10);
+    return dayjs().add(weeksToAdd, "week").format("YYYY-MM-DD");
+  },
+  WeeksAgo: (weeks?: string) => {
+    const weeksToSubtract = parseInt(weeks || "0", 10);
+    return dayjs().subtract(weeksToSubtract, "week").format("YYYY-MM-DD");
+  },
+
+  DaysFromNow: (days?: string) => {
+    const daysToAdd = parseInt(days || "0", 10);
+    return dayjs().add(daysToAdd, "day").format("YYYY-MM-DD");
+  },
+  DaysAgo: (days?: string) => {
+    const daysToSubtract = parseInt(days || "0", 10);
+    return dayjs().subtract(daysToSubtract, "day").format("YYYY-MM-DD");
+  },
+};
+
+export function evaluateFaker(value: string): string {
+  const [key, param] = value.split(":");
+
+  const fn = fakerMapping[key];
+  if (typeof fn === "function") {
+    return fn(param);
+  }
+
+  return value; // fallback to raw value if not mapped
+}

package/helpers/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./fakerUtils";
+export * from "./optionsUtils";
+export * from "./resolveUtils";

package/helpers/utils/optionsUtils.ts

@@ -0,0 +1,106 @@
+//optionsUtils.ts
+import type { DataTable } from "@cucumber/cucumber";
+import type { Locator } from "@playwright/test";
+
+type ClickOptions = Parameters<Locator["click"]>[0];
+type DblClickOptions = Parameters<Locator["dblclick"]>[0];
+type HoverOptions = Parameters<Locator["hover"]>[0];
+type FillOptions = Parameters<Locator["fill"]>[1];
+type TypeOptions = Parameters<Locator["type"]>[1];
+type CheckOptions = Parameters<Locator["check"]>[0];
+type UncheckOptions = Parameters<Locator["uncheck"]>[0];
+type SelectOptionOptions = Parameters<Locator["selectOption"]>[1];
+
+type KeyboardModifier = NonNullable<
+  NonNullable<ClickOptions>["modifiers"]
+>[number];
+
+export function parseClickOptions(table?: DataTable): Partial<ClickOptions> {
+  return parseGenericOptions(table) as Partial<ClickOptions>;
+}
+
+export function parseDblClickOptions(
+  table?: DataTable
+): Partial<DblClickOptions> {
+  return parseGenericOptions(table) as Partial<DblClickOptions>;
+}
+
+export function parseHoverOptions(table?: DataTable): Partial<HoverOptions> {
+  return parseGenericOptions(table) as Partial<HoverOptions>;
+}
+
+export function parseTypeOptions(table?: DataTable): Partial<TypeOptions> {
+  return parseGenericOptions(table) as unknown as Partial<TypeOptions>;
+}
+
+export function parseFillOptions(table?: DataTable): Partial<FillOptions> {
+  return parseGenericOptions(table) as Partial<FillOptions>;
+}
+
+export function parseCheckOptions(table?: DataTable): Partial<CheckOptions> {
+  return parseGenericOptions(table) as Partial<CheckOptions>;
+}
+
+export function parseUncheckOptions(
+  table?: DataTable
+): Partial<UncheckOptions> {
+  return parseGenericOptions(table) as Partial<UncheckOptions>;
+}
+
+export function parseSelectOptions(
+  table?: DataTable
+): Partial<SelectOptionOptions> {
+  return parseGenericOptions(table) as Partial<SelectOptionOptions>;
+}
+
+function parseGenericOptions(table?: DataTable): Record<string, any> {
+  if (!table) return {};
+
+  const options: Record<string, any> = {};
+  const rows = table.raw();
+
+  for (const [key, value] of rows) {
+    switch (key) {
+      case "timeout":
+      case "delay":
+      case "clickCount":
+        options[key] = Number(value);
+        break;
+
+      case "force":
+      case "noWaitAfter":
+      case "strict":
+      case "trial":
+        options[key] = value === "true";
+        break;
+
+      case "modifiers":
+        options.modifiers = value
+          .split(",")
+          .map((v) => v.trim() as KeyboardModifier);
+        break;
+
+      case "button":
+        if (["left", "middle", "right"].includes(value)) {
+          options.button = value;
+        } else {
+          throw new Error(`Invalid button option: "${value}"`);
+        }
+        break;
+
+      case "position":
+        const [x, y] = value.split(",").map((n) => Number(n.trim()));
+        if (isNaN(x) || isNaN(y)) {
+          throw new Error(`Invalid position format: "${value}"`);
+        }
+        options.position = { x, y };
+        break;
+
+      default:
+        console.warn(`[⚠️ parseGenericOptions] Unknown option "${key}"`);
+        break;
+    }
+  }
+
+  return options;
+}

package/helpers/utils/resolveUtils.ts

@@ -0,0 +1,69 @@
+import fs from "fs";
+import path from "path";
+import type { CustomWorld } from "../world";
+
+// Dynamic resolver
+export function resolveValue(input: string): string {
+  // Uppercase = environment variable (e.g. TEST_USER)
+  if (/^[A-Z0-9_]+$/.test(input)) {
+    const envVal = process.env[input];
+    if (!envVal) {
+      throw new Error(`Environment variable ${input} not found.`);
+    }
+    return envVal;
+  }
+
+  // Dot = JSON reference (e.g. userData.email)
+  if (input.includes(".")) {
+    const [fileName, fieldName] = input.split(".");
+    const jsonPath = path.resolve(
+      "e2e/support/helper/test-data",
+      `${fileName}.json`
+    );
+    if (fs.existsSync(jsonPath)) {
+      const json = JSON.parse(fs.readFileSync(jsonPath, "utf-8"));
+      const value = json[fieldName];
+      if (value !== undefined) return value;
+      throw new Error(`Field "${fieldName}" not found in ${fileName}.json`);
+    }
+  }
+
+  // Default to hardcoded value
+  return input;
+}
+export function resolveLoginValue(
+  raw: string,
+  world: CustomWorld
+): string | undefined {
+  // ✅ Alias: @aliasName
+  if (raw.startsWith("@")) {
+    return world.data[raw.slice(1)];
+  }
+
+  // ✅ JSON: user.json:key
+  if (raw.includes(".json:")) {
+    const [filename, key] = raw.split(".json:");
+    const filePath = path.resolve("test-data", `${filename}.json`);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`JSON fixture not found: ${filename}.json`);
+    }
+    const fileData = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    return fileData[key];
+  }
+
+  // ✅ Fallback to raw value
+  return raw;
+}
+// Determine session name from email or username
+export function deriveSessionName(
+  emailOrUser: string,
+  fallback = "default"
+): string {
+  if (!emailOrUser) return `${fallback}User`;
+
+  const base = emailOrUser.includes("@")
+    ? emailOrUser.split("@")[0]
+    : emailOrUser;
+
+  return `${base}User`;
+}

package/helpers/world.ts

@@ -0,0 +1,91 @@
+// support/world.ts
+import {
+  setWorldConstructor,
+  World,
+  ITestCaseHookParameter,
+} from "@cucumber/cucumber";
+import {
+  Browser,
+  Page,
+  BrowserContext,
+  Locator,
+  FrameLocator,
+  devices,
+} from "@playwright/test";
+import { chromium } from "playwright";
+import * as dotenv from "dotenv";
+
+dotenv.config();
+
+const isHeadless = process.env.HEADLESS !== "false";
+const slowMo = process.env.SLOWMO ? Number(process.env.SLOWMO) : 0;
+
+export class CustomWorld extends World {
+  browser!: Browser;
+  context!: BrowserContext;
+  page!: Page;
+
+  elements?: Locator;
+  element?: Locator;
+  frame?: FrameLocator;
+
+  data: Record<string, any> = {};
+  logs: string[] = [];
+  testName?: string;
+
+  async init(testInfo?: ITestCaseHookParameter) {
+    const isMobile = testInfo?.pickle.tags.some(
+      (tag) => tag.name === "@mobile"
+    );
+    const device = isMobile ? devices["Pixel 5"] : undefined;
+
+    this.browser = await chromium.launch({ headless: isHeadless, slowMo });
+
+    this.context = await this.browser.newContext({
+      ...(device || {}),
+      recordVideo: { dir: "e2e/test-artifacts/videos" },
+    });
+
+    this.page = await this.context.newPage();
+    this.testName = testInfo?.pickle.name;
+    this.log(`🧪 Initialized context${isMobile ? " (mobile)" : ""}`);
+  }
+
+  getScope(): Page | FrameLocator {
+    return this.frame ?? this.page;
+  }
+
+  exitIframe() {
+    this.frame = undefined;
+    this.log("⬅️ Exited iframe, scope is now main page");
+  }
+
+  log = (message: string) => {
+    this.logs.push(message);
+    console.log(`[LOG] ${message}`);
+  };
+
+  async cleanup(testInfo?: ITestCaseHookParameter) {
+    const failed = testInfo?.result?.status === "FAILED";
+
+    try {
+      await this.page?.close();
+    } catch (err) {
+      this.log(`⚠️ Error closing page: ${(err as Error).message}`);
+    }
+
+    try {
+      await this.context?.close();
+    } catch (err) {
+      this.log(`⚠️ Error closing context: ${(err as Error).message}`);
+    }
+
+    try {
+      await this.browser?.close();
+    } catch (err) {
+      this.log(`⚠️ Error closing browser: ${(err as Error).message}`);
+    }
+  }
+}
+
+setWorldConstructor(CustomWorld);

package/index.ts

@@ -0,0 +1,4 @@
+// index.ts
+export * from "./src";
+export * from "./helpers/world";
+export * from "./helpers/utils";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "playwright-cucumber-ts-steps",
+  "version": "0.0.1",
+  "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": "module",
+  "types": "dist/index.d.ts",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qaPaschalE/playwright-cucumber-ts-steps.git"
+  },
+  "keywords": [
+    "playwright",
+    "cucumber",
+    "typescript",
+    "e2e",
+    "steps",
+    "step-definitions",
+    "testing",
+    "automation",
+    "bdd",
+    "api",
+    "ui",
+    "web",
+    "end-to-end",
+    "behavior-driven",
+    "mobile",
+    "visual-testing"
+  ],
+  "author": "qaPaschalE",
+  "devDependencies": {
+    "@cucumber/cucumber": "^11.3.0",
+    "@faker-js/faker": "^9.8.0",
+    "@playwright/test": "^1.53.0",
+    "@types/pngjs": "^6.0.5",
+    "dayjs": "^1.11.13",
+    "dotenv-cli": "^8.0.0",
+    "multiple-cucumber-html-reporter": "^3.9.2",
+    "parse": "^6.1.1",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  },
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/qaPaschalE/playwright-cucumber-ts-steps/issues"
+  },
+  "homepage": "https://github.com/qaPaschalE/playwright-cucumber-ts-steps#readme"
+}