playwright-cucumber-ts-steps 0.1.7 → 1.0.1

package/lib/actions/storageSteps.d.ts

@@ -1 +1,174 @@
-export {};
+import { CustomWorld } from "../helpers/world";
+/**
+ * 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 declare function When_I_clear_all_local_storage(this: CustomWorld): Promise<void>;
+/**
+ * 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 declare function When_I_clear_local_storage(this: CustomWorld): Promise<void>;
+/**
+ * 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 declare function When_I_clear_session_storage(this: CustomWorld): Promise<void>;
+/**
+ * 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 declare function When_I_clear_all_browser_storage(this: CustomWorld): Promise<void>;
+/**
+ * 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 declare function When_I_set_local_storage_item(this: CustomWorld, key: string, value: string): Promise<void>;
+/**
+ * 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 declare function When_I_set_session_storage_item(this: CustomWorld, key: string, value: string): Promise<void>;
+/**
+ * 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 declare function When_I_store_input_text_as(this: CustomWorld, alias: string): Promise<void>;
+/**
+ * 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 declare function When_I_clear_session_file(this: CustomWorld, fileName: string): Promise<void>;
+/**
+ * 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 declare function When_I_clear_all_saved_session_files(this: CustomWorld): Promise<void>;

package/lib/actions/storageSteps.js

@@ -3,70 +3,290 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.When_I_clear_all_local_storage = When_I_clear_all_local_storage;
+exports.When_I_clear_local_storage = When_I_clear_local_storage;
+exports.When_I_clear_session_storage = When_I_clear_session_storage;
+exports.When_I_clear_all_browser_storage = When_I_clear_all_browser_storage;
+exports.When_I_set_local_storage_item = When_I_set_local_storage_item;
+exports.When_I_set_session_storage_item = When_I_set_session_storage_item;
+exports.When_I_store_input_text_as = When_I_store_input_text_as;
+exports.When_I_clear_session_file = When_I_clear_session_file;
+exports.When_I_clear_all_saved_session_files = When_I_clear_all_saved_session_files;
 // e2e/step_definitions/common/actions/storageSteps.ts
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const cucumber_1 = require("@cucumber/cucumber");
-(0, cucumber_1.When)("I clear all local storage", async function () {
+// ===================================================================================
+// 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
+ */
+async function When_I_clear_all_local_storage() {
     await this.page.evaluate(() => localStorage.clear());
-    this.log("Cleared all local storage");
-});
-(0, cucumber_1.When)("I clear local storage", async function () {
+    this.log?.("🗑️ Cleared all local storage.");
+}
+(0, cucumber_1.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
+ */
+async function When_I_clear_local_storage() {
     await this.page.evaluate(() => localStorage.clear());
-    this.log("Cleared local storage (alias)");
-});
-(0, cucumber_1.When)("I clear session storage", async function () {
+    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.
+(0, cucumber_1.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
+ */
+async function When_I_clear_session_storage() {
     await this.page.evaluate(() => sessionStorage.clear());
-    this.log("Cleared session storage");
-});
-(0, cucumber_1.When)("I clear all browser storage", async function () {
+    this.log?.("🗑️ Cleared session storage.");
+}
+(0, cucumber_1.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
+ */
+async function When_I_clear_all_browser_storage() {
     const { context, page } = this;
-    // Clear cookies
+    // 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");
+        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 cookies and storage");
-});
-(0, cucumber_1.When)("I set local storage item {string} to {string}", async function (key, value) {
+    this.log?.("🗑️ Cleared all local and session storage.");
+    this.log?.("✅ Cleared all browser cookies and storage.");
+}
+(0, cucumber_1.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
+ */
+async function When_I_set_local_storage_item(key, value) {
+    // FIX: Use object for evaluate arguments to avoid TypeScript overload issues
     await this.page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
-});
-(0, cucumber_1.When)("I set session storage item {string} to {string}", async function (key, value) {
+    this.log?.(`📦 Set local storage item "${key}" to "${value.slice(0, 50)}...".`);
+}
+(0, cucumber_1.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
+ */
+async function When_I_set_session_storage_item(key, value) {
+    // FIX: Use object for evaluate arguments to avoid TypeScript overload issues
     await this.page.evaluate(([k, v]) => sessionStorage.setItem(k, v), [key, value]);
-});
-(0, cucumber_1.When)("I clear local storage", async function () {
-    await this.page.evaluate(() => localStorage.clear());
-});
-(0, cucumber_1.When)("I store input text as {string}", async function (alias) {
+    this.log?.(`📦 Set session storage item "${key}" to "${value.slice(0, 50)}...".`);
+}
+(0, cucumber_1.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
+ */
+async function When_I_store_input_text_as(alias) {
     const activeElementHandle = await this.page.evaluateHandle(() => document.activeElement);
-    const tagName = await activeElementHandle.evaluate((el) => (el ? el.tagName.toLowerCase() : ""));
+    // Check if activeElementHandle is not null and is an HTMLInputElement or HTMLTextAreaElement
+    const tagName = await activeElementHandle.evaluate((el) => el ? el.tagName.toLowerCase() : "");
     if (tagName !== "input" && tagName !== "textarea") {
-        throw new Error(`Active element is not an input or textarea (found: ${tagName})`);
+        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.value);
     this.data[alias] = value;
-    this.log?.(`📥 Stored value from input as "${alias}": ${value}`);
-});
-(0, cucumber_1.When)("I clear session {string}", async function (fileName) {
+    this.log?.(`📥 Stored value from active input as "${alias}": "${value}".`);
+}
+(0, cucumber_1.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
+ */
+async function When_I_clear_session_file(fileName) {
     const baseDir = this.parameters?.artifactDir || process.env.TEST_ARTIFACT_DIR || "test-artifacts";
-    const fullPath = path_1.default.resolve(baseDir, "auth-cookies", fileName);
+    const sessionDirPath = path_1.default.resolve(baseDir, "auth-cookies"); // Assuming sessions are stored here
+    const fullPath = path_1.default.resolve(sessionDirPath, fileName);
     try {
         if (fs_1.default.existsSync(fullPath)) {
             fs_1.default.unlinkSync(fullPath);
-            this.log?.(`🗑️ Session file deleted: ${fullPath}`);
+            this.log?.(`🗑️ Session file deleted: "${fullPath}".`);
         }
         else {
-            this.log?.(`ℹ️ Session file not found, nothing to delete: ${fullPath}`);
+            this.log?.(`ℹ️ Session file not found, nothing to delete: "${fullPath}".`);
         }
     }
     catch (err) {
-        this.log?.(`❌ Failed to delete session file: ${err.message}`);
-        throw 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
+    }
+}
+(0, cucumber_1.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
+ */
+async function When_I_clear_all_saved_session_files() {
+    // Hardcoded path based on your original snippet
+    const authDir = path_1.default.resolve("e2e/support/helper/auth");
+    if (fs_1.default.existsSync(authDir)) {
+        const files = fs_1.default.readdirSync(authDir);
+        for (const file of files) {
+            const filePath = path_1.default.join(authDir, file);
+            // Ensure it's a file, not a subdirectory
+            if (fs_1.default.lstatSync(filePath).isFile()) {
+                fs_1.default.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.`);
     }
-});
+}
+(0, cucumber_1.When)("I clear all saved session files", When_I_clear_all_saved_session_files);