@playq/core 0.2.77

package/src/helper/actions/stepGroupStepDefs.ts

@@ -0,0 +1,17 @@
+import { Given, When, Then } from "@cucumber/cucumber";
+
+Given("Step Group: {param} {param}", async function (stepGroupName, stepGroupDesc) {
+  console.error(`❌ Step Group not available: ${stepGroupName} | ${stepGroupDesc}`);
+});
+
+Given("- Step Group - START: {param} Desc: {param}", async function (stepGroupName, stepGroupDesc) {
+  console.log(`-> Step Group [START]: ${stepGroupName} | ${stepGroupDesc}`);
+});
+
+Given("- Step Group - END: {string}", async function (stepGroupName) {
+  console.log(`-> Step Group [END]: ${stepGroupName}`);
+});
+
+Given("Step Group: tests", async function (stepGroupName, stepGroupDesc) {
+  console.error(`❌ Step Group not available: ${stepGroupName} | ${stepGroupDesc}`);
+});

package/src/helper/actions/web/alertActions.ts

@@ -0,0 +1,179 @@
+/**
+ * @file alertActions.ts
+ *
+ * Browser alert handling actions for PlayQ across Playwright and Cucumber.
+ * Provides accept, dismiss, fill, and verification of alert messages with
+ * runner-aware logging and Allure-compatible step wrappers.
+ *
+ * Key Features:
+ * - Hybrid runner support (Playwright/Cucumber) via lightweight shims
+ * - Consistent step naming for reporting and traceability
+ * - Attaches alert text to reports where available
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import * as allure from "allure-js-commons";
+import { Page } from "@playwright/test";
+import { vars, comm } from "../../../global";
+import { processScreenshot } from "./screenshotActions";
+
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_alert: any = allure as any;
+if (typeof __allureAny_alert.step !== 'function') { __allureAny_alert.step = async (_n: string, f: any) => await f(); }
+
+/**
+ * Web: Accept Alert -options: {param}
+ *
+ * Waits for a browser alert and accepts it. Attaches the alert text and optionally captures a screenshot.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Optional JSON string or object:
+ *  - actionTimeout: [number] Timeout to wait for alert (default: config or 10000)
+ *  - screenshot: [boolean] Capture screenshot after handling the alert (default: false)
+ *  - screenshotText: [string] Description for screenshot (default: "")
+ *  - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ * @throws Error if page is not initialized or alert does not appear within timeout
+ */
+export async function acceptAlert(page: Page, options?: string | Record<string, any>) {
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const {
+    actionTimeout = Number(vars.getConfigValue("testExecution.actionTimeout")) || 10000,
+    screenshot = false,
+    screenshotText = "",
+    screenshotFullPage = true,
+  } = options_json;
+  const stepName = `Web: Accept Alert -options: ${JSON.stringify(options_json)}`;
+  if (!page) throw new Error("Page not initialized");
+  async function run() {
+    const dialog = await page.waitForEvent('dialog', { timeout: actionTimeout }).catch(() => null);
+    if (!dialog) throw new Error(`❌ No alert appeared within ${actionTimeout}ms`);
+    await comm.attachLog(`Alert Text: ${dialog.message()}`, 'text/plain', 'Alert');
+    await dialog.accept();
+    await processScreenshot(page, screenshot, screenshotText || 'After alert accept', screenshotFullPage);
+  }
+  if (isPlaywrightRunner()) { await __allureAny_alert.step(stepName, run); } else { await run(); }
+}
+
+/**
+ * Web: Dismiss Alert -options: {param}
+ *
+ * Waits for a browser alert and dismisses it. Attaches the alert text and optionally captures a screenshot.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Optional JSON string or object:
+ *  - actionTimeout: [number] Timeout to wait for alert (default: config or 10000)
+ *  - screenshot: [boolean] Capture screenshot after handling the alert (default: false)
+ *  - screenshotText: [string] Description for screenshot (default: "")
+ *  - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ * @throws Error if page is not initialized or alert does not appear within timeout
+ */
+export async function dismissAlert(page: Page, options?: string | Record<string, any>) {
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const {
+    actionTimeout = Number(vars.getConfigValue("testExecution.actionTimeout")) || 10000,
+    screenshot = false,
+    screenshotText = "",
+    screenshotFullPage = true,
+  } = options_json;
+  const stepName = `Web: Dismiss Alert -options: ${JSON.stringify(options_json)}`;
+  if (!page) throw new Error("Page not initialized");
+  async function run() {
+    const dialog = await page.waitForEvent('dialog', { timeout: actionTimeout }).catch(() => null);
+    if (!dialog) throw new Error(`❌ No alert appeared within ${actionTimeout}ms`);
+    await comm.attachLog(`Alert Text: ${dialog.message()}`, 'text/plain', 'Alert');
+    await dialog.dismiss();
+    await processScreenshot(page, screenshot, screenshotText || 'After alert dismiss', screenshotFullPage);
+  }
+  if (isPlaywrightRunner()) { await __allureAny_alert.step(stepName, run); } else { await run(); }
+}
+
+/**
+ * Web: Fill Alert -text: {param} -options: {param}
+ *
+ * Waits for a prompt alert and fills it with the provided text. Attaches the alert text and optionally captures a screenshot.
+ *
+ * @param page - Playwright Page instance
+ * @param text - Text to send to alert prompt
+ * @param options - Optional JSON string or object:
+ *  - actionTimeout: [number] Timeout to wait for alert (default: config or 10000)
+ *  - screenshot: [boolean] Capture screenshot after handling the alert (default: false)
+ *  - screenshotText: [string] Description for screenshot (default: "")
+ *  - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ * @throws Error if page is not initialized or alert does not appear within timeout
+ */
+export async function fillAlert(page: Page, text: string, options?: string | Record<string, any>) {
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const {
+    actionTimeout = Number(vars.getConfigValue("testExecution.actionTimeout")) || 10000,
+    screenshot = false,
+    screenshotText = "",
+    screenshotFullPage = true,
+  } = options_json;
+  const stepName = `Web: Fill Alert -text: ${text} -options: ${JSON.stringify(options_json)}`;
+  if (!page) throw new Error("Page not initialized");
+  async function run() {
+    const dialog = await page.waitForEvent('dialog', { timeout: actionTimeout }).catch(() => null);
+    if (!dialog) throw new Error(`❌ No alert appeared within ${actionTimeout}ms`);
+    await comm.attachLog(`Alert Text: ${dialog.message()}`, 'text/plain', 'Alert');
+    await dialog.accept(text);
+    await processScreenshot(page, screenshot, screenshotText || 'After alert fill', screenshotFullPage);
+  }
+  if (isPlaywrightRunner()) { await __allureAny_alert.step(stepName, run); } else { await run(); }
+}
+
+/**
+ * Web: See Alert Text -expected: {param} -options: {param}
+ *
+ * Verifies the next alert message matches the expected text. Supports partial match and case-insensitive comparison.
+ *
+ * @param page - Playwright Page instance
+ * @param expected - Expected alert text
+ * @param options - Optional JSON string or object:
+ *  - actionTimeout: [number] Timeout to wait for alert (default: config or 10000)
+ *  - partialMatch: [boolean] If true, checks substring instead of exact match (default: false)
+ *  - ignoreCase: [boolean] Case-insensitive comparison (default: false)
+ *  - assert: [boolean] If false, logs failure but does not throw (default: true)
+ *  - screenshot: [boolean] Capture screenshot after verification (default: false)
+ *  - screenshotText: [string] Description for screenshot (default: "")
+ *  - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ */
+export async function seeAlertText(page: Page, expected: string, options?: string | Record<string, any>) {
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const {
+    actionTimeout = Number(vars.getConfigValue("testExecution.actionTimeout")) || 10000,
+    partialMatch = false,
+    ignoreCase = false,
+    assert = true,
+    screenshot = false,
+    screenshotText = "",
+    screenshotFullPage = true,
+  } = options_json;
+  const stepName = `Web: See Alert Text -expected: ${expected} -options: ${JSON.stringify(options_json)}`;
+  if (!page) throw new Error("Page not initialized");
+  async function run() {
+    const dialog = await page.waitForEvent('dialog', { timeout: actionTimeout }).catch(() => null);
+    if (!dialog) {
+      const msg = `❌ No alert appeared within ${actionTimeout}ms`;
+      await comm.attachLog(msg, 'text/plain', 'Alert');
+      if (assert) throw new Error(msg);
+      return;
+    }
+    let msg = dialog.message();
+    await comm.attachLog(`Alert Text: ${msg}`, 'text/plain', 'Alert');
+    let exp = vars.replaceVariables(expected);
+    let actual = msg;
+    if (ignoreCase) { exp = exp.toLowerCase(); actual = actual.toLowerCase(); }
+    const matched = partialMatch ? actual.includes(exp) : actual === exp;
+    if (!matched) {
+      const err = `Alert text mismatch: expected '${expected}'${partialMatch ? " (partial)" : ""}, got '${msg}'`;
+      await comm.attachLog(`❌ ${err}`, 'text/plain', 'Validation');
+      if (assert) throw new Error(err);
+    } else {
+      await comm.attachLog(`✅ Alert text matched: '${msg}'`, 'text/plain', 'Validation');
+    }
+    await dialog.dismiss();
+    await processScreenshot(page, screenshot, screenshotText || 'After alert verification', screenshotFullPage);
+  }
+  if (isPlaywrightRunner()) { await __allureAny_alert.step(stepName, run); } else { await run(); }
+}

package/src/helper/actions/web/cookieActions.ts

@@ -0,0 +1,124 @@
+/**
+ * @file cookieActions.ts
+ *
+ * Cookie management utilities for PlayQ web tests.
+ * Supports setting, reading, and clearing cookies with reporting-friendly
+ * step wrappers compatible with Playwright and Cucumber runners.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import * as allure from "allure-js-commons";
+import type { Page } from "playwright";
+import { vars } from "../../../global";
+
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_cookie: any = allure as any;
+if (typeof __allureAny_cookie.step !== 'function') { __allureAny_cookie.step = async (_n: string, f: any) => await f(); }
+
+/**
+ * Web: Set Cookie -name: {param} -value: {param} -options: {param}
+ *
+ * Adds a cookie for the current page URL.
+ *
+ * @param page - Playwright Page instance
+ * @param name - Cookie name
+ * @param value - Cookie value
+ * @param options - Optional JSON string or object with cookie attributes:
+ *  - domain, path, sameSite, secure, httpOnly, expires
+ * @throws Error if page is not initialized or required params are missing
+ */
+export async function setCookie(page: Page, name: string, value: string, options?: string | Record<string, any>) {
+  if (!page) throw new Error("Page not initialized");
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const stepName = `Web: Set Cookie -name: ${name}`;
+  if (!name) throw new Error("Cookie.setCookie: 'name' is required");
+  if (value === undefined || value === null) throw new Error("Cookie.setCookie: 'value' is required");
+  const ctx = page.context();
+  const cookie: any = { name, value };
+
+  // Precedence: explicit url > domain/path > current page url
+  const explicitUrl = options_json?.url;
+  const explicitDomain = options_json?.domain;
+  const explicitPath = options_json?.path;
+
+  if (explicitUrl) {
+    // When url is specified, do not include domain/path
+    cookie.url = explicitUrl;
+  } else if (explicitDomain || explicitPath) {
+    // When domain/path are specified, do not include url
+    if (explicitDomain) cookie.domain = explicitDomain;
+    cookie.path = explicitPath || '/';
+  } else {
+    // Default to current page url if no domain/path/url provided
+    cookie.url = page.url();
+  }
+
+  if (options_json?.sameSite) cookie.sameSite = options_json.sameSite;
+  if (options_json?.secure !== undefined) cookie.secure = !!options_json.secure;
+  if (options_json?.httpOnly !== undefined) cookie.httpOnly = !!options_json.httpOnly;
+  if (typeof options_json?.expires === 'number') cookie.expires = options_json.expires;
+  if (isPlaywrightRunner()) { await __allureAny_cookie.step(stepName, async () => { await ctx.addCookies([cookie]); }); }
+  else { await ctx.addCookies([cookie]); }
+}
+
+/**
+ * Web: Get Cookie -name: {param}
+ *
+ * Retrieves the value of a cookie by name.
+ *
+ * @param page - Playwright Page instance
+ * @param name - Cookie name
+ * @param options - Optional JSON string or object: { assert?: boolean }
+ * @returns Cookie value or undefined
+ * @throws Error if page is not initialized or when assert=true and cookie missing
+ */
+export async function getCookie(page: Page, name: string, options?: string | Record<string, any>) {
+  if (!page) throw new Error("Page not initialized");
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const stepName = `Web: Get Cookie -name: ${name}`;
+  const run = async () => {
+    const cookies = await page.context().cookies(page.url());
+    const val = cookies.find(c => c.name === name)?.value;
+    if (options_json?.assert === true && (val === undefined || val === null)) {
+      throw new Error(`Cookie.getCookie: No cookie found with name '${name}'`);
+    }
+    return val;
+  };
+  if (isPlaywrightRunner()) { return __allureAny_cookie.step(stepName, run); }
+  return run();
+}
+
+/**
+ * Web: Delete Cookie -name: {param}
+ *
+ * Clears cookies. Note: Playwright API does not support deleting a single cookie directly; this clears all cookies in context.
+ *
+ * @param page - Playwright Page instance
+ * @param name - Cookie name (for reporting only)
+ * @throws Error if page is not initialized
+ */
+export async function deleteCookie(page: Page, name: string) {
+  if (!page) throw new Error("Page not initialized");
+  const stepName = `Web: Delete Cookie -name: ${name}`;
+  const run = async () => {
+    const ctx = page.context();
+    await ctx.clearCookies();
+  };
+  if (isPlaywrightRunner()) { await __allureAny_cookie.step(stepName, run); } else { await run(); }
+}
+
+/**
+ * Web: Clear Cookies
+ *
+ * Clears all cookies in the current browser context.
+ *
+ * @param page - Playwright Page instance
+ * @throws Error if page is not initialized
+ */
+export async function clearCookies(page: Page) {
+  if (!page) throw new Error("Page not initialized");
+  const stepName = `Web: Clear Cookies`;
+  const run = async () => { await page.context().clearCookies(); };
+  if (isPlaywrightRunner()) { await __allureAny_cookie.step(stepName, run); } else { await run(); }
+}

package/src/helper/actions/web/downloadActions.ts

@@ -0,0 +1,129 @@
+/**
+ * @file downloadActions.ts
+ *
+ * Simple filesystem helpers used in web download scenarios.
+ * Provides directory listing and file existence checks with
+ * Allure-compatible step wrappers.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import * as allure from "allure-js-commons";
+import * as fs from "fs";
+import * as path from "path";
+import type { Page, Locator } from "playwright";
+import { vars, webLocResolver } from "../../../global";
+import { waitForPageToLoad } from "./waitActions";
+import { processScreenshot } from "./screenshotActions";
+
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+const __allureAny_dl: any = allure as any;
+if (typeof __allureAny_dl.step !== 'function') { __allureAny_dl.step = async (_n: string, f: any) => await f(); }
+
+/**
+ * Web: List Files -dir: {param}
+ *
+ * Lists files in the given directory.
+ *
+ * @param dirPath - Directory path
+ * @returns Array of filenames or empty list if directory does not exist
+ * @throws Error if `dirPath` is empty
+ */
+export async function listFiles(dirPath: string) {
+  if (!dirPath) throw new Error("download.listFiles: 'dirPath' is required");
+  const abs = path.resolve(dirPath);
+  const stepName = `Web: List Files -dir: ${abs}`;
+  const run = async () => fs.existsSync(abs) ? fs.readdirSync(abs) : [];
+  if (isPlaywrightRunner()) { return __allureAny_dl.step(stepName, run); }
+  return run();
+}
+
+/**
+ * Web: Has File -dir: {param} -fileName: {param}
+ *
+ * Checks if a file exists in the directory listing.
+ *
+ * @param dirPath - Directory path
+ * @param fileName - File name to check
+ * @returns True if present; false otherwise
+ * @throws Error if `dirPath` or `fileName` is empty
+ */
+export async function hasFile(dirPath: string, fileName: string) {
+  if (!dirPath) throw new Error("download.hasFile: 'dirPath' is required");
+  if (!fileName) throw new Error("download.hasFile: 'fileName' is required");
+  const stepName = `Web: Has File -dir: ${path.resolve(dirPath)} -fileName: ${fileName}`;
+  const run = async () => {
+    const files = await listFiles(dirPath);
+    return files.includes(fileName);
+  };
+  if (isPlaywrightRunner()) { return __allureAny_dl.step(stepName, run); }
+  return run();
+}
+
+/**
+ * Web: Download File -field: {param} -options: {param}
+ *
+ * Triggers a download by clicking the target element and saves it to a directory.
+ *
+ * @param page - Playwright Page instance
+ * @param field - Button/link text, selector, or Locator to click (e.g., 'Download Text')
+ * @param options - Optional JSON string or object:
+ *  - pattern: [string] Locator pattern namespace (e.g., 'letcodesamples')
+ *  - locatorCategory: [string] 'button' | 'link' (default 'button') used by webLocResolver
+ *  - targetDir: [string] Directory to save file (default: PLAYQ_PROJECT_ROOT/_Temp/downloads)
+ *  - fileName: [string] Override file name; default is suggested filename
+ *  - actionTimeout: [number] Timeout for waits/clicks (default from config/testExecution)
+ *  - screenshot, screenshotText, screenshotFullPage, screenshotBefore: screenshot options
+ *
+ * @returns Saved file absolute path
+ */
+export async function downloadFile(
+  page: Page,
+  field: string | Locator,
+  options?: string | Record<string, any>
+) {
+  if (!page) throw new Error("Page not initialized");
+  const options_json = typeof options === 'string' ? vars.parseLooseJson(options) : options || {};
+  const {
+    pattern,
+    locatorCategory = 'button',
+    targetDir,
+    fileName,
+    actionTimeout = Number(vars.getConfigValue("testExecution.actionTimeout")) || 60000,
+    screenshot = false,
+    screenshotText = "",
+    screenshotFullPage = true,
+    screenshotBefore = false,
+  } = options_json || {};
+
+  const resolvedField = typeof field === 'string' ? vars.replaceVariables(field) : field;
+  const stepName = `Web: Download File -field: ${typeof resolvedField === 'string' ? resolvedField : '<locator>'}`;
+
+  const run = async () => {
+    await waitForPageToLoad(page, actionTimeout);
+    const target =
+      typeof resolvedField === 'string'
+        ? await webLocResolver(locatorCategory, resolvedField, page, pattern, actionTimeout)
+        : resolvedField;
+
+    await processScreenshot(page, screenshotBefore, screenshotText, screenshotFullPage);
+
+    const [download] = await Promise.all([
+      page.waitForEvent('download', { timeout: actionTimeout }),
+      (target as any).click({ timeout: actionTimeout })
+    ]);
+
+    const suggested = download.suggestedFilename();
+    const root = (targetDir ? path.resolve(targetDir) : path.join(process.env.PLAYQ_PROJECT_ROOT || process.cwd(), '_Temp', 'downloads'));
+    if (!fs.existsSync(root)) fs.mkdirSync(root, { recursive: true });
+    const finalName = fileName || suggested;
+    const savePath = path.join(root, finalName);
+    await download.saveAs(savePath);
+
+    await processScreenshot(page, screenshot, screenshotText, screenshotFullPage);
+    return savePath;
+  };
+
+  if (isPlaywrightRunner()) { return __allureAny_dl.step(stepName, run); }
+  return run();
+}