playwright-cucumber-ts-steps 0.1.3 → 0.1.4

package/{dist → lib}/actions/miscSteps.js

@@ -4,8 +4,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const cucumber_1 = require("@cucumber/cucumber");
+const test_1 = require("@playwright/test");
 const dayjs_1 = __importDefault(require("dayjs"));
 const optionsUtils_1 = require("../helpers/utils/optionsUtils");
+const resolveUtils_1 = require("../helpers/utils/resolveUtils");
 //
 // Timers
 //
@@ -38,16 +40,18 @@ const optionsUtils_1 = require("../helpers/utils/optionsUtils");
 (0, cucumber_1.When)(/^I wait (\d+) second[s]?$/, async function (seconds) {
     await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
 });
-(0, cucumber_1.When)("I wait {int} milliseconds", async function (ms) {
+(0, cucumber_1.When)(/^I wait (\d+) millisecond[s]?$/, async function (ms) {
     await new Promise((res) => setTimeout(res, ms));
 });
+(0, cucumber_1.When)("I set step timeout to {int} ms", function (timeoutMs) {
+    (0, cucumber_1.setDefaultTimeout)(timeoutMs);
+    this.log?.(`⏱️ Timeout set to ${timeoutMs}ms`);
+});
 //
 // Events
 //
 (0, cucumber_1.When)(/^I trigger "(.*)" event on "([^"]+)"$/, async function (eventType, selector) {
-    await this.page
-        .locator(selector)
-        .evaluate((el, type) => {
+    await this.page.locator(selector).evaluate((el, type) => {
         const event = new Event(type, {
             bubbles: true,
             cancelable: true,
@@ -73,8 +77,8 @@ const optionsUtils_1 = require("../helpers/utils/optionsUtils");
 //
 // Debugging / Logging
 //
-(0, cucumber_1.When)(/^I log "(.*)"$/, async function (_, message) {
-    console.log(`[LOG]: ${message}`);
+(0, cucumber_1.When)("I log {string}", async function (message) {
+    this.log(message);
 });
 (0, cucumber_1.When)(/^I debug$/, async function () {
     debugger;
@@ -163,9 +167,7 @@ const validUnits = [
 //
 (0, cucumber_1.When)("I switch to iframe with selector {string}", async function (selector) {
     const frameLocator = this.page.frameLocator(selector);
-    await frameLocator
-        .locator("body")
-        .waitFor({ state: "visible", timeout: 10000 });
+    await frameLocator.locator("body").waitFor({ state: "visible", timeout: 10000 });
     this.frame = frameLocator;
     this.log?.(`🪟 Switched to iframe: ${selector}`);
 });
@@ -197,9 +199,7 @@ function toOrdinal(n) {
 async function getReadableLabel(el) {
     try {
         const tag = await el.evaluate((el) => el.tagName.toLowerCase());
-        return tag === "input"
-            ? await el.inputValue()
-            : (await el.innerText()).trim();
+        return tag === "input" ? await el.inputValue() : (await el.innerText()).trim();
     }
     catch {
         return "(unknown)";
@@ -270,3 +270,51 @@ const locatorActions = {
     await this.element.press(key);
     this.log?.(`🎹 Pressed {${key}}`);
 });
+(0, cucumber_1.When)(/^I set viewport to "([^"]+)"(?: and "([^"]+)")?$/, async function (deviceInput, orientation) {
+    const normalizedDevice = (0, resolveUtils_1.normalizeDeviceName)(deviceInput);
+    if (!normalizedDevice) {
+        throw new Error(`🚫 Unknown device: "${deviceInput}"`);
+    }
+    const baseDevice = test_1.devices[normalizedDevice];
+    if (!baseDevice) {
+        throw new Error(`🚫 Device not found: "${normalizedDevice}"`);
+    }
+    const isLandscape = orientation?.toLowerCase() === "landscape";
+    const deviceSettings = isLandscape
+        ? baseDevice.landscape
+            ? baseDevice.landscape
+            : {
+                ...baseDevice,
+                isMobile: true,
+                viewport: { ...baseDevice.viewport, isLandscape: true },
+            }
+        : baseDevice;
+    // Close current context if needed
+    if (this.context) {
+        await this.context.close();
+    }
+    this.context = await this.browser.newContext(deviceSettings);
+    this.page = await this.context.newPage();
+    this.log?.(`📱 Set viewport to ${normalizedDevice}${isLandscape ? " in landscape" : ""}`);
+});
+(0, cucumber_1.When)("I set viewport to {int}px by {int}px", async function (width, height) {
+    // Close existing context
+    if (this.context) {
+        await this.context.close();
+    }
+    // Recreate new context with the desired viewport
+    this.context = await this.browser.newContext({
+        viewport: { width, height },
+    });
+    this.page = await this.context.newPage();
+    this.log?.(`🖥️ Set viewport to ${width}x${height}`);
+});
+// Dynamic Playwright Config Setters (for page-only config)
+(0, cucumber_1.When)('I set Playwright config "{word}" to {string}', async function (key, value) {
+    this.page[key] = value;
+});
+(0, cucumber_1.When)("I set Playwright config", async function (table) {
+    for (const [key, value] of table.rows()) {
+        this.page[key] = value;
+    }
+});

package/{dist → lib}/actions/storageSteps.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 // 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 () {
     await this.page.evaluate(() => localStorage.clear());
@@ -32,15 +37,15 @@ const cucumber_1 = require("@cucumber/cucumber");
 (0, cucumber_1.When)("I set local storage item {string} to {string}", async function (key, value) {
     await this.page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value]);
 });
-// When("I clear session storage", async function (this: CustomWorld) {
-//   await this.page.evaluate(() => sessionStorage.clear());
-// });
+(0, cucumber_1.When)("I set session storage item {string} to {string}", async function (key, value) {
+    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) {
     const activeElementHandle = await this.page.evaluateHandle(() => document.activeElement);
-    const tagName = await activeElementHandle.evaluate((el) => el ? el.tagName.toLowerCase() : "");
+    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})`);
     }
@@ -48,3 +53,20 @@ const cucumber_1 = require("@cucumber/cucumber");
     this.data[alias] = value;
     this.log?.(`📥 Stored value from input as "${alias}": ${value}`);
 });
+(0, cucumber_1.When)("I clear session {string}", async function (fileName) {
+    const baseDir = this.parameters?.artifactDir || process.env.TEST_ARTIFACT_DIR || "test-artifacts";
+    const fullPath = path_1.default.resolve(baseDir, "auth-cookies", fileName);
+    try {
+        if (fs_1.default.existsSync(fullPath)) {
+            fs_1.default.unlinkSync(fullPath);
+            this.log?.(`🗑️ Session file deleted: ${fullPath}`);
+        }
+        else {
+            this.log?.(`ℹ️ Session file not found, nothing to delete: ${fullPath}`);
+        }
+    }
+    catch (err) {
+        this.log?.(`❌ Failed to delete session file: ${err.message}`);
+        throw err;
+    }
+});

package/{dist → lib}/assertions/buttonAndTextVisibilitySteps.js

@@ -14,9 +14,7 @@ const fakerUtils_1 = require("../helpers/utils/fakerUtils");
  * THEN: I see button "Submit"
  */
 (0, cucumber_1.Then)(/^I see button "(.*)"$/, async function (rawText) {
-    let buttonText = rawText.startsWith("@")
-        ? this.data[rawText.slice(1)]
-        : rawText;
+    let buttonText = rawText.startsWith("@") ? this.data[rawText.slice(1)] : rawText;
     if (!buttonText) {
         throw new Error(`No value found for alias: "${rawText}"`);
     }
@@ -31,9 +29,7 @@ const fakerUtils_1 = require("../helpers/utils/fakerUtils");
  * THEN: I do not see button "Cancel"
  */
 (0, cucumber_1.Then)(/^I do not see button "(.*)"$/, async function (rawText) {
-    let buttonText = rawText.startsWith("@")
-        ? this.data[rawText.slice(1)]
-        : rawText;
+    let buttonText = rawText.startsWith("@") ? this.data[rawText.slice(1)] : rawText;
     if (!buttonText) {
         throw new Error(`No value found for alias: "${rawText}"`);
     }
@@ -59,20 +55,6 @@ const fakerUtils_1 = require("../helpers/utils/fakerUtils");
     await locator.waitFor({ state: "visible", timeout: 5000 });
     this.log?.(`✅ Verified text visible: ${expected}`);
 });
-/**
- * THEN: I do not see text "Error"
- */
-(0, cucumber_1.Then)("I do not see text {string}", async function (text) {
-    await this.page.waitForLoadState("networkidle");
-    const locator = this.page.locator(`:has-text("${text}")`);
-    const count = await locator.count();
-    for (let i = 0; i < count; i++) {
-        const item = locator.nth(i);
-        if (await item.isVisible()) {
-            throw new Error(`Text "${text}" is visible but should not be`);
-        }
-    }
-});
 /**
  * THEN: I see visible text "Dashboard"
  */
@@ -151,9 +133,7 @@ const fakerUtils_1 = require("../helpers/utils/fakerUtils");
 });
 (0, cucumber_1.Then)("I see button {string} is disabled", async function (rawText) {
     // Resolve alias
-    let buttonText = rawText.startsWith("@")
-        ? this.data[rawText.slice(1)]
-        : rawText;
+    let buttonText = rawText.startsWith("@") ? this.data[rawText.slice(1)] : rawText;
     if (!buttonText) {
         throw new Error(`No value found for alias: "${rawText}"`);
     }

package/{dist → lib}/assertions/elementSteps.js

@@ -59,6 +59,12 @@ const test_1 = require("@playwright/test");
     const el = this.page.locator(selector);
     await (0, test_1.expect)(el).toHaveAttribute(attribute, expected);
 });
+(0, cucumber_1.Then)('I see element attribute "{word}" equals {string}', async function (attr, expected) {
+    if (!this.element) {
+        throw new Error("No element is currently selected. Use a 'find' step before asserting.");
+    }
+    await (0, test_1.expect)(this.element).toHaveAttribute(attr, expected);
+});
 (0, cucumber_1.Then)("I see element has attribute {string}", async function (attr) {
     if (!this.element)
         throw new Error("No element in context");
@@ -66,7 +72,7 @@ const test_1 = require("@playwright/test");
     if (value === null)
         throw new Error(`Attribute "${attr}" not found`);
 });
-(0, cucumber_1.Then)("I see element attribute {string} contains {string}", async function (attr, part) {
+(0, cucumber_1.Then)('I see element attribute "{word}" contains {string}', async function (attr, part) {
     if (!this.element)
         throw new Error("No element in context");
     const value = await this.element.getAttribute(attr);

package/{dist → lib}/assertions/locationSteps.js

@@ -69,3 +69,19 @@ const test_1 = require("@playwright/test");
         throw new Error(`Search does not contain "${part}". Got: "${search}"`);
     }
 });
+(0, cucumber_1.Then)("I see location", async function (table) {
+    const location = await this.page.evaluate(() => ({
+        href: window.location.href,
+        origin: window.location.origin,
+        protocol: window.location.protocol,
+        host: window.location.host,
+        hostname: window.location.hostname,
+        port: window.location.port,
+        pathname: window.location.pathname,
+        search: window.location.search,
+        hash: window.location.hash,
+    }));
+    for (const [key, expected] of table.rows()) {
+        (0, test_1.expect)(location[key]).toBe(expected);
+    }
+});

package/{dist → lib}/assertions/semanticSteps.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const cucumber_1 = require("@cucumber/cucumber");
+const test_1 = require("@playwright/test");
+const optionsUtils_1 = require("../helpers/utils/optionsUtils");
 //
 // 🧠 HEADINGS
 //
 (0, cucumber_1.Then)("I see heading {string}", async function (text) {
-    const heading = await this.page
-        .locator("h1, h2, h3, h4, h5, h6", { hasText: text })
-        .first();
+    const heading = await this.page.locator("h1, h2, h3, h4, h5, h6", { hasText: text }).first();
     if (!(await heading.isVisible())) {
         throw new Error(`Heading "${text}" not found or not visible`);
     }
@@ -52,3 +52,16 @@ const cucumber_1 = require("@cucumber/cucumber");
         throw new Error(`Link "${text}" is visible but should not be`);
     }
 });
+(0, cucumber_1.Then)("I count {int} element", async function (count) {
+    const locator = this.currentLocator ?? this.page.locator("*");
+    await (0, test_1.expect)(locator).toHaveCount(count);
+});
+//document title assertions
+(0, cucumber_1.Then)("I see document title {string}", async function (expected, table) {
+    const options = (0, optionsUtils_1.parseExpectOptions)(table);
+    await (0, test_1.expect)(this.page).toHaveTitle(expected, options);
+});
+(0, cucumber_1.Then)("I see document title contains {string}", async function (substring, table) {
+    const options = (0, optionsUtils_1.parseExpectOptions)(table);
+    await (0, test_1.expect)(this.page).toHaveTitle(new RegExp(substring, "i"), options);
+});

package/{dist → lib}/assertions/visualSteps.js

@@ -3,12 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const cucumber_1 = require("@cucumber/cucumber");
-const pixelmatch_1 = __importDefault(require("pixelmatch"));
-const pngjs_1 = require("pngjs");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const cucumber_1 = require("@cucumber/cucumber");
 const test_1 = require("@playwright/test");
+const pixelmatch_1 = __importDefault(require("pixelmatch"));
+const pngjs_1 = require("pngjs");
 const BASELINE_DIR = path_1.default.resolve("e2e/snapshots/baseline");
 const CURRENT_DIR = path_1.default.resolve("e2e/snapshots/current");
 const DIFF_DIR = path_1.default.resolve("e2e/snapshots/diff");
@@ -36,7 +36,9 @@ function getSnapshotPaths(name) {
     const current = pngjs_1.PNG.sync.read(fs_1.default.readFileSync(paths.current));
     const { width, height } = baseline;
     const diff = new pngjs_1.PNG({ width, height });
-    const pixelDiff = (0, pixelmatch_1.default)(baseline.data, current.data, diff.data, width, height, { threshold: 0.1 });
+    const pixelDiff = (0, pixelmatch_1.default)(baseline.data, current.data, diff.data, width, height, {
+        threshold: 0.1,
+    });
     if (pixelDiff > 0) {
         fs_1.default.writeFileSync(paths.diff, pngjs_1.PNG.sync.write(diff));
         this.log?.(`❌ Visual mismatch detected, diff: ${paths.diff}`);
@@ -63,7 +65,9 @@ function getSnapshotPaths(name) {
     }
     const { width, height } = baseline;
     const diff = new pngjs_1.PNG({ width, height });
-    const pixelDiff = (0, pixelmatch_1.default)(baseline.data, current.data, diff.data, width, height, { threshold: 0.1 });
+    const pixelDiff = (0, pixelmatch_1.default)(baseline.data, current.data, diff.data, width, height, {
+        threshold: 0.1,
+    });
     if (pixelDiff > 0) {
         fs_1.default.writeFileSync(paths.diff, pngjs_1.PNG.sync.write(diff));
         this.log?.(`⚠️ Snapshot mismatch: ${alias}`);

package/lib/custom_setups/loginHooks.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const cucumber_1 = require("@cucumber/cucumber");
+const resolveUtils_1 = require("../helpers/utils/resolveUtils");
+// Step 1: Check and load existing session if valid
+(0, cucumber_1.When)("I login with a session data {string}", async function (sessionName) {
+    const sessionPath = (0, resolveUtils_1.resolveSessionPath)(this, sessionName);
+    this.data.sessionFile = sessionPath;
+    if (fs_1.default.existsSync(sessionPath)) {
+        try {
+            await this.context?.addCookies(JSON.parse(fs_1.default.readFileSync(sessionPath, "utf-8")).cookies || []);
+            this.log?.(`✅ Loaded session from ${sessionPath}`);
+        }
+        catch (err) {
+            this.log?.(`⚠️ Failed to apply session: ${err.message}`);
+        }
+    }
+    else {
+        this.log?.(`⚠️ Session file not found: ${sessionPath}`);
+    }
+});
+// Step 2: Save current context as session
+(0, cucumber_1.When)(/^I save session as "([^"]+)"$/, async function (sessionName) {
+    const sessionPath = (0, resolveUtils_1.resolveSessionPath)(this, sessionName);
+    const cookies = await this.context.cookies();
+    const [localStorageData, sessionStorageData] = await this.page.evaluate(() => {
+        const toPairs = (store) => Object.entries(store);
+        return [
+            [{ origin: location.origin, values: toPairs(localStorage) }],
+            [{ origin: location.origin, values: toPairs(sessionStorage) }],
+        ];
+    });
+    const sessionData = {
+        cookies,
+        localStorage: localStorageData,
+        sessionStorage: sessionStorageData,
+    };
+    try {
+        fs_1.default.writeFileSync(sessionPath, JSON.stringify(sessionData, null, 2));
+        this.log?.(`💾 Saved session as "${sessionName}"`);
+    }
+    catch (err) {
+        this.log?.(`❌ Failed to save session "${sessionName}": ${err.message}`);
+    }
+});
+// Step 3: Remove a session
+(0, cucumber_1.When)("I clear session {string}", function (sessionName) {
+    const sessionPath = (0, resolveUtils_1.resolveSessionPath)(this, sessionName);
+    if (fs_1.default.existsSync(sessionPath)) {
+        fs_1.default.unlinkSync(sessionPath);
+        this.log?.(`🧹 Cleared session: ${sessionPath}`);
+    }
+    else {
+        this.log?.(`⚠️ Session not found: ${sessionPath}`);
+    }
+});
+(0, cucumber_1.When)(/^I restore session cookies "([^"]+)"(?: with reload "(true|false)")?$/, async function (sessionName, reload = "true") {
+    const sessionPath = (0, resolveUtils_1.resolveSessionPath)(this, sessionName);
+    if (!fs_1.default.existsSync(sessionPath)) {
+        this.log?.(`❌ Session file not found: ${sessionPath}`);
+        return;
+    }
+    const sessionData = JSON.parse(fs_1.default.readFileSync(sessionPath, "utf-8"));
+    const { cookies = [], localStorage = [], sessionStorage = [] } = sessionData;
+    try {
+        // Clear & set cookies
+        if (cookies.length) {
+            const existing = await this.context.cookies();
+            if (existing.length)
+                await this.context.clearCookies();
+            await this.context.addCookies(cookies);
+            this.log?.(`🍪 Cookies restored from "${sessionName}"`);
+        }
+        // Apply storage into page context
+        await this.page.goto("about:blank");
+        if (localStorage.length > 0) {
+            for (const entry of localStorage) {
+                await this.page.addInitScript(([origin, values]) => {
+                    if (window.origin === origin) {
+                        for (const [key, val] of values) {
+                            localStorage.setItem(key, val);
+                        }
+                    }
+                }, [entry.origin, entry.values]);
+            }
+            this.log?.("📦 localStorage restored");
+        }
+        if (sessionStorage.length > 0) {
+            for (const entry of sessionStorage) {
+                await this.page.addInitScript(([origin, values]) => {
+                    if (window.origin === origin) {
+                        for (const [key, val] of values) {
+                            sessionStorage.setItem(key, val);
+                        }
+                    }
+                }, [entry.origin, entry.values]);
+            }
+            this.log?.("🗄️ sessionStorage restored");
+        }
+        // Final reload to apply context if requested
+        if (reload !== "false") {
+            await this.page.reload();
+            this.log?.("🔄 Page reloaded to apply restored session");
+        }
+    }
+    catch (err) {
+        this.log?.(`❌ Error restoring session: ${err.message}`);
+    }
+});

package/lib/helpers/hooks.js

@@ -0,0 +1,210 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const cucumber_1 = require("@cucumber/cucumber");
+const dotenv = __importStar(require("dotenv"));
+const playwright_1 = require("playwright");
+const compareSnapshots_1 = require("./compareSnapshots");
+// Set to 30 seconds
+(0, cucumber_1.setDefaultTimeout)(30 * 1000);
+dotenv.config();
+let sharedBrowser;
+(0, cucumber_1.BeforeAll)(async () => {
+    sharedBrowser = await playwright_1.chromium.launch({
+        headless: process.env.HEADLESS !== "false",
+    });
+    console.log("🚀 Launched shared browser for all scenarios");
+});
+(0, cucumber_1.AfterAll)(async () => {
+    await sharedBrowser?.close();
+    console.log("🧹 Closed shared browser after all scenarios");
+});
+(0, cucumber_1.Before)(async function (scenario) {
+    const params = this.parameters || {};
+    const ARTIFACT_DIR = params.artifactDir || process.env.TEST_ARTIFACT_DIR || "test-artifacts";
+    const SCREENSHOT_DIR = path_1.default.resolve(ARTIFACT_DIR, "screenshots");
+    const VIDEO_DIR = path_1.default.resolve(ARTIFACT_DIR, "videos");
+    const TRACE_DIR = path_1.default.resolve(ARTIFACT_DIR, "traces");
+    const SESSION_FILE = path_1.default.resolve(ARTIFACT_DIR, "auth-cookies", "session.json");
+    this.data.artifactDir = ARTIFACT_DIR;
+    this.data.screenshotDir = SCREENSHOT_DIR;
+    this.data.videoDir = VIDEO_DIR;
+    this.data.traceDir = TRACE_DIR;
+    this.data.sessionFile = SESSION_FILE;
+    // Modes: "false" | "fail" | "all"
+    const traceMode = (params.enableTrace || process.env.ENABLE_TRACE || "false").toLowerCase();
+    const screenshotMode = (params.enableScreenshots ||
+        process.env.ENABLE_SCREENSHOTS ||
+        "false").toLowerCase();
+    const videoMode = (params.enableVideos || process.env.ENABLE_VIDEOS || "false").toLowerCase();
+    this.data.traceMode = traceMode;
+    this.data.screenshotMode = screenshotMode;
+    this.data.videoMode = videoMode;
+    const isMobileTag = scenario.pickle.tags.some((t) => t.name === "@mobile");
+    const deviceName = params.device || process.env.MOBILE_DEVICE || (isMobileTag ? "iPhone 13 Pro" : null);
+    const deviceSettings = deviceName ? playwright_1.devices[deviceName] : undefined;
+    if (deviceName && !deviceSettings) {
+        throw new Error(`🚫 Invalid MOBILE_DEVICE: "${deviceName}" is not recognized by Playwright.`);
+    }
+    const isVisualTest = params.enableVisualTest ??
+        (process.env.ENABLE_VISUAL_TEST === "true" ||
+            scenario.pickle.tags.some((t) => t.name === "@visual"));
+    this.data.enableVisualTest = isVisualTest;
+    if (isVisualTest)
+        process.env.VISUAL_TEST = "true";
+    const contextOptions = {
+        ...(videoMode !== "false" ? { recordVideo: { dir: VIDEO_DIR } } : {}),
+        ...(deviceSettings || {}),
+    };
+    if (fs_1.default.existsSync(SESSION_FILE)) {
+        contextOptions.storageState = SESSION_FILE;
+        this.log?.("✅ Reusing session from saved file.");
+    }
+    const context = await sharedBrowser.newContext(contextOptions);
+    const page = await context.newPage();
+    this.browser = sharedBrowser;
+    this.context = context;
+    this.page = page;
+    if (traceMode !== "false") {
+        await context.tracing.start({
+            screenshots: true,
+            snapshots: true,
+            sources: true,
+        });
+        this.data.tracingStarted = true;
+        this.log?.(`🧪 Tracing started (${traceMode})`);
+    }
+    if (deviceName)
+        this.log?.(`📱 Mobile emulation enabled (${deviceName})`);
+});
+(0, cucumber_1.After)(async function (scenario) {
+    const name = scenario.pickle.name.replace(/[^a-z0-9]+/gi, "_").toLowerCase();
+    const failed = scenario.result?.status === "FAILED";
+    const mode = (value) => value?.toLowerCase();
+    const screenshotMode = mode(this.parameters?.enableScreenshots || process.env.ENABLE_SCREENSHOTS);
+    const videoMode = mode(this.parameters?.enableVideos || process.env.ENABLE_VIDEOS);
+    const traceMode = mode(this.parameters?.enableTrace || process.env.ENABLE_TRACE);
+    const shouldSaveScreenshot = screenshotMode === "all" || (screenshotMode === "fail" && failed);
+    const shouldSaveVideo = videoMode === "all" || (videoMode === "fail" && failed);
+    const shouldSaveTrace = traceMode === "all" || (traceMode === "fail" && failed);
+    // 📸 Screenshot
+    if (shouldSaveScreenshot && this.page) {
+        const screenshotPath = path_1.default.join(this.data.screenshotDir, `${failed ? "failed-" : ""}${name}.png`);
+        try {
+            fs_1.default.mkdirSync(this.data.screenshotDir, { recursive: true });
+            await this.page.screenshot({ path: screenshotPath, fullPage: true });
+            console.log(`🖼️ Screenshot saved: ${screenshotPath}`);
+        }
+        catch (err) {
+            console.warn("❌ Failed to save screenshot:", err);
+        }
+    }
+    // 🎥 Video
+    if (this.page && videoMode !== "false") {
+        try {
+            const video = this.page.video();
+            if (video) {
+                const rawPath = await video.path();
+                if (fs_1.default.existsSync(rawPath)) {
+                    const finalPath = path_1.default.join(this.data.videoDir, `${failed ? "failed-" : ""}${name}.webm`);
+                    fs_1.default.mkdirSync(this.data.videoDir, { recursive: true });
+                    shouldSaveVideo ? fs_1.default.renameSync(rawPath, finalPath) : fs_1.default.unlinkSync(rawPath);
+                    console.log(`${shouldSaveVideo ? "🎥 Video saved" : "🧹 Deleted video"}: ${finalPath}`);
+                }
+            }
+        }
+        catch (err) {
+            console.warn(`⚠️ Video error: ${err.message}`);
+        }
+    }
+    // 🧪 Tracing
+    if (this.context && this.data.tracingStarted) {
+        const tracePath = path_1.default.join(this.data.artifactDir, "traces", `${name}.zip`);
+        try {
+            fs_1.default.mkdirSync(path_1.default.dirname(tracePath), { recursive: true });
+            await this.context.tracing.stop({ path: tracePath });
+            shouldSaveTrace
+                ? console.log(`📦 Trace saved: ${tracePath}`)
+                : (fs_1.default.existsSync(tracePath) && fs_1.default.unlinkSync(tracePath),
+                    console.log(`🧹 Trace discarded: ${tracePath}`));
+        }
+        catch (err) {
+            console.warn("❌ Trace handling error:", err);
+        }
+    }
+    // 🧪 Visual regression
+    if (this.page && this.data.enableVisualTest) {
+        const BASELINE_DIR = path_1.default.resolve(this.data.artifactDir, "snapshots/baseline");
+        const DIFF_DIR = path_1.default.resolve(this.data.artifactDir, "snapshots/diff");
+        fs_1.default.mkdirSync(BASELINE_DIR, { recursive: true });
+        fs_1.default.mkdirSync(DIFF_DIR, { recursive: true });
+        const baselinePath = path_1.default.join(BASELINE_DIR, `${name}.png`);
+        const actualPath = path_1.default.join(DIFF_DIR, `${name}.actual.png`);
+        const diffPath = path_1.default.join(DIFF_DIR, `${name}.diff.png`);
+        await this.page.screenshot({ path: actualPath, fullPage: true });
+        if (!fs_1.default.existsSync(baselinePath)) {
+            fs_1.default.copyFileSync(actualPath, baselinePath);
+            console.log(`📸 Created baseline image: ${baselinePath}`);
+        }
+        else {
+            try {
+                const diffPixels = (0, compareSnapshots_1.compareSnapshots)({
+                    actualPath,
+                    baselinePath,
+                    diffPath,
+                    threshold: 0.1,
+                });
+                console.log(diffPixels > 0
+                    ? `⚠️ Visual diff found (${diffPixels} pixels): ${diffPath}`
+                    : "✅ No visual changes detected");
+            }
+            catch (err) {
+                console.warn("❌ Snapshot comparison failed:", err);
+            }
+        }
+    }
+    // Cleanup
+    try {
+        await this.cleanup(scenario);
+    }
+    catch (err) {
+        this.log?.("❌ Error during cleanup: " + err.message);
+    }
+});

package/{dist → lib}/helpers/utils/index.d.ts

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