@capillarytech/cap-ui-utils 3.1.3 → 3.2.0-beta.1

package/e2e/README.md

@@ -36,6 +36,32 @@ Only helpers that are **self-contained and free of per-repo test data**:
 | Misc infra | `utils/debugModeUtil`, `utils/featureFlagUtil`, `utils/automationBypassUtil`, `utils/deletionRegistry`, `utils/htmlEditorUtil`, `utils/virtualListUtil`, `utils/unmatchedBracesUtil`, `utils/uploaders/*` |
 | Services | `services/lockService`, `services/locks/*` |
 | Config | `constants/common` (waits, log markers, `maxLoginAttempts`) |
+| Playwright (phase 2) | `playwright/reporter`, `playwright/config`, `playwright/login`, `playwright/waits` |
+
+## Playwright toolkit (phase 2 — coexistence)
+
+WDIO and Playwright coexist: the runner picks the engine per module from
+`module-map.json`. A migrated module's product repo carries **only** Playwright code
+and builds its config from here, so the results contract stays intact.
+
+```ts
+// playwright.config.ts (product repo)
+import { createPlaywrightConfig } from '@capillarytech/cap-ui-utils/e2e/playwright/config';
+export default createPlaywrightConfig({ testDir: './tests', title: 'Garuda E2E' });
+
+// a spec
+import { doLogin } from '@capillarytech/cap-ui-utils/e2e/playwright/login';
+import { waitForApi } from '@capillarytech/cap-ui-utils/e2e/playwright/waits';
+```
+
+- **`playwright/reporter`** — emits `reports/html-reports/master-report.html` (same
+  path/shape the WDIO reporter produced) so `supervisor.py`'s `generateReport()` →
+  Apitester pipeline is unchanged. Referenced by path via `require.resolve`.
+- **`playwright/config`** — `createPlaywrightConfig()` wires the reporter, selects the
+  suite via `SUITE` → `@<suite>` grep (mirrors `wdio --suite`), and sets pod-friendly
+  defaults (headless chromium, trace/screenshot on failure, retries).
+- **`playwright/login`** — Playwright port of `pages/common/login.page` (intouch V2/V1).
+- **`playwright/waits`** — network-driven wait helpers (no fixed sleeps).
 
 Two small decouplings were applied on the way in:
 - `logCollectorUtil` had a **dead** `import { config } from '../../test/wdio.conf'` (never used) — removed.

package/e2e/playwright/config.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Shared Playwright config factory — phase-2 coexistence.
+ *
+ * Product repos build their playwright.config from this so every migrated module
+ * inherits the same reporter (results contract), suite selection, and pod-friendly
+ * defaults. Returns a plain config object (no hard require of @playwright/test), so
+ * it resolves even where defineConfig isn't importable.
+ *
+ *   // playwright.config.ts (in a product repo)
+ *   import { createPlaywrightConfig } from '@capillarytech/cap-ui-utils/e2e/playwright/config';
+ *   export default createPlaywrightConfig({ testDir: './tests', title: 'Garuda E2E' });
+ *
+ * Suite selection: the runner exports SUITE (smoke|sanity|regression). Tests are
+ * tagged (e.g. test('@smoke ...')) and this config greps `@<suite>` so
+ * `npm run test:e2e` runs only that suite — same contract as `wdio --suite`.
+ */
+const path = require("path");
+
+function num(v, dflt) {
+    const n = parseInt(v, 10);
+    return Number.isFinite(n) ? n : dflt;
+}
+
+function createPlaywrightConfig(overrides = {}) {
+    const suite = process.env.SUITE || process.env.suite || "";
+    const reporterPath = require.resolve("./reporter");
+
+    const base = {
+        testDir: overrides.testDir || "./tests",
+        // A migrated module is Playwright-only; keep the tree explicit.
+        fullyParallel: overrides.fullyParallel !== undefined ? overrides.fullyParallel : true,
+        forbidOnly: !!process.env.CI,
+        retries: num(process.env.PW_RETRIES, overrides.retries !== undefined ? overrides.retries : 1),
+        workers: num(process.env.PW_WORKERS, overrides.workers !== undefined ? overrides.workers : 1),
+        timeout: num(process.env.PW_TIMEOUT, overrides.timeout || 90000),
+        expect: { timeout: num(process.env.PW_EXPECT_TIMEOUT, 15000) },
+        // Only the migrated suite runs — same behaviour as `wdio --suite <suite>`.
+        grep: suite ? new RegExp("@" + suite + "\\b") : undefined,
+        reporter: [
+            [reporterPath, { title: overrides.title || "E2E Report (Playwright)" }],
+            ["line"],
+        ],
+        use: Object.assign(
+            {
+                baseURL: overrides.baseURL || process.env.INTOUCH_URL || undefined,
+                headless: true,
+                trace: "retain-on-failure",
+                screenshot: "only-on-failure",
+                video: "off",
+                actionTimeout: num(process.env.PW_ACTION_TIMEOUT, 15000),
+                navigationTimeout: num(process.env.PW_NAV_TIMEOUT, 60000),
+                ignoreHTTPSErrors: true,
+                viewport: { width: 1920, height: 1080 },
+            },
+            overrides.use || {}
+        ),
+        projects: overrides.projects || [{ name: "chromium", use: { browserName: "chromium" } }],
+    };
+    return Object.assign(base, overrides.extra || {});
+}
+
+module.exports = { createPlaywrightConfig };
+module.exports.default = createPlaywrightConfig;

package/e2e/playwright/debugRecorder.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Playwright FULL_DEBUG_MODE recorders — phase-2 parity with the WDIO debug bundle.
+ *
+ * Reproduces, engine-natively, the two artifact sets the WDIO
+ * screenshotRecorderUtil + requestRecorderService produce, at the SAME paths so
+ * the zip-compare tooling is unchanged:
+ *
+ *   reports/debug/screenshots/<module>/<test>/NNN_click.png  (+ steps.json)
+ *   reports/debug/request-payloads/<module>/<test>.json
+ *
+ * Gated by the shared debugMode util (FULL_DEBUG_MODE=true [+ optional
+ * DEBUG_MODULES]); a no-op otherwise, so zero overhead when off.
+ *
+ *   import { installDebugRecorders } from '@capillarytech/cap-ui-utils/e2e/playwright/debugRecorder';
+ *   const rec = await installDebugRecorders(page, { module, testTitle, baseURL });
+ *   ... run test ...
+ *   await rec.flush();   // in fixture teardown
+ *
+ * Notes on WDIO parity:
+ * - screenshots: WDIO captured after every `click` command; we hook real DOM
+ *   clicks (capture phase) so programmatic PW clicks count too, then settle +
+ *   full-page screenshot, dropping byte-identical duplicates (same as WDIO).
+ * - request payloads: WDIO recorded POST/PATCH/PUT/DELETE to the app host via CDP;
+ *   we use page.on('request') (no CDP needed). Initiator JS stack isn't available
+ *   via the PW request API, so `initiator` is null (only field that differs).
+ */
+const fs = require("fs");
+const path = require("path");
+const debugMode = require("../utils/debugModeUtil").default;
+
+const RECORDED_METHODS = ["POST", "PATCH", "PUT", "DELETE"];
+const SETTLE_MS = Number(process.env.FULL_DEBUG_SCREENSHOT_DELAY_MS) || 500;
+const CAPTURE_TIMEOUT_MS = Number(process.env.FULL_DEBUG_SCREENSHOT_TIMEOUT_MS) || 8000;
+
+function safeName(s) {
+  // Drop the leading suite tag (e.g. "@smoke ") so the folder matches the WDIO
+  // it()-title naming (smoke_garudaUI_analytics_KPI_visibility).
+  return String(s || "unknown_test").replace(/^@\w+\s+/, "").replace(/[^\w.-]+/g, "_");
+}
+function hostOf(u) {
+  try { return new URL(u).host; } catch (_) { return ""; }
+}
+
+class PwDebugRecorder {
+  constructor(page, opts = {}) {
+    this.page = page;
+    this.enabled = debugMode.isCaptureEnabled();
+    this.module = opts.module || process.env.module || "unknown";
+    this.testTitle = safeName(opts.testTitle);
+    this.baseHost = hostOf(opts.baseURL || process.env.INTOUCH_URL || "");
+    this.requests = [];
+    this.steps = [];
+    this.counter = 0;
+    this.lastImage = null;
+    this.chain = Promise.resolve();
+    const root = path.join(process.cwd(), "reports", "debug");
+    this.ssDir = path.join(root, "screenshots", this.module, this.testTitle);
+    this.rpDir = path.join(root, "request-payloads", this.module);
+  }
+
+  async install() {
+    if (!this.enabled) return this;
+
+    // --- request payloads (POST/PATCH/PUT/DELETE to the app host) ---
+    this.page.on("request", (req) => {
+      try {
+        const method = req.method();
+        if (!RECORDED_METHODS.includes(method)) return;
+        const url = req.url();
+        if (this.baseHost && !url.includes(this.baseHost)) return;
+        this.requests.push({
+          method,
+          url,
+          timestamp: new Date().toISOString(),
+          postData: req.postData() || null,
+          headers: req.headers(),
+          resourceType: req.resourceType(),
+          initiator: null, // JS initiator stack not exposed by the PW request API
+        });
+      } catch (_) { /* never let recording break the run */ }
+    });
+
+    // --- screenshot after every click ---
+    await this.page.exposeFunction("__capOnClick", (info) => {
+      // Serialize captures so rapid clicks don't overlap screenshots.
+      this.chain = this.chain.then(() => this._capture(info)).catch(() => {});
+    });
+    const inject = () => {
+      // eslint-disable-next-line no-undef
+      if (window.__capClickHooked) return;
+      // eslint-disable-next-line no-undef
+      window.__capClickHooked = true;
+      // eslint-disable-next-line no-undef
+      document.addEventListener(
+        "click",
+        (e) => {
+          try {
+            const t = e.target;
+            // eslint-disable-next-line no-undef
+            window.__capOnClick &&
+              window.__capOnClick({
+                tag: t && t.tagName,
+                text: ((t && t.innerText) || "").trim().slice(0, 40),
+              });
+          } catch (_) { /* ignore */ }
+        },
+        true // capture phase — fires even if a handler stops propagation
+      );
+    };
+    await this.page.addInitScript(inject);          // future navigations / SPA reloads
+    await this.page.evaluate(inject).catch(() => {}); // the already-loaded document
+    return this;
+  }
+
+  async _capture(info) {
+    const clickTime = new Date().toISOString();
+    await this.page.waitForTimeout(SETTLE_MS).catch(() => {}); // let the click settle (WDIO parity)
+    let buf;
+    try {
+      buf = await this.page.screenshot({ fullPage: true, timeout: CAPTURE_TIMEOUT_MS });
+    } catch (_) {
+      return; // a mid-navigation screenshot can fail; never block the run
+    }
+    if (this.lastImage && buf.equals(this.lastImage)) return; // drop byte-identical duplicate
+    this.lastImage = buf;
+    this.counter += 1;
+    const file = String(this.counter).padStart(3, "0") + "_click.png";
+    try {
+      fs.mkdirSync(this.ssDir, { recursive: true });
+      fs.writeFileSync(path.join(this.ssDir, file), buf);
+      this.steps.push({ step: this.counter, file, command: "click", clickTime, target: (info && info.tag) || null });
+    } catch (_) { /* ignore */ }
+  }
+
+  /** Drain pending screenshots, then write steps.json + the request-payloads file. */
+  async flush() {
+    if (!this.enabled) return;
+    await this.chain.catch(() => {});
+    try {
+      if (this.steps.length) {
+        fs.mkdirSync(this.ssDir, { recursive: true });
+        fs.writeFileSync(path.join(this.ssDir, "steps.json"), JSON.stringify(this.steps, null, 2));
+      }
+    } catch (_) { /* ignore */ }
+    try {
+      fs.mkdirSync(this.rpDir, { recursive: true });
+      const payload = {
+        test: this.testTitle,
+        module: this.module,
+        recordedAt: new Date().toISOString(),
+        requestCount: this.requests.length,
+        requests: this.requests,
+      };
+      fs.writeFileSync(path.join(this.rpDir, this.testTitle + ".json"), JSON.stringify(payload, null, 2));
+    } catch (_) { /* ignore */ }
+  }
+}
+
+async function installDebugRecorders(page, opts = {}) {
+  const rec = new PwDebugRecorder(page, opts);
+  await rec.install();
+  return rec;
+}
+
+module.exports = { installDebugRecorders, PwDebugRecorder };
+module.exports.default = { installDebugRecorders };

package/e2e/playwright/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Playwright subpath barrel — phase-2 coexistence toolkit.
+ *   import { createPlaywrightConfig, doLogin, waitForApi } from '@capillarytech/cap-ui-utils/e2e/playwright';
+ * The reporter is referenced by PATH in a config (not imported), e.g.
+ *   require.resolve('@capillarytech/cap-ui-utils/e2e/playwright/reporter')
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("./config");
+const login_1 = require("./login");
+const waits_1 = require("./waits");
+
+exports.createPlaywrightConfig = config_1.createPlaywrightConfig;
+exports.doLogin = login_1.doLogin;
+exports.waitForApi = waits_1.waitForApi;
+exports.clickAndWaitForApi = waits_1.clickAndWaitForApi;
+exports.waitForApiIdle = waits_1.waitForApiIdle;
+exports.reporterPath = require.resolve("./reporter");

package/e2e/playwright/login.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Shared Playwright login — phase-2 coexistence.
+ *
+ * Playwright port of e2e/pages/common/login.page (WDIO). Same intouch flow:
+ *   username -> (V2: Continue -> password) -> Sign in -> wait for /home/ui ->
+ *   sidebar shell mounted. Uses role/label + id locators and web-first waits
+ *   instead of WDIO waitForDisplayed. V2 flow is selected by env V2_LOGIN=true.
+ *
+ *   import { doLogin } from '@capillarytech/cap-ui-utils/e2e/playwright/login';
+ *   await doLogin(page, { url, username, password });
+ */
+const MAX_LOGIN_ATTEMPTS = 3;
+
+function sel(page) {
+    const v2 = process.env.V2_LOGIN === "true";
+    return {
+        v2,
+        username: v2 ? page.locator("#login-username") : page.locator("#login_user"),
+        password: v2 ? page.locator("#login-password") : page.locator("#login_cred"),
+        signIn: v2 ? page.getByRole("button", { name: "Sign in" }) : page.locator("#c-login-btn"),
+        continueBtn: page.getByRole("button", { name: "Continue" }),
+        // Post-login readiness: MFE sidebar shell testid, with the legacy
+        // "Explore features" text as a pre-MFE fallback (mirrors the WDIO page).
+        homeReady: page.locator('[data-testid="cap-navigation-spa-sidebar"], :text-is("Explore features")').first(),
+    };
+}
+
+async function doLogin(page, opts, attempt = 0) {
+    const { url, username, password } = opts;
+    const s = sel(page);
+    try {
+        await page.goto(url, { waitUntil: "domcontentloaded" });
+
+        // Already home (retry path)?
+        if (attempt > 0 && page.url().includes("/home/ui")) {
+            try {
+                await s.homeReady.waitFor({ state: "visible", timeout: 60000 });
+                console.log("-----Logged In (already home on retry)-----");
+                return;
+            } catch (e) { /* fall through to full login */ }
+        }
+
+        await s.username.waitFor({ state: "visible", timeout: 60000 });
+        await s.username.fill(username);
+
+        if (s.v2) {
+            await s.continueBtn.click();
+            await s.password.waitFor({ state: "visible", timeout: 30000 });
+        }
+        await s.password.fill(password);
+        await s.signIn.click();
+
+        await page.waitForURL(/\/home\/ui/, { timeout: 60000 });
+        console.log("-----Browser url contains /home/ui after login-----");
+        await s.homeReady.waitFor({ state: "visible", timeout: 60000 });
+        console.log("-----Logged In-----");
+    } catch (error) {
+        console.log(`Login attempt #${attempt} failed:`, error && error.message);
+        if (attempt >= MAX_LOGIN_ATTEMPTS - 1) {
+            throw new Error("Failed to get the user logged in: " + (error && error.message));
+        }
+        await doLogin(page, opts, attempt + 1);
+    }
+}
+
+module.exports = { doLogin, MAX_LOGIN_ATTEMPTS };
+module.exports.default = { doLogin };

package/e2e/playwright/reporter.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Shared Playwright reporter — phase-2 coexistence.
+ *
+ * The runner's supervisor.py reads `reports/html-reports/master-report.html`
+ * (historically produced by wdio-html-nice-reporter), inlines any linked CSS, and
+ * POSTs the result to log_collector -> Apitester. To keep that RESULTS CONTRACT
+ * intact for Playwright modules, this reporter emits the SAME file at the SAME
+ * path — self-contained (inline <style>, no external <link>) so it renders
+ * identically wherever the wdio report did.
+ *
+ * Wire it in a product repo's playwright.config via createPlaywrightConfig(), or
+ * directly:  reporter: [[require.resolve('@capillarytech/cap-ui-utils/e2e/playwright/reporter')]]
+ */
+const fs = require("fs");
+const path = require("path");
+
+function esc(s) {
+    return String(s == null ? "" : s)
+        .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+function fmtDuration(ms) {
+    if (ms == null) return "";
+    const s = ms / 1000;
+    if (s < 60) return s.toFixed(2) + "s";
+    const m = Math.floor(s / 60);
+    return m + "m " + (s - m * 60).toFixed(0) + "s";
+}
+
+class CapPlaywrightReporter {
+    constructor(options = {}) {
+        // Default path matches supervisor.py's generateReport() (cwd = /usr/wdio).
+        this.outputFile = options.outputFile ||
+            path.resolve(process.cwd(), "reports", "html-reports", "master-report.html");
+        this.title = options.title || "E2E Report (Playwright)";
+        this.results = [];
+        this.startedAt = Date.now();
+    }
+
+    onBegin(config, suite) {
+        this._total = typeof suite.allTests === "function" ? suite.allTests().length : 0;
+        this._suite = process.env.SUITE || process.env.suite || "";
+        this._module = process.env.module || process.env.E2E_MODULE || "";
+    }
+
+    onTestEnd(test, result) {
+        this.results.push({
+            title: (typeof test.titlePath === "function" ? test.titlePath() : [test.title])
+                .filter(Boolean).join(" › "),
+            status: result.status, // passed | failed | timedOut | skipped | interrupted
+            duration: result.duration,
+            retry: result.retry,
+            error: result.error && (result.error.message || String(result.error)),
+        });
+    }
+
+    onEnd(result) {
+        const counts = { passed: 0, failed: 0, skipped: 0, flaky: 0 };
+        for (const r of this.results) {
+            if (r.status === "passed") counts.passed++;
+            else if (r.status === "skipped") counts.skipped++;
+            else counts.failed++; // failed | timedOut | interrupted
+        }
+        const total = this.results.length;
+        const wallMs = Date.now() - this.startedAt;
+        const overall = (result && result.status) || (counts.failed ? "failed" : "passed");
+
+        const html = this._render(counts, total, wallMs, overall);
+        try {
+            fs.mkdirSync(path.dirname(this.outputFile), { recursive: true });
+            fs.writeFileSync(this.outputFile, html, "utf-8");
+            console.log(`[cap-pw-reporter] wrote ${this.outputFile}`);
+        } catch (e) {
+            console.log("[cap-pw-reporter] FAILED to write report:", e && e.message);
+        }
+        // Also echo a plain summary to stdout so it lands in the Apitester log.
+        console.log(`[cap-pw-reporter] SUITE=${this._suite} module=${this._module} ` +
+            `total=${total} passed=${counts.passed} failed=${counts.failed} skipped=${counts.skipped} overall=${overall}`);
+    }
+
+    _statusPill(status) {
+        const map = {
+            passed: ["#1B7A1B", "#E7F3E8", "PASS"],
+            skipped: ["#8a6d00", "#FBEFD6", "SKIP"],
+        };
+        const [fg, bg, label] = map[status] || ["#B00020", "#FBE0DD", status.toUpperCase()];
+        return `<span class="pill" style="color:${fg};background:${bg}">${esc(label)}</span>`;
+    }
+
+    _render(counts, total, wallMs, overall) {
+        const rows = this.results.map((r, i) => `
+      <tr class="${r.status}">
+        <td class="num">${i + 1}</td>
+        <td>${this._statusPill(r.status)}</td>
+        <td class="title">${esc(r.title)}${r.retry ? ` <span class="retry">(retry ${r.retry})</span>` : ""}</td>
+        <td class="dur">${fmtDuration(r.duration)}</td>
+        <td class="err">${r.error ? `<pre>${esc(r.error)}</pre>` : ""}</td>
+      </tr>`).join("");
+
+        const overallColor = overall === "passed" ? "#1B7A1B" : "#B00020";
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>${esc(this.title)}</title>
+<style>
+  body{font-family:-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;margin:0;background:#f6f8fa;color:#1f2933}
+  .wrap{max-width:1100px;margin:0 auto;padding:24px}
+  h1{font-size:20px;margin:0 0 4px}
+  .meta{color:#556;font-size:13px;margin-bottom:16px}
+  .meta b{color:#1f2933}
+  .cards{display:flex;gap:12px;flex-wrap:wrap;margin-bottom:20px}
+  .card{background:#fff;border:1px solid #e2e8f0;border-radius:8px;padding:12px 18px;min-width:90px}
+  .card .n{font-size:24px;font-weight:700;font-variant-numeric:tabular-nums}
+  .card .l{font-size:11px;text-transform:uppercase;letter-spacing:.05em;color:#667}
+  .overall{font-weight:700;color:${overallColor}}
+  table{width:100%;border-collapse:collapse;background:#fff;border:1px solid #e2e8f0;border-radius:8px;overflow:hidden}
+  th,td{padding:9px 12px;text-align:left;font-size:13px;border-bottom:1px solid #eef2f6;vertical-align:top}
+  th{background:#1F3A5F;color:#fff;font-size:11px;text-transform:uppercase;letter-spacing:.04em}
+  td.num{color:#889;width:34px}
+  td.dur{white-space:nowrap;font-variant-numeric:tabular-nums;color:#556}
+  .pill{display:inline-block;padding:2px 8px;border-radius:10px;font-size:11px;font-weight:700}
+  .retry{color:#8a6d00;font-size:11px}
+  tr.failed td.title{font-weight:600}
+  pre{margin:0;white-space:pre-wrap;font-size:12px;color:#B00020;max-height:200px;overflow:auto}
+  .foot{color:#889;font-size:12px;margin-top:14px}
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>${esc(this.title)}</h1>
+    <div class="meta">
+      module <b>${esc(this._module || "NA")}</b> &nbsp;·&nbsp; suite <b>${esc(this._suite || "NA")}</b>
+      &nbsp;·&nbsp; engine <b>playwright</b> &nbsp;·&nbsp; result <span class="overall">${esc(overall.toUpperCase())}</span>
+    </div>
+    <div class="cards">
+      <div class="card"><div class="n">${total}</div><div class="l">Total</div></div>
+      <div class="card"><div class="n" style="color:#1B7A1B">${counts.passed}</div><div class="l">Passed</div></div>
+      <div class="card"><div class="n" style="color:#B00020">${counts.failed}</div><div class="l">Failed</div></div>
+      <div class="card"><div class="n" style="color:#8a6d00">${counts.skipped}</div><div class="l">Skipped</div></div>
+      <div class="card"><div class="n">${fmtDuration(wallMs)}</div><div class="l">Duration</div></div>
+    </div>
+    <table>
+      <thead><tr><th>#</th><th>Status</th><th>Test</th><th>Time</th><th>Error</th></tr></thead>
+      <tbody>${rows || '<tr><td colspan="5">No tests ran.</td></tr>'}</tbody>
+    </table>
+    <div class="foot">Generated by @capillarytech/cap-ui-utils Playwright reporter — results contract compatible with the WDIO master-report.</div>
+  </div>
+</body>
+</html>`;
+    }
+}
+
+module.exports = CapPlaywrightReporter;
+module.exports.default = CapPlaywrightReporter;

package/e2e/playwright/waits.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Network-driven wait helpers — phase-2 Playwright convention.
+ *
+ * Rule (see phase-2 docs): NEVER use fixed sleeps. Prefer web-first assertions
+ * (their timeout is a max budget, not a delay) and arm waitForResponse BEFORE the
+ * action. These helpers standardise that so every migrated suite waits the same way.
+ */
+
+/**
+ * Arm a response wait BEFORE the triggering action, then await it after.
+ *   const wait = waitForApi(page, '/api/badges');
+ *   await createBtn.click();
+ *   const resp = await wait;
+ */
+function waitForApi(page, urlPart, status = 200, timeout = 30000) {
+    return page.waitForResponse(
+        (r) => r.url().includes(urlPart) && (status == null || r.status() === status),
+        { timeout }
+    );
+}
+
+/** Run an action and wait for the matching response in one call. */
+async function clickAndWaitForApi(locator, page, urlPart, status = 200, timeout = 30000) {
+    const wait = waitForApi(page, urlPart, status, timeout);
+    await locator.click();
+    return wait;
+}
+
+/** Wait until any in-flight XHR/fetch to `urlPart` settles (response seen). */
+async function waitForApiIdle(page, urlPart, status = 200, timeout = 30000) {
+    await waitForApi(page, urlPart, status, timeout);
+}
+
+module.exports = { waitForApi, clickAndWaitForApi, waitForApiIdle };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capillarytech/cap-ui-utils",
-  "version": "3.1.3",
+  "version": "3.2.0-beta.1",
   "publishConfig": {
     "access": "public"
   },