@playq/core 0.2.77

package/dist/helper/actions/web/formActions.js

@@ -0,0 +1,423 @@
+"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 });
+exports.enter = exports.set = exports.type = exports.input = void 0;
+exports.fill = fill;
+exports.append = append;
+exports.selectOption = selectOption;
+exports.uploadFile = uploadFile;
+exports.selectOptionByIndex = selectOptionByIndex;
+exports.selectDropdown = selectDropdown;
+exports.selectDropdownByIndex = selectDropdownByIndex;
+/**
+ * @file formActions.ts
+ *
+ * Form interaction helpers for PlayQ web actions.
+ * Provides fill/select/upload utilities with runner-aware step wrappers,
+ * locator resolution, and screenshot options.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+const allure = __importStar(require("allure-js-commons"));
+const global_1 = require("../../../global");
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const webLocFixture_1 = require("../../fixtures/webLocFixture");
+const waitActions_1 = require("./waitActions");
+const screenshotActions_1 = require("./screenshotActions");
+const vars_1 = require("../../bundle/vars");
+const commActions_1 = require("../commActions");
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_form = allure;
+if (typeof __allureAny_form.step !== 'function') {
+    __allureAny_form.step = async (_n, f) => await f();
+}
+/**
+ * Web: Fill -field: {param} -value: {param} -options: {param}
+ *
+ * Fills a form input field (e.g., text box, textarea) with the specified value.
+ *
+ * @param field - The label, placeholder, id, name, or pattern of the input field (e.g., "Username", "Email", "search").
+ * @param value - The text value to fill in the input field (e.g., "JohnDoe", "test@example.com").
+ * @param options - Optional JSON string or object:
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - pattern: [string] Optional pattern to refine element search. Default: Configured pattern.
+ *   - screenshot: [boolean] Capture a screenshot after filling the input. Default: false.
+ *   - screenshotText: [string] Text description for the screenshot. Default: "".
+ *   - screenshotFullPage: [boolean] Capture a full page screenshot. Default: true.
+ *   - screenshotField: [boolean] Capture screenshot of the field (input element) only. Overrides fullPage. Default: false.
+ *
+ * @example
+ *  Web: Fill -field: "Username" -value: "JohnDoe" -options: "{screenshot: true, screenshotText: 'After filling Username', screenshotField: true}"
+ */
+async function fill(page, field, value, options) {
+    let resolvedvalue = global_1.vars.replaceVariables(value.toString());
+    const options_json = typeof options === "string" ? (0, vars_1.parseLooseJson)(options) : options || {};
+    if (!page)
+        throw new Error("Page not initialized");
+    const { iframe = "", actionTimeout = Number(global_1.vars.getConfigValue("testExecution.actionTimeout")), pattern, screenshot = false, screenshotText = "", screenshotFullPage = true, screenshotField = false, smartIQ_refreshLoc = "", } = options_json || {};
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(`Web: Fill -field: ${field} -value: ${value} -options: ${JSON.stringify(options_json)}`, async () => {
+            await doFill();
+        });
+    }
+    else {
+        await doFill();
+    }
+    async function doFill() {
+        const target = typeof field === "string"
+            ? await (0, webLocFixture_1.webLocResolver)("input", field, page, pattern, smartIQ_refreshLoc)
+            : field;
+        if (iframe) {
+            await (0, waitActions_1.waitForEnabled)(page.frameLocator(iframe).locator(target), actionTimeout);
+            await page
+                .frameLocator(iframe)
+                .locator(target)
+                .fill(resolvedvalue, { timeout: actionTimeout });
+        }
+        else {
+            await (0, waitActions_1.waitForEnabled)(target, actionTimeout);
+            await target.fill(resolvedvalue, { timeout: actionTimeout });
+        }
+        const isFieldScreenshot = screenshotField === true;
+        await (0, screenshotActions_1.processScreenshot)(page, screenshot, screenshotText, !isFieldScreenshot, isFieldScreenshot ? target : undefined);
+    }
+}
+// Friendly aliases
+exports.input = fill;
+exports.type = fill;
+exports.set = fill;
+exports.enter = fill;
+/**
+ * Web: Append -field: {param} -value: {param} -options: {param}
+ *
+ * Appends text to an input or textarea without clearing existing content.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The label, placeholder, id, name, or pattern of the input field
+ * @param value - The text value to append
+ * @param options - Optional JSON string or object:
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - pattern: [string] Optional pattern to refine element search
+ *   - screenshot: [boolean] Capture a screenshot after appending (default: false)
+ *   - screenshotText: [string] Text description for the screenshot
+ *   - screenshotFullPage: [boolean] Capture a full page screenshot (default: true)
+ *   - screenshotField: [boolean] Capture screenshot of the field (input element) only (default: false)
+ */
+async function append(page, field, value, options) {
+    let resolvedvalue = global_1.vars.replaceVariables(value.toString());
+    const options_json = typeof options === "string" ? (0, vars_1.parseLooseJson)(options) : options || {};
+    if (!page)
+        throw new Error("Page not initialized");
+    const { iframe = "", actionTimeout = Number(global_1.vars.getConfigValue("testExecution.actionTimeout")), pattern, screenshot = false, screenshotText = "", screenshotFullPage = true, screenshotField = false, smartIQ_refreshLoc = "", } = options_json || {};
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(`Web: Append -field: ${field} -value: ${value} -options: ${JSON.stringify(options_json)}`, async () => {
+            await doAppend();
+        });
+    }
+    else {
+        await doAppend();
+    }
+    async function doAppend() {
+        const target = typeof field === "string"
+            ? await (0, webLocFixture_1.webLocResolver)("input", field, page, pattern, smartIQ_refreshLoc)
+            : field;
+        if (iframe) {
+            await (0, waitActions_1.waitForEnabled)(page.frameLocator(iframe).locator(target), actionTimeout);
+            await page
+                .frameLocator(iframe)
+                .locator(target)
+                .type(resolvedvalue, { timeout: actionTimeout });
+        }
+        else {
+            await (0, waitActions_1.waitForEnabled)(target, actionTimeout);
+            await target.type(resolvedvalue, { timeout: actionTimeout });
+        }
+        const isFieldScreenshot = screenshotField === true;
+        await (0, screenshotActions_1.processScreenshot)(page, screenshot, screenshotText, !isFieldScreenshot, isFieldScreenshot ? target : undefined);
+    }
+}
+/**
+ * Web: Select Option -field: {param} -value: {param} -options: {param}
+ *
+ * Selects an option in a dropdown by label or value.
+ * Delegates to core `selectDropdown`.
+ *
+ * @param page Playwright Page instance
+ * @param field Dropdown locator or string selector
+ * @param value Option label or value
+ * @param options Optional JSON string or object ({ actionTimeout, pattern })
+ */
+/**
+ * Web: Select Dropdown -field: {param} -value: {param} -options: {param}
+ *
+ * Selects a dropdown option by visible text or value.
+ * Works with both native <select> elements and custom dropdowns.
+ *
+ * @param page - Playwright Page instance
+ * @param field - Locator or label of the dropdown
+ * @param value - Value or label of the option to select
+ * @param options - Optional string or object containing:
+ *   - actionTimeout: custom timeout
+ *   - pattern: extra pattern string for locator resolution
+ *   - screenshot: boolean (default false)
+ *   - screenshotText: text for screenshot description
+ *   - screenshotFullPage: boolean (default true)
+ *   - smartIQ_refreshLoc: optional override for locator refresh key
+ */
+async function selectOption(page, field, value, options) {
+    const resolvedValue = value !== undefined && value !== null ? global_1.vars.replaceVariables(value.toString()) : "";
+    const options_json = typeof options === "string" ? global_1.vars.parseLooseJson(options) : options || {};
+    const { actionTimeout = Number(global_1.vars.getConfigValue("testExecution.actionTimeout")) || 30000, pattern, screenshot = false, screenshotText = "", screenshotFullPage = true, smartIQ_refreshLoc = "" } = options_json;
+    const stepName = `Web: Select Dropdown -field: ${String(field)} -value: ${resolvedValue} -options: ${JSON.stringify(options_json)}`;
+    async function run() {
+        if (!page)
+            throw new Error("Page not initialized");
+        const target = typeof field === "string" ? await (0, webLocFixture_1.webLocResolver)("dropdown", field, page, pattern, actionTimeout, smartIQ_refreshLoc) : field;
+        const tag = await target.evaluate((el) => el.tagName.toLowerCase());
+        try {
+            if (tag === "select") {
+                await target.selectOption({ label: resolvedValue }).catch(async () => { await target.selectOption({ value: resolvedValue }); });
+            }
+            else {
+                await (0, waitActions_1.waitForEnabled)(target, actionTimeout);
+                await target.click();
+                const dropdownOptions = page.locator(`role=option >> text="${resolvedValue}"`);
+                const visibleOption = dropdownOptions.first();
+                if (await visibleOption.isVisible()) {
+                    await visibleOption.click();
+                }
+                else {
+                    await page.locator(`text="${resolvedValue}"`).first().click();
+                }
+            }
+        }
+        catch (e) {
+            throw new Error(`❌ Failed to select "${resolvedValue}" from dropdown: ${e}`);
+        }
+        await (0, screenshotActions_1.processScreenshot)(page, screenshot, screenshotText || `Select: ${resolvedValue}`, screenshotFullPage);
+    }
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(stepName, run);
+    }
+    else {
+        await run();
+    }
+}
+/**
+ * Web: Upload File -field: {param} -file: {param} -options: {param}
+ *
+ * Uploads a file to an input element.
+ * Delegates to core `uploadFile`.
+ *
+ * @param page Playwright Page instance
+ * @param field File input locator or string selector
+ * @param file Local file path
+ * @param options Optional JSON string or object ({ actionTimeout })
+ */
+async function uploadFile(page, field, file, options) {
+    const projectRoot = process.env['PLAYQ_PROJECT_ROOT'] || process.cwd();
+    let filePath = file;
+    if (!path_1.default.isAbsolute(filePath)) {
+        const basePath = path_1.default.resolve(projectRoot, 'test-data');
+        filePath = path_1.default.resolve(basePath, file);
+    }
+    filePath = path_1.default.normalize(filePath);
+    if (!fs_1.default.existsSync(filePath)) {
+        throw new Error(`File not found for upload: ${filePath}`);
+    }
+    const options_json = typeof options === "string" ? global_1.vars.parseLooseJson(options) : options || {};
+    const { actionTimeout = Number(global_1.vars.getConfigValue("testExecution.actionTimeout")) || 10000, screenshot = false, screenshotText = "", screenshotFullPage = true, pattern } = options_json || {};
+    const stepName = `Web: Upload file at -field: ${String(field)} with filename: ${file} -options: ${JSON.stringify(options_json)}`;
+    async function run() {
+        if (!page)
+            throw new Error("Page not initialized");
+        const target = typeof field === "string" ? await (0, webLocFixture_1.webLocResolver)("input", field, page, pattern, actionTimeout) : field;
+        await target.waitFor({ state: "visible", timeout: actionTimeout });
+        const tag = await target.evaluate((el) => ({ tag: el.tagName.toLowerCase(), type: el.getAttribute('type') || '' }));
+        if (tag.tag === 'input' && tag.type.toLowerCase() === 'file') {
+            await target.setInputFiles(filePath, { timeout: actionTimeout });
+        }
+        else {
+            const fileChooserPromise = page.waitForEvent('filechooser');
+            await target.click();
+            const fileChooser = await fileChooserPromise;
+            await fileChooser.setFiles(filePath);
+        }
+    }
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(stepName, run);
+    }
+    else {
+        await run();
+    }
+}
+/**
+ * Web: Select Dropdown by Index -field: {param} -index: {param} -options: {param}
+ *
+ * Selects a dropdown option by its index (zero-based).
+ * Works with both native <select> elements and custom dropdowns.
+ *
+ * @param page - Playwright Page instance
+ * @param field - Locator or label of the dropdown
+ * @param index - Index of the option to select (zero-based)
+ * @param options - Optional string or object containing:
+ *   - actionTimeout: custom timeout
+ *   - pattern: extra pattern string for locator resolution
+ *   - screenshot: boolean (default false)
+ *   - screenshotText: text for screenshot description
+ *   - screenshotFullPage: boolean (default true)
+ *   - smartIQ_refreshLoc: optional override for locator refresh key
+ */
+async function selectOptionByIndex(page, field, index, options) {
+    const options_json = typeof options === "string" ? global_1.vars.parseLooseJson(options) : options || {};
+    const { actionTimeout = Number(global_1.vars.getConfigValue("testExecution.actionTimeout")) || 30000, pattern, screenshot = false, screenshotText = "", screenshotFullPage = true, smartIQ_refreshLoc = "" } = options_json;
+    const stepName = `Web: Select Dropdown by Index -field: ${String(field)} -index: ${index} -options: ${JSON.stringify(options_json)}`;
+    async function run() {
+        if (!page)
+            throw new Error("Page not initialized");
+        const target = typeof field === "string" ? await (0, webLocFixture_1.webLocResolver)("dropdown", field, page, pattern, actionTimeout, smartIQ_refreshLoc) : field;
+        const tag = await target.evaluate((el) => el.tagName.toLowerCase());
+        try {
+            if (tag === "select") {
+                const optionsCount = await target.locator("option").count();
+                if (index < 0 || index >= optionsCount) {
+                    throw new Error(`❌ Index ${index} is out of bounds for dropdown with ${optionsCount} options`);
+                }
+                const optionLocator = target.locator("option").nth(index);
+                const value = await optionLocator.getAttribute("value");
+                await target.selectOption({ value });
+            }
+            else {
+                await target.click();
+                const dropdownOptions = page.locator('role=option');
+                const optionCount = await dropdownOptions.count();
+                if (index < 0 || index >= optionCount) {
+                    throw new Error(`❌ Index ${index} is out of bounds for custom dropdown with ${optionCount} options`);
+                }
+                const optionToClick = dropdownOptions.nth(index);
+                await optionToClick.click();
+            }
+        }
+        catch (e) {
+            throw new Error(`❌ Failed to select index ${index} from dropdown: ${e}`);
+        }
+        await (0, screenshotActions_1.processScreenshot)(page, screenshot, screenshotText || `Select dropdown index: ${index}`, screenshotFullPage);
+    }
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(stepName, run);
+    }
+    else {
+        await run();
+    }
+}
+/**
+ * Web: Select Dropdown -field: {param} -value: {param} -options: {param}
+ *
+ * Selects a dropdown option by visible text or value.
+ * Works with both native <select> elements and custom dropdowns.
+ *
+ * @param page - Playwright Page instance
+ * @param field - Locator or label of the dropdown
+ * @param value - Value or label of the option to select
+ * @param options - Optional string or object containing:
+ *   - actionTimeout: custom timeout
+ *   - pattern: extra pattern string for locator resolution
+ *   - screenshot: boolean (default false)
+ *   - screenshotText: text for screenshot description
+ *   - screenshotFullPage: boolean (default true)
+ *   - smartIQ_refreshLoc: optional override for locator refresh key
+ */
+async function selectDropdown(page, field, value, options) {
+    const resolvedValue = value !== undefined && value !== null
+        ? global_1.vars.replaceVariables(value.toString())
+        : "";
+    const options_json = typeof options === "string" ? (0, vars_1.parseLooseJson)(options) : options || {};
+    const { actionTimeout, pattern, screenshot = false, screenshotText = "", screenshotFullPage = true, smartIQ_refreshLoc = "", } = options_json;
+    if (isPlaywrightRunner()) {
+        await __allureAny_form.step(`Web: Select Dropdown -field: ${field} -value: ${resolvedValue} -options: ${JSON.stringify(options_json)}`, async () => {
+            await doSelectDropdown();
+        });
+    }
+    else {
+        await doSelectDropdown();
+    }
+    async function doSelectDropdown() {
+        if (!page)
+            throw new Error("Page not initialized");
+        // Resolve dropdown element
+        const target = typeof field === "string"
+            ? await (0, webLocFixture_1.webLocResolver)("dropdown", field, page, pattern, actionTimeout, smartIQ_refreshLoc)
+            : field;
+        // Determine tag
+        const tag = await target.evaluate((el) => el.tagName.toLowerCase());
+        try {
+            if (tag === "select") {
+                // Native select dropdown
+                await target.selectOption({ label: resolvedValue }).catch(async () => {
+                    await target.selectOption({ value: resolvedValue });
+                });
+            }
+            else {
+                await (0, commActions_1.waitInMilliSeconds)(2000);
+                // Custom dropdown: aria-haspopup or role-based
+                await target.click();
+                const dropdownOptions = page.locator(`role=option >> text="${resolvedValue}"`);
+                const visibleOption = dropdownOptions.first();
+                if (await visibleOption.isVisible()) {
+                    await visibleOption.click();
+                }
+                else {
+                    // Fallback to plain text match
+                    await page.locator(`text="${resolvedValue}"`).first().click();
+                }
+            }
+        }
+        catch (e) {
+            throw new Error(`❌ Failed to select "${resolvedValue}" from dropdown: ${e}`);
+        }
+        await (0, screenshotActions_1.processScreenshot)(page, screenshot, screenshotText || `Select: ${resolvedValue}`, screenshotFullPage);
+    }
+}
+/**
+ * Alias: Select Dropdown by Index (wrapper to selectOptionByIndex)
+ */
+async function selectDropdownByIndex(page, field, index, options) {
+    return selectOptionByIndex(page, field, index, options);
+}

package/dist/helper/actions/web/iframeActions.d.ts

@@ -0,0 +1,23 @@
+import type { Page, Frame, Locator } from "playwright";
+/**
+ * Web: Switch To Frame -selector: {param} -options: {param}
+ *
+ * Switches execution context to the specified iframe.
+ *
+ * @param page - Playwright Page instance
+ * @param frameSelector - Frame locator or string selector
+ * @param options - Optional JSON string or object ({ pattern, actionTimeout })
+ * @returns The resolved `Frame`
+ * @throws Error if page is not initialized or frame not found
+ */
+export declare function switchToFrame(page: Page, frameSelector: string | Locator, options?: string | Record<string, any>): Promise<Frame>;
+/**
+ * Web: Switch To Main Content -options: {param}
+ *
+ * Returns to the main document context.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Optional JSON string or object (reserved)
+ * @throws Error if page is not initialized
+ */
+export declare function switchToMainContent(page: Page, options?: string | Record<string, any>): Promise<void>;

package/dist/helper/actions/web/iframeActions.js

@@ -0,0 +1,108 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.switchToFrame = switchToFrame;
+exports.switchToMainContent = switchToMainContent;
+/**
+ * @file iframeActions.ts
+ *
+ * Frame switching helpers for PlayQ web actions.
+ * Provides utilities to switch to a specific iframe and back to main content
+ * with runner-aware step wrappers and robust error handling.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+const allure = __importStar(require("allure-js-commons"));
+const global_1 = require("../../../global");
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_iframe = allure;
+if (typeof __allureAny_iframe.step !== 'function') {
+    __allureAny_iframe.step = async (_n, f) => await f();
+}
+/**
+ * Web: Switch To Frame -selector: {param} -options: {param}
+ *
+ * Switches execution context to the specified iframe.
+ *
+ * @param page - Playwright Page instance
+ * @param frameSelector - Frame locator or string selector
+ * @param options - Optional JSON string or object ({ pattern, actionTimeout })
+ * @returns The resolved `Frame`
+ * @throws Error if page is not initialized or frame not found
+ */
+async function switchToFrame(page, frameSelector, options) {
+    if (!page)
+        throw new Error("Page not initialized");
+    const options_json = typeof options === 'string' ? global_1.vars.parseLooseJson(options) : options || {};
+    const locator = typeof frameSelector === 'string'
+        ? await (0, global_1.webLocResolver)((options_json === null || options_json === void 0 ? void 0 : options_json.fieldType) || '', frameSelector, page, options_json === null || options_json === void 0 ? void 0 : options_json.pattern, typeof (options_json === null || options_json === void 0 ? void 0 : options_json.actionTimeout) === 'number' ? options_json.actionTimeout : undefined, (options_json === null || options_json === void 0 ? void 0 : options_json.smartAiRefresh) || '')
+        : frameSelector;
+    let frame = null;
+    const stepName = `Web: Switch To Frame -selector: ${typeof frameSelector === 'string' ? frameSelector : '<locator>'}`;
+    if (isPlaywrightRunner()) {
+        await __allureAny_iframe.step(stepName, async () => {
+            frame = await locator.elementHandle().then(h => (h === null || h === void 0 ? void 0 : h.contentFrame()) || null);
+            if (!frame)
+                throw new Error('Frame not found');
+        });
+    }
+    else {
+        frame = await locator.elementHandle().then(h => (h === null || h === void 0 ? void 0 : h.contentFrame()) || null);
+        if (!frame)
+            throw new Error('Frame not found');
+    }
+    return frame;
+}
+/**
+ * Web: Switch To Main Content -options: {param}
+ *
+ * Returns to the main document context.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Optional JSON string or object (reserved)
+ * @throws Error if page is not initialized
+ */
+async function switchToMainContent(page, options) {
+    if (!page)
+        throw new Error("Page not initialized");
+    const stepName = `Web: Switch To Main Content`;
+    if (isPlaywrightRunner()) {
+        await __allureAny_iframe.step(stepName, async () => { });
+    }
+    else {
+        /* No-op */
+    }
+}

package/dist/helper/actions/web/javascriptActions.d.ts

@@ -0,0 +1,14 @@
+import type { Page } from "playwright";
+/**
+ * Web: Execute Script -options: {param}
+ *
+ * Executes a function in the browser context via `page.evaluate`.
+ *
+ * @param page - Playwright Page instance
+ * @param fn - Function to execute in the page context
+ * @param args - Optional array passed as a single argument to the function
+ * @returns The function result
+ * @throws Error if page is not initialized or `fn` is not a function
+ */
+export declare function execute<T>(page: Page, fn: (...args: any[]) => any, args?: any[]): Promise<any>;
+export declare const executeScript: typeof execute;

package/dist/helper/actions/web/javascriptActions.js

@@ -0,0 +1,77 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeScript = void 0;
+exports.execute = execute;
+/**
+ * @file javascriptActions.ts
+ *
+ * Execute custom JavaScript in the page context with PlayQ.
+ * Wraps page.evaluate with reporting-friendly step wrappers.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+const allure = __importStar(require("allure-js-commons"));
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_js = allure;
+if (typeof __allureAny_js.step !== 'function') {
+    __allureAny_js.step = async (_n, f) => await f();
+}
+/**
+ * Web: Execute Script -options: {param}
+ *
+ * Executes a function in the browser context via `page.evaluate`.
+ *
+ * @param page - Playwright Page instance
+ * @param fn - Function to execute in the page context
+ * @param args - Optional array passed as a single argument to the function
+ * @returns The function result
+ * @throws Error if page is not initialized or `fn` is not a function
+ */
+async function execute(page, fn, args) {
+    if (!page)
+        throw new Error("Page not initialized");
+    if (typeof fn !== 'function')
+        throw new Error("javascript.execute: 'fn' must be a function");
+    const stepName = `Web: Execute Script`;
+    const run = async () => page.evaluate(fn, ...(args ? [args] : []));
+    if (isPlaywrightRunner()) {
+        return __allureAny_js.step(stepName, run);
+    }
+    return run();
+}
+// Friendly aliases
+exports.executeScript = execute;

package/dist/helper/actions/web/keyboardActions.d.ts

@@ -0,0 +1,35 @@
+import { Page } from "@playwright/test";
+/**
+ * Web: Press Key -key: {param} -options: {param}
+ *
+ * Presses a keyboard key on the page or a specific element.
+ *
+ * @param page - Playwright Page instance
+ * @param key - The key to press (e.g., "Enter", "Tab", "ArrowDown", "a", etc.)
+ * @param options - Optional string or object:
+ *   - screenshot: [boolean] Capture screenshot after pressing the key. Default: false.
+ *   - screenshotText: [string] Description for the screenshot. Default: "".
+ *   - screenshotFullPage: [boolean] Full page screenshot. Default: true.
+ *
+ * @example
+ *   await pressKey(page, 'Enter', { field: 'Username', screenshot: true });
+ */
+export declare function pressKey(page: Page, key: string, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Press Enter -options: {param}
+ *
+ * Convenience wrapper to press the Enter key.
+ *
+ * @param page Playwright Page instance
+ * @param options Optional JSON string or object ({ delay })
+ */
+export declare function pressEnter(page: Page, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Press Tab -options: {param}
+ *
+ * Convenience wrapper to press the Tab key.
+ *
+ * @param page Playwright Page instance
+ * @param options Optional JSON string or object ({ delay })
+ */
+export declare function pressTab(page: Page, options?: string | Record<string, any>): Promise<void>;