@capillarytech/cap-ui-utils 3.0.20 → 3.1.0

package/e2e/utils/screenshotRecorderUtil.ts

@@ -0,0 +1,174 @@
+import fs from 'fs';
+import path from 'path';
+import debugMode from './debugModeUtil';
+
+/**
+ * Captures a full-page screenshot after every click and saves them under
+ * reports/debug/screenshots/<module>/<test>/<NNN>_<command>.png.
+ *
+ * Off by default; enabled only when FULL_DEBUG_MODE=true. When off, every
+ * method is a no-op so there is zero overhead.
+ *
+ * Driven by the WDIO afterCommand hook. Only click commands trigger a capture,
+ * so other commands (typing, lookups, navigation) don't spam the report.
+ *
+ * Also writes a steps.json per test mapping each click (step index) to its
+ * screenshot file and the wall-clock time it fired. The compare tool uses the
+ * click times to attribute recorded request payloads to the click that
+ * triggered them (request.timestamp falls between consecutive click times).
+ */
+
+interface RecordedStep {
+    step: number;
+    file: string;
+    command: string;
+    clickTime: string;
+}
+
+// WDIO command names that represent a click worth screenshotting.
+const INTERACTION_COMMANDS = new Set([
+    'click',
+    'doubleClick',
+]);
+
+// afterCommand fires before the post-click content has rendered; wait this long
+// so the screenshot reflects the settled page. Tunable via env.
+const SETTLE_MS = Number(process.env.FULL_DEBUG_SCREENSHOT_DELAY_MS) || 500;
+
+// Hard cap on a single CDP screenshot. The capture can hang indefinitely when it
+// fires while the page is mid-navigation (e.g. during login), which would block
+// the awaiting afterCommand hook and stall the whole run until the Mocha hook
+// timeout. Bounding it guarantees screenshots can never block automations.
+const CAPTURE_TIMEOUT_MS = Number(process.env.FULL_DEBUG_SCREENSHOT_TIMEOUT_MS) || 8000;
+
+class ScreenshotRecorder {
+    private enabled = debugMode.isCaptureEnabled();
+    private outputDir = path.join(process.cwd(), 'reports', 'debug', 'screenshots');
+    private currentTestTitle = '';
+    private counter = 0;
+    // Last saved image; used to drop byte-identical duplicate captures.
+    private lastImage: Buffer | null = null;
+    // Guard against re-entrancy: our own cdp/screenshot calls also fire afterCommand.
+    private capturing = false;
+    // Per-test record of clicks → screenshot file + time, for request correlation.
+    private steps: RecordedStep[] = [];
+
+    isEnabled(): boolean {
+        return this.enabled;
+    }
+
+    /** Reset the per-test counter and remember the current test. */
+    startTest(testTitle: string): void {
+        if (!this.enabled) return;
+        this.currentTestTitle = testTitle || 'unknown_test';
+        this.counter = 0;
+        this.lastImage = null;
+        this.steps = [];
+    }
+
+    /** Capture a full-page screenshot if commandName is a click. */
+    async captureAfter(commandName: string): Promise<void> {
+        if (!this.enabled || this.capturing) return;
+        if (!INTERACTION_COMMANDS.has(commandName)) return;
+        // No active test means we're in the login/setup phase (the root before-all
+        // hook). Capturing here is pointless and, worse, the CDP screenshot can hang
+        // mid-navigation and block that hook until its Mocha timeout. Skip it.
+        if (!this.currentTestTitle) return;
+
+        this.capturing = true;
+        // Stamp the click time before the settle pause so it lines up with when
+        // the click actually fired (and thus with the requests it triggered).
+        const clickTime = new Date().toISOString();
+        try {
+            // Let the post-click content render before capturing.
+            await browser.pause(SETTLE_MS);
+
+            // captureBeyondViewport => full scrollable page, not just the viewport.
+            // Bound the CDP call: it can hang indefinitely if it fires while the page
+            // is mid-navigation, which would block the awaiting afterCommand hook.
+            const capturePromise: Promise<any> = browser.cdp('Page', 'captureScreenshot', {
+                format: 'png',
+                captureBeyondViewport: true,
+            });
+            // If the timeout wins, the CDP promise may still settle (or reject) later;
+            // swallow it so a late rejection never surfaces as an unhandled rejection.
+            capturePromise.catch(() => {});
+
+            let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+            const res: any = await Promise.race([
+                capturePromise,
+                new Promise((resolve) => {
+                    timeoutHandle = setTimeout(() => resolve(null), CAPTURE_TIMEOUT_MS);
+                }),
+            ]);
+            // Clear the fallback timer once the race settles so a pending timeout
+            // can't keep the Node event loop alive (delaying process exit by up to
+            // CAPTURE_TIMEOUT_MS) when the CDP call won.
+            if (timeoutHandle) clearTimeout(timeoutHandle);
+            if (!res?.data) return;
+
+            const image = Buffer.from(res.data, 'base64');
+            // afterCommand fires twice per click; once settled both frames are
+            // identical, so skip the byte-identical repeat.
+            if (this.lastImage && this.lastImage.equals(image)) return;
+            this.lastImage = image;
+
+            const moduleName = process.env.module || 'unknown_module';
+            const safeTitle = (this.currentTestTitle || '_pre-test')
+                .replace(/[^a-zA-Z0-9_-]+/g, '_')
+                .slice(0, 120);
+            const dir = path.join(this.outputDir, moduleName, safeTitle);
+            fs.mkdirSync(dir, { recursive: true });
+
+            this.counter += 1;
+            const seq = String(this.counter).padStart(3, '0');
+            const fileName = `${seq}_${commandName}.png`;
+            fs.writeFileSync(path.join(dir, fileName), image);
+
+            this.steps.push({
+                step: this.counter,
+                file: fileName,
+                command: commandName,
+                clickTime,
+            });
+        } catch (err) {
+            console.log(`[screenshotRecorder] failed to capture after ${commandName}: ${err}`);
+        } finally {
+            this.capturing = false;
+        }
+    }
+
+    /**
+     * Write the per-test steps.json alongside this test's screenshots, mapping
+     * each click step to its screenshot file and the time it fired. Used by the
+     * compare tool to attribute request payloads to the click that triggered
+     * them. No-op when nothing was captured.
+     */
+    flushTest(): void {
+        if (!this.enabled) return;
+        try {
+            if (this.steps.length === 0) return;
+
+            const moduleName = process.env.module || 'unknown_module';
+            const safeTitle = (this.currentTestTitle || '_pre-test')
+                .replace(/[^a-zA-Z0-9_-]+/g, '_')
+                .slice(0, 120);
+            const dir = path.join(this.outputDir, moduleName, safeTitle);
+            fs.mkdirSync(dir, { recursive: true });
+
+            const payload = {
+                test: this.currentTestTitle,
+                module: moduleName,
+                stepCount: this.steps.length,
+                steps: this.steps,
+            };
+            fs.writeFileSync(path.join(dir, 'steps.json'), JSON.stringify(payload, null, 2));
+        } catch (err) {
+            console.log(`[screenshotRecorder] failed to write steps.json: ${err}`);
+        } finally {
+            this.steps = [];
+        }
+    }
+}
+
+export default new ScreenshotRecorder();

package/e2e/utils/setupMock.ts

@@ -0,0 +1,29 @@
+import { beamerApiResp } from "./mockResponse";
+
+class setupMock {
+  async mockBeamerAPIForPopup() {
+    const beamerReq1 = await browser.mock(
+      "https://backend.getbeamer.com/initialize" + "**",
+      {
+        method: "get",
+      }
+    );
+
+    beamerReq1.respond(beamerApiResp);
+
+    const beamerReq2 = await browser.mock(
+      "https://backend.getbeamer.com/numberFeatures" + "**",
+      {
+        method: "get",
+      }
+    );
+
+    beamerReq2.respond(
+      [{}],
+      {
+        statusCode: 404,
+      }
+    );
+  }
+}
+export default new setupMock();

package/e2e/utils/unmatchedBracesUtil.ts

@@ -0,0 +1,101 @@
+import elementUtil from "./elementUtil";
+
+/** Invalid snippet used to trigger unmatched-braces validation across Engage and Adiona flows. */
+export const UNMATCHED_BRACES_SNIPPET = "{{ my_standard_tag";
+
+/** Unsupported/unrecognised tag used to trigger the send-for-approval server-side validation error. */
+export const UNSUPPORTED_TAG = "{{my_invalid_standard_tag}}";
+
+/** Full footer / inline error copy for standard-tag validation (SMS, MPush, Web Push, etc.). */
+export const INVALID_LABEL_ERROR_TEXT = "Invalid label, please close all curly braces";
+
+/**
+ * Footer error container for "Invalid label…" type errors (SMS, Journey SMS).
+ * XPath: //div[contains(@class,'error-container')]//div[text()='<message>']
+ */
+export function invalidLabelErrorFooterContainer(errorMessage: string) {
+  return $(
+    `//div[contains(@class,'error-container')]//div[text()='${errorMessage}']`
+  );
+}
+
+/**
+ * Inline error span for "Invalid label…" (Viber, Zalo, Journey Zalo).
+ * XPath: //span[contains(@class,'error-message') and contains(.,'Invalid label')]
+ */
+export function invalidLabelErrorSpan() {
+  return $("//span[contains(@class,'error-message') and contains(.,'Invalid label')]");
+}
+
+/**
+ * Validation error span below a component-with-label input (MPush Title / Message).
+ * XPath: //div[contains(@class,'component-with-label-label') and normalize-space()='<label>']
+ *        /ancestor::div[contains(@class,'component-with-label')]//span[contains(@class,'error-message')]
+ * Use for channels where the error appears inline under the input rather than in the footer.
+ */
+export function componentWithLabelErrorSpan(label: string) {
+  return $(
+    `//div[contains(@class,'component-with-label-label') and normalize-space()='${label}']/ancestor::div[contains(@class,'component-with-label')]//span[contains(@class,'error-message')]`
+  );
+}
+
+/**
+ * CodeMirror email editor: click the last cm-line at a stable left-edge offset to acquire focus,
+ * wait for the editor to be focused, then press End + Enter to position the cursor on a new last line.
+ * Call this before typing a snippet into the editor.
+ *
+ * @param codeMirrorEditor   The CodeMirror content-editable div (aria-placeholder contains "Write your HTML email code here").
+ * @param codeMirrorLastLine The last `.cm-line` div inside that editor.
+ */
+export async function focusEmailEditorAddNewLineAtEnd(
+  codeMirrorEditor: WebdriverIO.Element,
+  codeMirrorLastLine: WebdriverIO.Element
+): Promise<void> {
+  await codeMirrorEditor.waitForDisplayed({ timeout: 90000 });
+  await codeMirrorLastLine.waitForDisplayed({ timeout: 10000 });
+  const size = await codeMirrorLastLine.getSize();
+  const xOffset = Math.round(2 - size.width / 2);
+  await codeMirrorLastLine.click({ x: xOffset, y: 0 });
+  await browser.waitUntil(
+    async () => {
+      const focused = await browser.execute(() => {
+        const codeMirrorEditorEl = document.querySelector(
+          'div[aria-placeholder*="Write your HTML email code here"]'
+        );
+        if (!codeMirrorEditorEl) return false;
+        const active = document.activeElement;
+        const editorFocused = active === codeMirrorEditorEl || (active && codeMirrorEditorEl.contains(active));
+        const cmEditor = codeMirrorEditorEl.closest(".cm-editor");
+        const hasCmFocused =
+          (cmEditor && cmEditor.classList.contains("cm-focused")) ||
+          (active && active.classList.contains("cm-focused"));
+        return !!(editorFocused || hasCmFocused);
+      });
+      return focused === true;
+    },
+    {
+      timeout: 10000,
+      timeoutMsg: "CodeMirror editor did not receive focus after clicking last line",
+      interval: 100,
+    }
+  );
+  await browser.keys(["End"]);
+  await browser.keys(["Enter"]);
+}
+
+/**
+ * Inject unmatched-braces snippet, try submit (if clickable), assert via callback, then restore field.
+ * Not used for Email (CodeMirror debounce / waitUntil sequencing is bespoke).
+ */
+export async function injectAndRestore(
+  targetInput: WebdriverIO.Element,
+  submitButton: WebdriverIO.Element,
+  originalValue: string,
+  assertFn: () => Promise<void>
+): Promise<void> {
+  await elementUtil.enterText(targetInput, UNMATCHED_BRACES_SNIPPET);
+  await elementUtil.clickIfClickable(submitButton);
+  await assertFn();
+  await elementUtil.clearByBackspace(UNMATCHED_BRACES_SNIPPET, targetInput);
+  await elementUtil.typeText(targetInput, originalValue);
+}

package/e2e/utils/uploaders/fileServiceUploader.ts

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import axios from 'axios';
+import { Uploader } from './uploader';
+
+/**
+ * Uploads a file to Capillary's internal File Service, mirroring the
+ * `uploadData` flow in arya's arya-fileservice-sdk: a raw-binary POST to
+ *   POST {baseUrl}v2/{namespace}/?fileName={name}&fileNameEncoding=false
+ * with the file bytes as the body. The service stores the object (in S3 under
+ * the hood) and returns JSON containing file_path / secure_file_path.
+ *
+ * Config via env vars:
+ *   FILE_SERVICE_URL        - base URL. Defaults to the in-cluster DNS
+ *                             http://file-service.default/ which is ONLY
+ *                             reachable from inside the Capillary cluster.
+ *                             Set this to a reachable host when running
+ *                             outside the cluster.
+ *   FILE_SERVICE_NAMESPACE  - target namespace (must be configured on the
+ *                             file-service side to allow the archive's
+ *                             extension/mime-type and size). Defaults to
+ *                             'import', which is provisioned on the crm
+ *                             clusters and permits .zip (it stores under a
+ *                             generated UUID key, so use the returned path).
+ *   FILE_SERVICE_ORG_ID     - optional org id (X-CAP-API-AUTH-ORG-ID header)
+ *   FILE_SERVICE_PUBLIC     - "false" to upload as PRIVATE (default PUBLIC)
+ *
+ * Note: the arya SDK sends no auth header — the service relies on in-cluster
+ * network isolation. There is no external/authenticated route here.
+ */
+export class FileServiceUploader implements Uploader {
+    readonly name = 'Capillary File Service';
+    private baseUrl = process.env.FILE_SERVICE_URL || 'http://file-service.default/';
+    // Defaults to the 'import' namespace: it is provisioned on the crm clusters
+    // (unlike 'default', which does NOT exist server-side and 500s with
+    // NoSuchNamespaceException) and permits .zip uploads. Note it stores under a
+    // server-generated UUID key, so retrieve via the returned file_path, not the
+    // original filename. Override per env with FILE_SERVICE_NAMESPACE.
+    private namespace = process.env.FILE_SERVICE_NAMESPACE || 'import';
+    private orgId = process.env.FILE_SERVICE_ORG_ID || '';
+    private isPublic = process.env.FILE_SERVICE_PUBLIC !== 'false';
+    // Hard network timeout so an unresponsive file-service can never hang the
+    // run's onComplete hook (which would keep the pod alive forever).
+    private timeoutMs = Number(process.env.FILE_SERVICE_TIMEOUT_MS) || 60000;
+
+    isConfigured(): boolean {
+        return Boolean(this.baseUrl && this.namespace);
+    }
+
+    missingConfigMessage(): string {
+        const missing: string[] = [];
+        if (!this.baseUrl) missing.push('FILE_SERVICE_URL');
+        if (!this.namespace) missing.push('FILE_SERVICE_NAMESPACE');
+        return missing.join(', ');
+    }
+
+    async upload(localFilePath: string, remoteName: string): Promise<string> {
+        const base = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
+        const url = `${base}v2/${this.namespace}/?fileName=${encodeURI(remoteName)}&fileNameEncoding=false`;
+
+        const headers: Record<string, string> = { 'Content-Type': 'application/zip' };
+        if (this.isPublic) headers['X-CAP-FS-ACL'] = 'PUBLIC';
+        if (this.orgId) headers['X-CAP-API-AUTH-ORG-ID'] = String(this.orgId);
+
+        const body = fs.readFileSync(localFilePath);
+        const res = await axios.post(url, body, {
+            headers,
+            maxBodyLength: Infinity,
+            maxContentLength: Infinity,
+            timeout: this.timeoutMs,
+        });
+
+        // The file-service returns HTTP 200 even when the upload fails (e.g.
+        // NoSuchNamespaceException), carrying the error in the JSON body. So a
+        // 200 is NOT proof of success — only a real file path is. Treat a body
+        // without one as a failure so the run doesn't silently report success.
+        const data = typeof res.data === 'string' ? JSON.parse(res.data) : res.data;
+        const location = data?.secure_file_path || data?.file_path || data?.file?.s3_token;
+        if (!location) {
+            const body = typeof res.data === 'string' ? res.data : JSON.stringify(res.data);
+            throw new Error(`file-service returned no file path (namespace='${this.namespace}'): ${body}`);
+        }
+        return location;
+    }
+}

package/e2e/utils/uploaders/uploader.ts

@@ -0,0 +1,20 @@
+/**
+ * Destination-agnostic uploader contract. Implement this for each backend
+ * (Google Drive now, S3 later) so the orchestrator never changes.
+ */
+export interface Uploader {
+    /** Human-readable backend name, used in logs. */
+    readonly name: string;
+
+    /** True when all required credentials/config are present. */
+    isConfigured(): boolean;
+
+    /** Describes which config is missing (for a helpful log when not configured). */
+    missingConfigMessage(): string;
+
+    /**
+     * Upload a local file and return a human-readable location
+     * (URL or id) for logging.
+     */
+    upload(localFilePath: string, remoteName: string): Promise<string>;
+}

package/e2e/utils/virtualListUtil.ts

@@ -0,0 +1,115 @@
+/**
+ * Helpers for antd v6 virtualized lists (`rc-virtual-list`).
+ *
+ * The list renders only a window of DOM rows at a time. A row that exists in the data
+ * model but is outside that window has no DOM node, so `waitForDisplayed` / `click`
+ * through WDIO never sees it. These helpers drive the scroll container in the browser
+ * until the row is rendered, then click the target directly.
+ *
+ * Works for both `ant-select-tree` (TreeSelect) and `ant-select-item-option` (Select).
+ */
+
+interface ScrollToOptions {
+  /** CSS selector of a container that scopes the search (popover root). If omitted, document. */
+  containerSelector?: string;
+  /** Click the checkbox inside the row instead of the row itself. */
+  clickCheckbox?: boolean;
+  /** Overall timeout in ms. */
+  timeout?: number;
+  /** Per-iteration pause in ms. */
+  interval?: number;
+}
+
+/**
+ * Scroll a virtualized antd list inside `containerSelector` until a row whose trimmed
+ * textContent equals `label` is rendered, then click it (or its checkbox).
+ *
+ * Returns true on success, throws on timeout.
+ */
+export async function scrollAndClickVirtualOption(
+  label: string,
+  opts: ScrollToOptions = {},
+): Promise<void> {
+  const {
+    containerSelector,
+    clickCheckbox = true,
+    timeout = 15000,
+    interval = 300,
+  } = opts;
+
+  await browser.waitUntil(
+    async () => {
+      return await browser.execute(
+        (containerSel: string, targetLabel: string, useCheckbox: boolean) => {
+          const root: ParentNode = containerSel
+            ? document.querySelector(containerSel) || document
+            : document;
+
+          const ROW_SELECTOR =
+            '[role="treeitem"], .ant-select-tree-treenode, .ant-select-item-option';
+
+          const findRow = (): HTMLElement | null => {
+            const rows = Array.from((root as ParentNode).querySelectorAll(ROW_SELECTOR));
+            for (const r of rows) {
+              if ((r.textContent || '').trim() === targetLabel) return r as HTMLElement;
+            }
+            return null;
+          };
+
+          // If already rendered, click and return.
+          let row = findRow();
+          if (row) {
+            const checkbox = useCheckbox
+              ? (row.querySelector(
+                  '.ant-select-tree-checkbox, .ant-tree-checkbox, .ant-select-item-option-state',
+                ) as HTMLElement | null)
+              : null;
+            (checkbox || row).click();
+            return true;
+          }
+
+          // Find the scroll container.
+          const holder = (root as ParentNode).querySelector(
+            '.rc-virtual-list-holder, .ant-select-tree-list-holder, .ant-tree-list-holder',
+          ) as HTMLElement | null;
+          if (!holder) return false;
+
+          // rc-virtual-list uses the holder's scrollTop to drive the translateY of inner.
+          // Advance by one viewport (clientHeight) each tick until we either find the row
+          // or hit the end.
+          const prev = holder.scrollTop;
+          holder.scrollTop = Math.min(
+            holder.scrollHeight,
+            prev + Math.max(holder.clientHeight, 120),
+          );
+          // Dispatch scroll so the virtual list re-renders.
+          holder.dispatchEvent(new Event('scroll', { bubbles: true }));
+
+          row = findRow();
+          if (row) {
+            const checkbox = useCheckbox
+              ? (row.querySelector(
+                  '.ant-select-tree-checkbox, .ant-tree-checkbox, .ant-select-item-option-state',
+                ) as HTMLElement | null)
+              : null;
+            (checkbox || row).click();
+            return true;
+          }
+
+          // Reached the bottom without finding it? Caller will timeout if so.
+          return holder.scrollTop >= holder.scrollHeight - holder.clientHeight ? false : false;
+        },
+        containerSelector ?? '',
+        label,
+        clickCheckbox,
+      );
+    },
+    {
+      timeout,
+      interval,
+      timeoutMsg: `Virtualized option "${label}" not found within ${timeout}ms (container=${containerSelector ?? 'document'})`,
+    },
+  );
+}
+
+export default { scrollAndClickVirtualOption };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capillarytech/cap-ui-utils",
-  "version": "3.0.20",
+  "version": "3.1.0",
   "description": "Utility functions shared accross all the modules",
   "main": "index.js",
   "scripts": {
@@ -18,5 +18,19 @@
     "react-ga": "^3.3.1",
     "react-intl": "6.6.6",
     "tti-polyfill": "^0.2.2"
+  },
+  "peerDependencies": {
+    "webdriverio": ">=7",
+    "@rpii/wdio-commands": ">=7",
+    "axios": ">=1",
+    "supertest": ">=6",
+    "nanoid": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "webdriverio": { "optional": true },
+    "@rpii/wdio-commands": { "optional": true },
+    "axios": { "optional": true },
+    "supertest": { "optional": true },
+    "nanoid": { "optional": true }
   }
 }