playwright-cucumber-ts-steps 0.1.6 → 1.0.0

package/src/actions/mouseSteps.ts

@@ -0,0 +1,256 @@
+// e2e/step_definitions/common/mouseSteps.ts
+import { When } from "@cucumber/cucumber";
+import { CustomWorld } from "../helpers/world"; // Assuming this path is correct
+
+// ===================================================================================
+// MOUSE ACTIONS: SCROLLING
+// ===================================================================================
+
+/**
+ * Scrolls the element matching the given selector into view.
+ * This is useful for making sure an element is visible before interacting with it.
+ *
+ * ```gherkin
+ * When I scroll {string} into view
+ * ```
+ *
+ * @param selector - The CSS selector of the element to scroll into view.
+ *
+ * @example
+ * When I scroll ".footer-section" into view
+ *
+ * @remarks
+ * This step uses Playwright's `locator.scrollIntoViewIfNeeded()`.
+ * It will scroll the page or scrollable container as little as possible to bring
+ * the element into the viewport.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_element_into_view(this: CustomWorld, selector: string) {
+  const locator = this.getScope().locator(selector);
+  await locator.scrollIntoViewIfNeeded();
+  this.log?.(`🖱️ Scrolled element "${selector}" into view.`);
+}
+When(/^I scroll "([^"]+)" into view$/, When_I_scroll_element_into_view);
+
+/**
+ * Scrolls the element matching the given selector to a specific X and Y position.
+ * The scrolling is relative to the element's own scrollable area.
+ *
+ * ```gherkin
+ * When I scroll {string} to position x:{int} y:{int}
+ * ```
+ *
+ * @param selector - The CSS selector of the element to scroll.
+ * @param x - The X-coordinate (horizontal) to scroll to within the element.
+ * @param y - The Y-coordinate (vertical) to scroll to within the element.
+ *
+ * @example
+ * When I scroll ".my-scrollable-div" to position x:100 y:200
+ *
+ * @remarks
+ * This step uses `locator.evaluate()` to execute `element.scrollTo()` directly
+ * in the browser context. This is typically used for scrolling within a specific
+ * scrollable HTML element, not the main window.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_element_to_position(
+  this: CustomWorld,
+  selector: string,
+  x: number, // Changed to number as Cucumber's {int} already parses it
+  y: number // Changed to number
+) {
+  const locator = this.getScope().locator(selector);
+  await locator.evaluate(
+    (el: Element, coords: { x: number; y: number }) => {
+      el.scrollTo(coords.x, coords.y);
+    },
+    { x, y } // Pass coordinates as an object
+  );
+  this.log?.(`🖱️ Scrolled element "${selector}" to position x:${x} y:${y}.`);
+}
+When(/^I scroll "([^"]+)" to position x:(\d+) y:(\d+)$/, When_I_scroll_element_to_position);
+
+/**
+ * Scrolls the entire window to specific X and Y coordinates.
+ * The coordinates are absolute positions on the page.
+ *
+ * ```gherkin
+ * When I scroll to coordinates x:{int} y:{int}
+ * ```
+ *
+ * @param x - The X-coordinate (horizontal) to scroll the window to.
+ * @param y - The Y-coordinate (vertical) to scroll the window to.
+ *
+ * @example
+ * When I scroll to coordinates x:0 y:500
+ *
+ * @remarks
+ * This step uses `page.evaluate()` to execute `window.scrollTo()` directly
+ * in the browser context. This controls the main browser window's scroll position.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_to_coordinates(
+  this: CustomWorld,
+  x: number, // Changed to number
+  y: number // Changed to number
+) {
+  await this.page.evaluate(
+    (coords: { x: number; y: number }) => {
+      window.scrollTo(coords.x, coords.y);
+    },
+    { x, y } // Pass coordinates as an object
+  );
+  this.log?.(`🖱️ Scrolled window to coordinates x:${x} y:${y}.`);
+}
+When(/^I scroll to coordinates x:(\d+) y:(\d+)$/, When_I_scroll_to_coordinates);
+
+/**
+ * Scrolls the entire window to a specified top and left position with a smooth animation.
+ *
+ * ```gherkin
+ * When I scroll window to position top:{int} left:{int}
+ * ```
+ *
+ * @param top - The Y-coordinate (vertical) to scroll the window to.
+ * @param left - The X-coordinate (horizontal) to scroll the window to.
+ *
+ * @example
+ * When I scroll window to position top:0 left:100
+ *
+ * @remarks
+ * This step uses `page.evaluate()` to execute `window.scrollTo()` with a `behavior: "smooth"`
+ * option in the browser context, providing a native smooth scrolling experience.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_mouse_window_to_position(
+  this: CustomWorld,
+  top: number, // Changed to number
+  left: number // Changed to number
+) {
+  await this.page.evaluate(
+    (coords: { top: number; left: number }) => {
+      window.scrollTo({
+        top: coords.top,
+        left: coords.left,
+        behavior: "smooth",
+      });
+    },
+    { top, left } // Pass coordinates as an object
+  );
+  this.log?.(`🖱️ Scrolled window to position top:${top} left:${left} (smooth).`);
+}
+When(
+  /^I scroll mouse window to position top:(\d+) left:(\d+)$/,
+  When_I_scroll_mouse_window_to_position
+);
+
+/**
+ * Scrolls the window to a predefined direction (top, bottom, left, or right) with smooth behavior.
+ *
+ * ```gherkin
+ * When I scroll to "{word}"
+ * ```
+ *
+ * @param direction - The direction to scroll to: "top", "bottom", "left", or "right".
+ *
+ * @example
+ * When I scroll to "bottom"
+ * When I scroll to "top"
+ *
+ * @remarks
+ * This step evaluates `window.scrollTo()` in the browser context, setting the `top`
+ * or `left` property based on the `direction`. It includes a short `waitForTimeout`
+ * to allow the smooth scroll animation to complete.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_to_direction(this: CustomWorld, direction: string) {
+  const validDirections = ["top", "bottom", "left", "right"];
+  if (!validDirections.includes(direction)) {
+    throw new Error(
+      `Invalid scroll direction "${direction}". Must be one of: ${validDirections.join(", ")}.`
+    );
+  }
+
+  await this.page.evaluate((dir) => {
+    const scrollOptions: ScrollToOptions = {
+      behavior: "smooth",
+    };
+
+    switch (dir) {
+      case "top":
+        scrollOptions.top = 0;
+        break;
+      case "bottom":
+        // Scroll to the bottom of the body's scroll height
+        scrollOptions.top = document.body.scrollHeight;
+        break;
+      case "left":
+        scrollOptions.left = 0;
+        break;
+      case "right":
+        // Scroll to the rightmost edge of the body's scroll width
+        scrollOptions.left = document.body.scrollWidth;
+        break;
+    }
+    window.scrollTo(scrollOptions);
+  }, direction);
+
+  this.log?.(`🖱️ Scrolled to "${direction}".`);
+  // Allow a brief moment for the smooth scroll animation to complete
+  await this.page.waitForTimeout(500);
+}
+When('I scroll to "{word}"', When_I_scroll_to_direction);
+
+// ===================================================================================
+// MOUSE ACTIONS: HOVERING / MOVEMENT
+// ===================================================================================
+
+/**
+ * Hovers the mouse cursor over the element matching the given selector.
+ *
+ * ```gherkin
+ * When I hover over the element {string}
+ * ```
+ *
+ * @param selector - The CSS selector of the element to hover over.
+ *
+ * @example
+ * When I hover over the element ".dropdown-menu-trigger"
+ * Then I should see element ".dropdown-content"
+ *
+ * @remarks
+ * This step simulates a mouse hover event. It also stores the hovered element
+ * in {@link CustomWorld.element | this.element} for potential subsequent actions.
+ * @category Mouse Interaction Steps
+ */
+export async function When_I_hover_over_the_element(this: CustomWorld, selector: string) {
+  const element = this.getScope().locator(selector);
+  await element.hover();
+  this.element = element; // Store the hovered element as the current element
+  this.log?.(`🖱️ Hovered over: "${selector}".`);
+}
+When("I hover over the element {string}", When_I_hover_over_the_element);
+
+/**
+ * Moves the mouse cursor to the given absolute X and Y coordinates on the page.
+ *
+ * ```gherkin
+ * When I move mouse to coordinates {int}, {int}
+ * ```
+ *
+ * @param x - The X-coordinate in pixels.
+ * @param y - The Y-coordinate in pixels.
+ *
+ * @example
+ * When I move mouse to coordinates 100, 200
+ *
+ * @remarks
+ * This step directly controls the mouse cursor position using Playwright's
+ * `page.mouse.move()`. This is a low-level mouse action.
+ * @category Mouse Interaction Steps
+ */
+export async function When_I_move_mouse_to_coordinates(this: CustomWorld, x: number, y: number) {
+  await this.page.mouse.move(x, y);
+  this.log?.(`🧭 Mouse moved to (${x}, ${y}).`);
+}
+When("I move mouse to coordinates {int}, {int}", When_I_move_mouse_to_coordinates);

package/src/actions/scrollSteps.ts

@@ -0,0 +1,122 @@
+// e2e/step_definitions/common/scrollSteps.ts
+import { When } from "@cucumber/cucumber";
+import { CustomWorld } from "../helpers/world"; // Assuming this path is correct
+
+// ===================================================================================
+// SCROLLING ACTIONS
+// ===================================================================================
+
+/**
+ * Scrolls the previously selected element into the viewport if it's not already visible.
+ *
+ * ```gherkin
+ * When I scroll into view
+ * ```
+ *
+ * @example
+ * When I find element by selector ".my-long-content-element"
+ * And I scroll into view
+ *
+ * @remarks
+ * This step requires a preceding step that sets the {@link CustomWorld.element | current element}
+ * (e.g., "When I find element by selector"). It uses Playwright's `locator.scrollIntoViewIfNeeded()`,
+ * which scrolls the least amount necessary to make the element visible.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_into_view(this: CustomWorld) {
+  const element = this.element;
+  if (!element) throw new Error("No element selected. Use a 'find element' step before this.");
+  await element.scrollIntoViewIfNeeded();
+  this.log?.("Scrolled selected element into view."); // Using optional chaining for log
+}
+When("I scroll into view", When_I_scroll_into_view);
+
+/**
+ * Scrolls the main browser window to the given X (horizontal) and Y (vertical) pixel coordinates.
+ *
+ * ```gherkin
+ * When I scroll to position {int} {int}
+ * ```
+ *
+ * @param x - The X-coordinate in pixels to scroll to.
+ * @param y - The Y-coordinate in pixels to scroll to.
+ *
+ * @example
+ * When I scroll to position 0 500
+ *
+ * @remarks
+ * This step directly executes `window.scrollTo(x, y)` in the browser's context.
+ * It sets the absolute scroll position of the main document.
+ * This is similar to `When I scroll window to position {int} {int}` and `When I scroll window to x {int} and y {int}`.
+ * Consider consolidating if their functionality is identical.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_to_position(this: CustomWorld, x: number, y: number) {
+  // FIX: Pass arguments as an object instead of an array
+  await this.page.evaluate(({ xCoord, yCoord }) => window.scrollTo(xCoord, yCoord), {
+    xCoord: x,
+    yCoord: y,
+  });
+  this.log?.(`Scrolled window to position: ${x}, ${y}.`);
+}
+When("I scroll to position {int} {int}", When_I_scroll_to_position);
+
+/**
+ * Scrolls the main browser window to the given X (horizontal) and Y (vertical) pixel coordinates.
+ * This step is an alias for "When I scroll to position {int} {int}".
+ *
+ * ```gherkin
+ * When I scroll window to position {int} {int}
+ * ```
+ *
+ * @param x - The X-coordinate in pixels to scroll to.
+ * @param y - The Y-coordinate in pixels to scroll to.
+ *
+ * @example
+ * When I scroll window to position 0 500
+ *
+ * @remarks
+ * This step is functionally identical to {@link When_I_scroll_to_position | "When I scroll to position {int} {int}"}.
+ * It executes `window.scrollTo(x, y)` in the browser's context.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_window_to_position(this: CustomWorld, x: number, y: number) {
+  // FIX: Pass arguments as an object instead of an array
+  await this.page.evaluate(({ xCoord, yCoord }) => window.scrollTo(xCoord, yCoord), {
+    xCoord: x,
+    yCoord: y,
+  });
+  this.log?.(`Window scrolled to: ${x}, ${y}.`);
+}
+When("I scroll window to position {int} {int}", When_I_scroll_window_to_position);
+
+/**
+ * Scrolls the main browser window to the given X (horizontal) and Y (vertical) pixel coordinates.
+ * This step is another alias for "When I scroll to position {int} {int}".
+ *
+ * ```gherkin
+ * When I scroll window to x {int} and y {int}
+ * ```
+ *
+ * @param x - The X-coordinate in pixels to scroll to.
+ * @param y - The Y-coordinate in pixels to scroll to.
+ *
+ * @example
+ * When I scroll window to x 0 and y 500
+ *
+ * @remarks
+ * This step is functionally identical to {@link When_I_scroll_to_position | "When I scroll to position {int} {int}"}
+ * and {@link When_I_scroll_window_to_position | "When I scroll window to position {int} {int}"}.
+ * It executes `window.scrollTo(x, y)` in the browser's context.
+ * It's recommended to choose one consistent step pattern for window scrolling.
+ * @category Scrolling Steps
+ */
+export async function When_I_scroll_window_to_x_and_y(this: CustomWorld, x: number, y: number) {
+  // FIX: Pass arguments as an object instead of an array
+  await this.page.evaluate(({ xCoord, yCoord }) => window.scrollTo(xCoord, yCoord), {
+    xCoord: x,
+    yCoord: y,
+  });
+  this.log?.(`Window scrolled to coordinates: (${x}, ${y}).`);
+}
+When("I scroll window to x {int} and y {int}", When_I_scroll_window_to_x_and_y);

package/src/actions/storageSteps.ts

@@ -0,0 +1,308 @@
+// e2e/step_definitions/common/actions/storageSteps.ts
+import fs from "fs";
+import path from "path";
+import { When } from "@cucumber/cucumber";
+import { CustomWorld } from "../helpers/world"; // Assuming this path is correct
+
+// ===================================================================================
+// BROWSER STORAGE ACTIONS (LOCAL STORAGE, SESSION STORAGE, COOKIES)
+// ===================================================================================
+
+/**
+ * Clears all items from the browser's Local Storage for the current page's origin.
+ *
+ * ```gherkin
+ * When I clear all local storage
+ * ```
+ *
+ * @example
+ * When I clear all local storage
+ *
+ * @remarks
+ * This step executes `localStorage.clear()` in the browser's context.
+ * Local Storage items are persistent across browser sessions until explicitly cleared.
+ * This step will only affect local storage for the current page's origin.
+ * @category Storage Steps
+ */
+export async function When_I_clear_all_local_storage(this: CustomWorld) {
+  await this.page.evaluate(() => localStorage.clear());
+  this.log?.("🗑️ Cleared all local storage.");
+}
+When("I clear all local storage", When_I_clear_all_local_storage);
+
+/**
+ * Clears all items from the browser's Local Storage for the current page's origin.
+ * This is an alias for "When I clear all local storage".
+ *
+ * ```gherkin
+ * When I clear local storage
+ * ```
+ *
+ * @example
+ * When I clear local storage
+ *
+ * @remarks
+ * This step is functionally identical to {@link When_I_clear_all_local_storage | "When I clear all local storage"}.
+ * It executes `localStorage.clear()` in the browser's context.
+ * Consider using one consistent step pattern.
+ * @category Storage Steps
+ */
+export async function When_I_clear_local_storage(this: CustomWorld) {
+  await this.page.evaluate(() => localStorage.clear());
+  this.log?.("🗑️ Cleared local storage (alias).");
+}
+// Note: You have two steps with the exact same Gherkin pattern:
+// When("I clear local storage", async function () { ... });
+// When("I clear local storage", async function (this: CustomWorld) { ... });
+// I've consolidated them into one export and linked the When call.
+When("I clear local storage", When_I_clear_local_storage);
+
+/**
+ * Clears all items from the browser's Session Storage for the current page's origin.
+ *
+ * ```gherkin
+ * When I clear session storage
+ * ```
+ *
+ * @example
+ * When I clear session storage
+ *
+ * @remarks
+ * This step executes `sessionStorage.clear()` in the browser's context.
+ * Session Storage items are cleared when the browser session ends.
+ * This step will only affect session storage for the current page's origin.
+ * @category Storage Steps
+ */
+export async function When_I_clear_session_storage(this: CustomWorld) {
+  await this.page.evaluate(() => sessionStorage.clear());
+  this.log?.("🗑️ Cleared session storage.");
+}
+When("I clear session storage", When_I_clear_session_storage);
+
+/**
+ * Clears all browser storage: cookies, local storage, and session storage.
+ * It first navigates to the `BASE_URL` to ensure the correct origin's storage is cleared.
+ *
+ * ```gherkin
+ * When I clear all browser storage
+ * ```
+ *
+ * @example
+ * When I clear all browser storage
+ *
+ * @remarks
+ * This is a comprehensive cleanup step. It uses `context.clearCookies()` for cookies
+ * and `page.evaluate()` to clear `localStorage` and `sessionStorage`.
+ * Navigating to `BASE_URL` before clearing local/session storage is crucial to ensure
+ * the storage for the primary application domain is targeted. Ensure `process.env.BASE_URL` is set.
+ * @category Storage Steps
+ */
+export async function When_I_clear_all_browser_storage(this: CustomWorld) {
+  const { context, page } = this;
+
+  // Clear cookies for the entire browser context
+  await context.clearCookies();
+  this.log?.("🗑️ Cleared all cookies.");
+
+  // Clear local/session storage by navigating to base URL first
+  const baseUrl = process.env.BASE_URL;
+  if (!baseUrl)
+    throw new Error(
+      "Missing BASE_URL environment variable. Cannot clear local/session storage effectively."
+    );
+  // Navigate to base URL to ensure we are on the correct origin to clear its storage
+  await page.goto(baseUrl);
+  this.log?.(
+    `🌍 Navigated to BASE_URL (${baseUrl}) to ensure correct origin for storage clearing.`
+  );
+
+  await page.evaluate(() => {
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+  this.log?.("🗑️ Cleared all local and session storage.");
+
+  this.log?.("✅ Cleared all browser cookies and storage.");
+}
+When("I clear all browser storage", When_I_clear_all_browser_storage);
+
+/**
+ * Sets a specific item in the browser's Local Storage to the given value.
+ *
+ * ```gherkin
+ * When I set local storage item {string} to {string}
+ * ```
+ *
+ * @param key - The key of the local storage item.
+ * @param value - The value to set for the local storage item.
+ *
+ * @example
+ * When I set local storage item "token" to "abc123"
+ *
+ * @remarks
+ * This step executes `localStorage.setItem(key, value)` in the browser's context.
+ * This is useful for injecting authentication tokens, feature flags, or other data
+ * directly into local storage for test setup.
+ * @category Storage Steps
+ */
+export async function When_I_set_local_storage_item(this: CustomWorld, key: string, value: string) {
+  // FIX: Use object for evaluate arguments to avoid TypeScript overload issues
+  await this.page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
+  this.log?.(`📦 Set local storage item "${key}" to "${value.slice(0, 50)}...".`);
+}
+When("I set local storage item {string} to {string}", When_I_set_local_storage_item);
+
+/**
+ * Sets a specific item in the browser's Session Storage to the given value.
+ *
+ * ```gherkin
+ * When I set session storage item {string} to {string}
+ * ```
+ *
+ * @param key - The key of the session storage item.
+ * @param value - The value to set for the session storage item.
+ *
+ * @example
+ * When I set session storage item "sessionId" to "xyz789"
+ *
+ * @remarks
+ * This step executes `sessionStorage.setItem(key, value)` in the browser's context.
+ * This is useful for injecting data that needs to persist only for the current browser session.
+ * @category Storage Steps
+ */
+export async function When_I_set_session_storage_item(
+  this: CustomWorld,
+  key: string,
+  value: string
+) {
+  // FIX: Use object for evaluate arguments to avoid TypeScript overload issues
+  await this.page.evaluate(([k, v]) => sessionStorage.setItem(k, v), [key, value]);
+  this.log?.(`📦 Set session storage item "${key}" to "${value.slice(0, 50)}...".`);
+}
+When("I set session storage item {string} to {string}", When_I_set_session_storage_item);
+
+/**
+ * Stores the value of the currently focused input or textarea as an alias in the test data.
+ *
+ * ```gherkin
+ * When I store input text as {string}
+ * ```
+ *
+ * @param alias - The alias name under which to store the input's value.
+ *
+ * @example
+ * Given I find element by placeholder text "Enter your email"
+ * And I type "user@example.com"
+ * When I store input text as "userEmail"
+ * Then the value of alias "userEmail" should be "user@example.com"
+ *
+ * @remarks
+ * This step requires an input or textarea element to be currently focused. It retrieves
+ * the `value` attribute of that element and stores it in {@link CustomWorld.data | this.data}
+ * under the provided `alias`. This is useful for capturing dynamically generated input values.
+ * @category Data Manipulation Steps
+ */
+export async function When_I_store_input_text_as(this: CustomWorld, alias: string) {
+  const activeElementHandle = await this.page.evaluateHandle(() => document.activeElement);
+
+  // Check if activeElementHandle is not null and is an HTMLInputElement or HTMLTextAreaElement
+  const tagName = await activeElementHandle.evaluate((el) =>
+    el ? (el as HTMLElement).tagName.toLowerCase() : ""
+  );
+
+  if (tagName !== "input" && tagName !== "textarea") {
+    throw new Error(
+      `Active element is not an input or textarea (found: "${tagName || "none"}"). Cannot store text.`
+    );
+  }
+
+  // Cast el to HTMLInputElement as both input and textarea have a 'value' property
+  const value = await activeElementHandle.evaluate((el) => (el as HTMLInputElement).value);
+  this.data[alias] = value;
+  this.log?.(`📥 Stored value from active input as "${alias}": "${value}".`);
+}
+When("I store input text as {string}", When_I_store_input_text_as);
+
+/**
+ * Deletes a session file with the given name from the artifact directory.
+ * These session files are typically used for storing browser session state (e.g., cookies, local storage).
+ *
+ * ```gherkin
+ * When I clear session {string}
+ * ```
+ *
+ * @param fileName - The name of the session file to delete (e.g., "my-session.json").
+ *
+ * @example
+ * Given I save session as "admin-session.json"
+ * # ... later in a cleanup scenario
+ * When I clear session "admin-session.json"
+ *
+ * @remarks
+ * The `fileName` is resolved relative to a base directory, which defaults to
+ * `test-artifacts/auth-cookies` or can be configured via `this.parameters?.artifactDir`
+ * or `process.env.TEST_ARTIFACT_DIR`.
+ * This step ensures clean-up of saved session states, which is crucial for isolated tests.
+ * @category File System Steps
+ */
+export async function When_I_clear_session_file(this: CustomWorld, fileName: string) {
+  const baseDir = this.parameters?.artifactDir || process.env.TEST_ARTIFACT_DIR || "test-artifacts";
+  const sessionDirPath = path.resolve(baseDir, "auth-cookies"); // Assuming sessions are stored here
+  const fullPath = path.resolve(sessionDirPath, fileName);
+
+  try {
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+      this.log?.(`🗑️ Session file deleted: "${fullPath}".`);
+    } else {
+      this.log?.(`ℹ️ Session file not found, nothing to delete: "${fullPath}".`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    this.log?.(`❌ Failed to delete session file "${fullPath}": ${message}`);
+    throw err; // Re-throw to fail the step if deletion truly failed
+  }
+}
+When("I clear session {string}", When_I_clear_session_file);
+// ===================================================================================
+// FILE SYSTEM ACTIONS: SAVED SESSIONS
+// ===================================================================================
+
+/**
+ * Clears all saved session files from the authentication directory.
+ * This is useful for ensuring a clean slate before or after tests that rely on persistent sessions.
+ *
+ * ```gherkin
+ * When I clear all saved session files
+ * ```
+ *
+ * @example
+ * When I clear all saved session files
+ *
+ * @remarks
+ * This step reads the `e2e/support/helper/auth` directory (hardcoded path) and deletes
+ * all files found within it. It's crucial for managing test artifacts related to user sessions.
+ * Ensure the directory path is correct for your project structure.
+ * @category File System Steps
+ */
+export async function When_I_clear_all_saved_session_files(this: CustomWorld) {
+  // Hardcoded path based on your original snippet
+  const authDir = path.resolve("e2e/support/helper/auth");
+
+  if (fs.existsSync(authDir)) {
+    const files = fs.readdirSync(authDir);
+
+    for (const file of files) {
+      const filePath = path.join(authDir, file);
+      // Ensure it's a file, not a subdirectory
+      if (fs.lstatSync(filePath).isFile()) {
+        fs.unlinkSync(filePath);
+        this.log?.(`🧹 Deleted session file: "${file}".`);
+      }
+    }
+    this.log?.(`✅ All saved session files cleared from "${authDir}".`);
+  } else {
+    this.log?.(`⚠️ Auth directory not found at "${authDir}". No session files to clear.`);
+  }
+}
+When("I clear all saved session files", When_I_clear_all_saved_session_files);