@playq/core 0.2.77

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

@@ -0,0 +1,53 @@
+/**
+ * @file reportingActions.ts
+ *
+ * Lightweight reporting helpers for PlayQ web actions.
+ * Attaches info/pass/fail messages to the test report via comm fixture.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import { comm } from "../../../global";
+
+/**
+ * Web: Log Info -message: {param}
+ *
+ * Attaches an informational log message to the test report.
+ *
+ * @param message - Message to attach
+ */
+export async function logInfo(message: string) { await comm.attachLog(message, 'text/plain', 'INFO'); }
+
+/**
+ * Web: Log Pass -message: {param}
+ *
+ * Attaches a success log message to the test report.
+ *
+ * @param message - Message to attach
+ */
+export async function logPass(message: string) { await comm.attachLog(`✅ ${message}`, 'text/plain', 'PASS'); }
+
+/**
+ * Web: Log Fail -message: {param}
+ *
+ * Attaches a failure log message to the test report.
+ *
+ * @param message - Message to attach
+ */
+export async function logFail(message: string) { await comm.attachLog(`❌ ${message}`, 'text/plain', 'FAIL'); }
+
+/**
+ * Web: Assert -condition: {param} -message: {param}
+ *
+ * Asserts a condition and logs pass/fail. Throws on failure.
+ *
+ * @param condition - Condition to assert
+ * @param message - Optional message to include in logs and error
+ */
+export async function assert(condition: boolean, message?: string) {
+  if (!condition) { await logFail(message || 'Assertion failed'); throw new Error(message || 'Assertion failed'); }
+  await logPass(message || 'Assertion passed');
+}
+
+// Friendly aliases
+export const assertLog = assert;

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

@@ -0,0 +1,124 @@
+/**
+ * @file screenshotActions.ts
+ *
+ * Screenshot helpers for PlayQ web actions.
+ * Provides takeScreenshot and internal processScreenshot with hybrid
+ * runner support (Playwright/Cucumber) and robust attachment fallbacks.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as allure from "allure-js-commons";
+import { Page, Locator } from "@playwright/test";
+import { webFixture } from "../../../global";
+import { waitForPageToLoad } from "./waitActions";
+import { parseLooseJson } from '../../bundle/vars';
+
+function isPlaywrightRunner() { return process.env.TEST_RUNNER === 'playwright'; }
+function isCucumberRunner() { return process.env.TEST_RUNNER === 'cucumber'; }
+
+const __allureAny_shot: any = allure as any;
+if (typeof __allureAny_shot.step !== 'function') {
+  __allureAny_shot.step = async (_name: string, fn: any) => await fn();
+}
+
+/**
+ * Takes a screenshot of the provided Playwright page.
+ *
+ * @param page - The Playwright Page object to capture.
+ * @param options - Optional screenshot configuration. Can be a JSON string or an object.
+ *   - `screenshot_text` (string): Optional text to annotate the screenshot.
+ *   - `screenshot_fullPage` (boolean): Whether to capture the full page (default: true).
+ * @throws Will throw an error if the page is not initialized.
+ * @remarks
+ * Waits for the page to load before taking the screenshot.
+ */
+export async function takeScreenshot(
+  page: Page,
+  options?: string | Record<string, any>
+) {
+  const options_json =
+    typeof options === "string" ? parseLooseJson(options) : options || {};
+  const { screenshot_text = "", screenshot_fullPage = true } = options_json;
+
+  if (!page) throw new Error("Page not initialized");
+  await waitForPageToLoad(page);
+  await processScreenshot(page, true, screenshot_text, screenshot_fullPage);
+}
+
+function persistScreenshotToDisk(buffer: Buffer, text: string) {
+  try {
+    const baseDir = path.resolve(process.cwd(), "test-results", "screenshots");
+    fs.mkdirSync(baseDir, { recursive: true });
+    const safe = (text || "screenshot").toString().toLowerCase().replace(/[^a-z0-9-_]+/gi, "_").slice(0, 80);
+    const file = path.join(baseDir, `${Date.now()}_${safe || "shot"}.png`);
+    fs.writeFileSync(file, buffer);
+    console.log(`📸 Screenshot saved to: ${file}`);
+  } catch (e) {
+    console.warn(`⚠️ Failed to save screenshot to disk: ${e?.message || e}`);
+  }
+}
+
+/**
+ * Web: Process Screenshot -options: {param}
+ *
+ * Internal helper to capture and attach a screenshot.
+ *
+ * @param page - Playwright Page instance
+ * @param shouldTake - Whether to capture
+ * @param text - Attachment text
+ * @param fullPage - Full page flag
+ * @param selector - Optional Locator to screenshot
+ */
+export async function processScreenshot(
+  page: Page,
+  shouldTake: boolean,
+  text: string = "Screenshot",
+  fullPage: boolean = true,
+  selector?: Locator
+) {
+  if (!shouldTake) return;
+  if (!page) throw new Error("Page not initialized for screenshot");
+  const screenshotBuffer = selector
+    ? await selector.screenshot()
+    : await page.screenshot({ fullPage });
+
+  try {
+    if (isCucumberRunner()) {
+      const world = webFixture.getWorld();
+      if (world && typeof world.attach === "function") {
+        await world.attach(screenshotBuffer, "image/png");
+        await world.attach(`Screenshot Text: ${text}`, "text/plain");
+        console.log(`✅ Screenshot attached via Cucumber World: ${text}`);
+      } else {
+        console.warn(`⚠️ No Cucumber World context. Screenshot not attached.`);
+      }
+    } else if (isPlaywrightRunner()) {
+      const { test } = await import("@playwright/test");
+      await test
+        .info()
+        .attach(text, { body: screenshotBuffer, contentType: "image/png" });
+      console.log(`✅ Screenshot attached via Playwright: ${text}`);
+    } else {
+      console.warn(`⚠️ Unknown runner context. Screenshot not attached.`);
+    }
+  } catch (error) {
+    console.warn(`⚠️ Error attaching screenshot: ${error.message}`);
+  }
+}
+
+/**
+ * Web: Take Full Screenshot -options: {param}
+ *
+ * Captures a full-page screenshot by delegating to `takeScreenshot` with defaults.
+ *
+ * @param page - Playwright Page instance
+ * @param options - Optional JSON string or object (merged with defaults)
+ */
+export async function takeFullScreenshot(page: Page, options?: string | Record<string, any>) {
+  const defaults = { screenshot: true, screenshotFullPage: true };
+  let opts = typeof options === 'string' ? defaults : { ...defaults, ...(options || {}) };
+  return takeScreenshot(page, opts as any);
+}

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

@@ -0,0 +1,162 @@
+/**
+ * @file testDataActions.ts
+ *
+ * Test data helpers for PlayQ web actions.
+ * Supports JSON and CSV loading plus sample data generation via faker.
+ *
+ * Authors: PlayQ Team
+ * Version: v1.0.0
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { faker } from "../../../global";
+
+/**
+ * Web: Load Test Data JSON -file: {param}
+ *
+ * Loads and parses JSON test data from a file.
+ *
+ * @param filePath - Path to JSON file
+ * @returns Parsed JSON content
+ * @throws Error if file does not exist or JSON parsing fails
+ */
+export async function loadFromJson(filePath: string) {
+  if (!filePath) throw new Error("testData.loadFromJson: 'filePath' is required");
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) throw new Error(`testData.loadFromJson: File not found at '${abs}'`);
+  const content = fs.readFileSync(abs, 'utf-8');
+  try {
+    return JSON.parse(content);
+  } catch (err: any) {
+    throw new Error(`testData.loadFromJson: Failed to parse JSON - ${err?.message || err}`);
+  }
+}
+
+/**
+ * Web: Load Test Data CSV -file: {param}
+ *
+ * Loads CSV test data from a file and returns an array of objects.
+ *
+ * @param filePath - Path to CSV file
+ * @returns Array of row objects keyed by header names
+ * @throws Error if file does not exist or CSV is empty/invalid
+ */
+export async function loadFromCsv(filePath: string) {
+  if (!filePath) throw new Error("testData.loadFromCsv: 'filePath' is required");
+  const abs = path.resolve(filePath);
+  if (!fs.existsSync(abs)) throw new Error(`testData.loadFromCsv: File not found at '${abs}'`);
+  const content = (fs.readFileSync(abs, 'utf-8') || '').trim();
+  if (!content) throw new Error("testData.loadFromCsv: CSV file is empty");
+  const [headerLine, ...rows] = content.split(/\r?\n/);
+  if (!headerLine) throw new Error("testData.loadFromCsv: Missing header line");
+  const headers = headerLine.split(',').map(h => h.trim());
+  return rows.filter(r => r && r.trim().length > 0).map(r => {
+    const cols = r.split(',');
+    const obj: any = {};
+    headers.forEach((h, i) => obj[h] = (cols[i] ?? '').trim());
+    return obj;
+  });
+}
+
+/**
+ * Web: Generate Sample Data -schema: {param}
+ *
+ * Generates sample test data, optionally merged with a provided schema.
+ *
+ * @param schema - Optional object to override default generated fields
+ * @returns Object containing generated sample fields
+ */
+function generateValueByDescriptor(descriptor: string): any {
+  const d = (descriptor || '').toString().toLowerCase().trim();
+  switch (d) {
+    case 'string':
+      return faker?.lorem?.word?.() || 'sample';
+    case 'number':
+    case 'int':
+    case 'integer':
+      return (faker as any)?.number?.int?.({ min: 0, max: 9999 }) ?? 0;
+    case 'float':
+    case 'decimal':
+      return (faker as any)?.number?.float?.({ min: 0, max: 9999, precision: 0.01 }) ?? 0.0;
+    case 'boolean':
+      return Math.random() < 0.5;
+    case 'email':
+      return faker?.internet?.email?.() || 'user@example.com';
+    case 'phone':
+    case 'phonenumber':
+      return faker?.phone?.number?.() || '1234567890';
+    case 'firstname':
+      return faker?.person?.firstName?.() || 'John';
+    case 'lastname':
+      return faker?.person?.lastName?.() || 'Doe';
+    case 'fullname':
+    case 'name':
+      return `${faker?.person?.firstName?.() || 'John'} ${faker?.person?.lastName?.() || 'Doe'}`;
+    case 'uuid':
+      return (faker as any)?.string?.uuid?.() || '00000000-0000-0000-0000-000000000000';
+    case 'date':
+      return new Date().toISOString().slice(0, 10);
+    case 'datetime':
+    case 'isodatetime':
+      return new Date().toISOString();
+    case 'timestamp':
+      return Date.now();
+    case 'url':
+      return faker?.internet?.url?.() || 'https://example.com';
+    case 'ip':
+    case 'ipv4':
+      return (faker as any)?.internet?.ip?.() || '127.0.0.1';
+    case 'city':
+      return (faker as any)?.location?.city?.() || 'Metropolis';
+    case 'country':
+      return (faker as any)?.location?.country?.() || 'Wonderland';
+    case 'company':
+      return (faker as any)?.company?.name?.() || 'ACME Inc.';
+    default:
+      // Unknown descriptor → return as-is to avoid surprises
+      return descriptor;
+  }
+}
+
+function generateFromSchema(schema: any): any {
+  if (schema == null) return schema;
+  if (Array.isArray(schema)) {
+    // If array has a single descriptor like ['string'], generate a small array of values
+    if (schema.length === 1 && typeof schema[0] === 'string') {
+      return [generateValueByDescriptor(schema[0] as string), generateValueByDescriptor(schema[0] as string)];
+    }
+    // Otherwise, map values
+    return schema.map((v) => (typeof v === 'string' ? generateValueByDescriptor(v) : generateFromSchema(v)));
+  }
+  if (typeof schema === 'object') {
+    const out: any = {};
+    for (const [k, v] of Object.entries(schema)) {
+      if (typeof v === 'string') {
+        out[k] = generateValueByDescriptor(v);
+      } else if (typeof v === 'number' || typeof v === 'boolean') {
+        out[k] = v;
+      } else if (Array.isArray(v)) {
+        out[k] = generateFromSchema(v);
+      } else if (typeof v === 'object' && v !== null) {
+        out[k] = generateFromSchema(v);
+      } else {
+        out[k] = v;
+      }
+    }
+    return out;
+  }
+  if (typeof schema === 'string') return generateValueByDescriptor(schema);
+  return schema;
+}
+
+export async function generateSampleData(schema?: Record<string, any>) {
+  const sample = {
+    firstName: faker?.person?.firstName?.() || 'John',
+    lastName: faker?.person?.lastName?.() || 'Doe',
+    email: faker?.internet?.email?.() || 'john.doe@example.com',
+    phone: faker?.phone?.number?.() || '1234567890'
+  } as any;
+  if (!schema) return sample;
+  const interpreted = generateFromSchema(schema);
+  return { ...sample, ...interpreted };
+}