@capillarytech/cap-ui-utils 3.0.18 → 3.1.0

package/e2e/utils/elementUtil.ts

@@ -0,0 +1,757 @@
+import { strict as assert } from "assert";
+
+class ElementUtils {
+    async hoverToReveal(element:WebdriverIO.Element){
+        await element.waitForDisplayed({ timeout: 60000 });
+        await element.moveTo();
+        await browser.execute((el) => {
+            ['mouseenter','mouseover','mousemove'].forEach((t) =>
+                el.dispatchEvent(new MouseEvent(t, { bubbles: true })));
+        }, element);
+        await browser.pause(400);
+    }
+
+    async elementClick(element:WebdriverIO.Element){
+        await browser.pause(2000)
+        await element.waitForDisplayed({ timeout: 90000})
+        try{
+           await element.waitForClickable({ timeout: 60000, interval:1000, timeoutMsg:await element.getHTML(false)+" is still not clickable" })
+           await element.click()
+        }
+        catch(error){
+           await this.forceClick(element)
+        }
+    }
+
+    /**
+     * Scrolls the element to viewport center and clicks it via a dispatched
+     * pointer/mouse-event sequence — bypasses WDIO's isClickable coverage check.
+     * Use when an element is displayed but reports "not clickable" because an
+     * overlay (info banner, lingering popover) sits over its centre point, or
+     * antd selects that open on mousedown rather than click.
+     */
+    async forceClick(element:WebdriverIO.Element){
+        const fresh = await this.waitForDisplayedStaleSafe(element, 90000);
+        await browser.execute((el: any) => {
+            el.scrollIntoView({ block: "center", inline: "center" });
+            ['pointerdown','mousedown','pointerup','mouseup','click'].forEach((t) =>
+                el.dispatchEvent(new MouseEvent(t, { bubbles: true, cancelable: true, view: window })));
+        }, fresh);
+        await browser.pause(500);
+    }
+
+    /**
+     * Re-fetches a fresh element from its original selector. A detached ("stale")
+     * handle — left behind when React/antd re-renders the node — is replaced by a
+     * live one. Falls back to the original reference for elements without a plain
+     * string selector (e.g. chained/derived elements).
+     */
+    private async refetch(element: WebdriverIO.Element): Promise<WebdriverIO.Element> {
+        // `.selector` on an un-awaited ChainablePromiseElement (e.g. a page getter
+        // passed straight through, as every current caller does) resolves lazily —
+        // reading it as a promise, not a sync property, prevents this from always
+        // seeing a Promise object and silently skipping the re-query.
+        const selector = await (element as any)?.selector;
+        return typeof selector === "string" ? await $(selector) : element;
+    }
+
+    /**
+     * waitForDisplayed that survives the target re-rendering mid-wait, returning
+     * the live handle it last confirmed. WDIO's built-in waitForDisplayed polls
+     * one resolved handle for the whole timeout window; if the node gets
+     * swapped out from under it (modal mount/zoom transition still settling,
+     * a button's loading-spinner state toggling) that throws "stale element
+     * reference" instead of just waiting longer. Re-fetch and keep waiting
+     * until the timeout budget is spent, so callers (forceClick in particular)
+     * get a fresh, currently-attached element instead of one that already went
+     * stale during the wait.
+     */
+    private async waitForDisplayedStaleSafe(element: WebdriverIO.Element, timeout: number = 90000): Promise<WebdriverIO.Element> {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            const el = await this.refetch(element);
+            const remaining = Math.max(timeout - (Date.now() - start), 1000);
+            const outcome = await el
+                .waitForDisplayed({ timeout: remaining, interval: 500 })
+                .then(() => "displayed")
+                .catch((error) =>
+                    String((error as any)?.message ?? error).includes("stale element reference")
+                        ? "stale"
+                        : "timeout"
+                );
+            if (outcome === "displayed") return el;
+            if (outcome === "timeout") throw new Error("Element not displayed within timeout");
+            await browser.pause(300); // stale → re-query and keep waiting
+        }
+        throw new Error("Element kept going stale while waiting for it to be displayed");
+    }
+
+    /**
+     * Clicks an element, retrying against a freshly re-queried node whenever the
+     * DOM re-renders mid-interaction and throws "stale element reference" (antd
+     * modal mount/zoom transition, React reconcile). On a genuine non-stale
+     * failure it falls back to a forced click. Throws only if nothing succeeds
+     * within `timeout`.
+     */
+    private async clickWithStaleRetry(element: WebdriverIO.Element, timeout: number = 40000): Promise<void> {
+        const start = Date.now();
+        // Uses promise .catch() rather than nested try/catch blocks: a genuine
+        // failure still propagates cleanly to WDIO so the failure screenshot is
+        // captured (nested catches were breaking that earlier).
+        while (Date.now() - start < timeout) {
+            const el = await this.refetch(element);
+            const outcome = await el
+                .waitForClickable({ timeout: 10000, interval: 500 })
+                .then(() => el.click())
+                .then(() => "clicked")
+                .catch((error) =>
+                    String((error as any)?.message ?? error).includes("stale element reference")
+                        ? "stale"
+                        : "unclickable"
+                );
+            if (outcome === "clicked") return;
+            if (outcome === "unclickable") break;   // genuine (non-stale) failure → forced click
+            await browser.pause(500);               // stale → re-query and retry
+        }
+        // Single fallback: forceClick re-fetches and stale-waits internally, so
+        // it survives the target still churning after the loop above gave up.
+        // No try/catch — a genuine failure here should throw and surface the
+        // real error to the test (and its screenshot).
+        await this.forceClick(element);
+    }
+
+    /**
+     * Expands an antd Collapse (accordion) left-nav section by its header label,
+     * then confirms `confirmChild` became visible.
+     *
+     * The toggle handler lives on the `.ant-collapse-header` row (role="tab"); a
+     * native WebDriver click on the inner <span> does NOT reliably fire it (the
+     * click lands at the row centre), so the panel stays collapsed and its items
+     * remain present-but-hidden — which is why waitForDisplayed on a child times
+     * out. We instead JS-click the header element (which reliably fires antd's
+     * toggle), gate each click on aria-expanded (re-clicking an OPEN panel would
+     * collapse it), and retry up to `attempts` times until the child is visible.
+     *
+     * This is the shared version of the fix originally inlined in kpi.page
+     * navigateLibrary; use it for every left-nav section (Library, Data connectors,
+     * User segments, …). `label` is the visible header text; `confirmChild` is any
+     * element that only becomes visible once the section is expanded.
+     */
+    async expandSideNavSection(label: string, confirmChild: WebdriverIO.Element, attempts = 3): Promise<void> {
+        // The header label may be a <span> (top-level sections) or a <div> (nested
+        // sub-accordions like "Status"), so match any element by its text.
+        const header = await $(
+            `//div[@role="tab" and contains(@class,"ant-collapse-header")][.//*[normalize-space(text())="${label}"]]`
+        );
+        await header.waitForDisplayed({ timeout: 60000 });
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            const expanded = (await header.getAttribute("aria-expanded")) === "true";
+            if (!expanded) {
+                await header.waitForClickable({ timeout: 40000 });
+                await browser.execute((el: any) => el.click(), header);
+                console.log(`Expanded side-nav "${label}" (attempt ${attempt})`);
+            }
+            const visible = await confirmChild
+                .waitForDisplayed({ timeout: 20000 })
+                .then(() => true)
+                .catch(() => false);
+            if (visible) {
+                console.log(`Side-nav "${label}" expanded — content visible`);
+                return;
+            }
+        }
+        throw new Error(`Side-nav section "${label}" did not expand to reveal its content`);
+    }
+
+    /**
+     * Opens a leaf item that lives inside a left-nav antd Collapse section:
+     * expands the section (idempotent) via expandSideNavSection, then clicks the
+     * leaf. The Insights nav can re-render on late API content and collapse a
+     * just-expanded section, so the whole expand+click is RETRIED — a mid-flow
+     * collapse (leaf visible on expand, gone by click time) self-heals on the next
+     * attempt. Use for the "expand section -> click child" pattern
+     * (Library -> Charts, Data connectors -> Export schedules, User segments -> Status).
+     */
+    async openSideNavItem(sectionLabel: string, leaf: WebdriverIO.Element, attempts = 3): Promise<void> {
+        let lastError: unknown;
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                await this.expandSideNavSection(sectionLabel, leaf);
+                await leaf.waitForClickable({ timeout: 15000 });
+                await leaf.click();
+                console.log(`Opened "${sectionLabel}" item on attempt ${attempt}`);
+                return;
+            } catch (error) {
+                lastError = error;
+                console.log(`openSideNavItem "${sectionLabel}": attempt ${attempt}/${attempts} failed (${error}) — re-expanding`);
+                await browser.pause(2000);
+            }
+        }
+        throw new Error(`openSideNavItem: could not open item under "${sectionLabel}" after ${attempts} attempts. Last error: ${lastError}`);
+    }
+
+    async enterText(element:WebdriverIO.Element, textToEnter){
+            await browser.pause(1000)
+            // browser.execute('arguments[0].style.outline = "#f00 solid 4px";', element);
+            await element.waitForEnabled({ timeout: 40000, interval:1000, timeoutMsg:await element.getHTML(false)+" is still not editable" })
+            await element.setValue(textToEnter)
+    }
+
+    /**
+     * Types text using addValue (key events). Use for React controlled inputs
+     * where setValue does not update state.
+     */
+    async typeText(element: WebdriverIO.Element, textToEnter: string) {
+      await browser.pause(1000);
+      await element.waitForEnabled({
+        timeout: 40000,
+        interval: 1000,
+        timeoutMsg: await element.getHTML(false) + " is still not editable"
+      });
+      await element.addValue(textToEnter);
+    }
+
+    /**
+     * Selects a date by clicking through the antd calendar UI instead of
+     * typing into the input. Some DatePicker instances only accept a value
+     * chosen from their own calendar grid — typed/pasted text never commits
+     * (the input looks like it accepted it, but nothing was actually
+     * selected).
+     *
+     * The target day is usually already visible as a grayed spillover cell at
+     * the edge of the current month's grid (e.g. "1" shown right after "31")
+     * — antd's `<td>` cells carry a `title="YYYY-MM-DD"` attribute regardless
+     * of which month they spill over from, so clicking that cell directly
+     * both selects the date AND navigates the panel to its month. If the
+     * target is further out and no such cell is on screen at all, this falls
+     * back to walking the calendar header forward/back one month at a time
+     * (via the next/prev-month buttons) until the target month is showing,
+     * then clicks the day cell there.
+     */
+    async selectCalendarDate(dateInput: WebdriverIO.Element, targetDate: Date, label = "date field") {
+        const isoDate = `${targetDate.getFullYear()}-${String(targetDate.getMonth() + 1).padStart(2, "0")}-${String(targetDate.getDate()).padStart(2, "0")}`;
+        const expectedDisplay = targetDate.toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" });
+
+        await this.retryStep(async () => {
+            const input = await this.refetch(dateInput);
+            await input.waitForClickable({ timeout: 40000 });
+            await input.click();
+
+            const panel = await $('//div[contains(@class,"ant-picker-dropdown") and not(contains(@class,"ant-picker-dropdown-hidden"))]');
+            await panel.waitForDisplayed({ timeout: 10000 });
+
+            let dayCell = await panel.$(`.//td[@title="${isoDate}"]`);
+            const alreadyVisible = await dayCell.isDisplayed().catch(() => false);
+
+            if (!alreadyVisible) {
+                const headerView = await panel.$(".ant-picker-header-view");
+                const nextBtn = await panel.$(".ant-picker-header-next-btn");
+                const prevBtn = await panel.$(".ant-picker-header-prev-btn");
+                const targetMonths = targetDate.getFullYear() * 12 + targetDate.getMonth();
+
+                for (let attempt = 0; attempt < 24; attempt++) {
+                    const shownText = (await headerView.getText()).trim(); // e.g. "Jul 2026"
+                    const shownDate = new Date(`1 ${shownText}`);
+                    const shownMonths = shownDate.getFullYear() * 12 + shownDate.getMonth();
+                    const diff = targetMonths - shownMonths;
+                    if (diff === 0) break;
+                    if (attempt === 23) {
+                        throw new Error(`${label}: could not navigate calendar to target month (stuck on "${shownText}")`);
+                    }
+                    await (diff > 0 ? nextBtn : prevBtn).click();
+                    await browser.pause(300);
+                }
+                dayCell = await panel.$(`.//td[@title="${isoDate}"]`);
+            }
+
+            await dayCell.waitForClickable({ timeout: 10000 });
+            await dayCell.click();
+
+            await panel.waitForDisplayed({ timeout: 5000, reverse: true });
+
+            const committed = await input.getValue();
+            if (committed !== expectedDisplay) {
+                throw new Error(`${label} did not commit: expected "${expectedDisplay}", got "${committed}"`);
+            }
+            console.log(`${label} set to ${expectedDisplay} via calendar click`);
+        }, {
+            maxAttempts: 3,
+            label,
+            beforeRetry: async () => {
+                await browser.keys("Escape");
+            },
+        });
+    }
+
+    /**
+     * Writes via the native HTMLInputElement value setter, then dispatches an
+     * `input` event. Bypasses React's `_valueTracker`, so React commits the
+     * new value as a single state update.
+     *
+     * WebDriver's char-by-char typing races with antd v6 / React 18 controlled
+     * inputs and drops every character after the first. This injection avoids
+     * that race entirely.
+     *
+     * Accepts either a CSS `selector` string or an already-resolved WDIO
+     * element. With a selector, `alsoDispatch` adds extra events after `input`
+     * (e.g. `["change", "blur"]`) when the field's logic relies on them
+     * (validation, commit-on-blur, etc). With an element, it first waits for the
+     * field to be editable, then dispatches `change` + blur after `input`.
+     */
+    async setReactInputValue(
+      target: string | WebdriverIO.Element,
+      value: string,
+      alsoDispatch: Array<"change" | "blur"> = [],
+    ) {
+      if (typeof target === "string") {
+        await browser.execute(
+          (sel: string, val: string, extras: string[]) => {
+            const input = document.querySelector(sel) as HTMLInputElement | null;
+            if (!input) {
+              throw new Error(`setReactInputValue: no element matches selector "${sel}"`);
+            }
+            const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')!.set!;
+            setter.call(input, val);
+            input.dispatchEvent(new Event('input', { bubbles: true }));
+            for (const name of extras) {
+              input.dispatchEvent(new Event(name, { bubbles: true }));
+            }
+          },
+          target,
+          value,
+          alsoDispatch,
+        );
+        return;
+      }
+      await browser.pause(1000);
+      await target.waitForEnabled({
+        timeout: 40000,
+        interval: 1000,
+        timeoutMsg: await target.getHTML(false) + " is still not editable"
+      });
+      await browser.execute((el: any, val: string) => {
+        const desc = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, "value");
+        if (desc && desc.set) {
+          desc.set.call(el, val);
+        } else {
+          el.value = val;
+        }
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+        el.blur();
+      }, target, value);
+    }
+
+   async switchToUrl(url: string){
+      await browser.switchWindow('url')
+     }
+
+   async waitUntilDisplayed(element:WebdriverIO.Element, awaitedText, timeout=30000){
+      try {
+        // First wait for element to be displayed
+        await element.waitForDisplayed({ timeout: timeout, timeoutMsg: `Element not displayed within ${timeout} ms` });
+        
+        // Then wait for the correct text
+        await element.waitUntil(async function () {
+           const currentText = await this.getText();
+           console.log(`Waiting for text: '${awaitedText}', Current text: '${currentText}'`);
+           return currentText.includes(awaitedText) || currentText === awaitedText;
+        }, {
+            timeout, 
+            timeoutMsg: `Unable to locate the awaited text: '${awaitedText}' within ${timeout} ms`
+        });
+      } catch (error) {
+        console.log(`🔴 Error in waitUntilDisplayed: ${error}`);
+        throw error;
+      }
+    }
+
+   async waitUntilEnabled(element:WebdriverIO.Element){
+      await element.waitUntil(async function () {
+         return await element.isEnabled();
+     }, {
+         timeout: 90000,
+         timeoutMsg: 'Element not enabled'
+     });
+     }
+    async checkElemetExistsAndElementClick(element:WebdriverIO.Element){
+        await browser.pause(1000);
+        let isDisplayed = await element.isDisplayed();
+        if (isDisplayed) {
+         await element.waitForClickable({ timeout: 40000, interval:1000, timeoutMsg:await element.getHTML(false)+" is still not clickable" })
+         await element.click()
+        }
+    }
+
+    /**
+     * Stale-safe variant of checkElemetExistsAndElementClick. Opt-in helper for
+     * optional buttons that live inside a re-rendering container — e.g. the
+     * reset-optin confirmation modal, whose node is swapped by the antd mount/
+     * transition between the presence check and the click, throwing "stale
+     * element reference". Kept as a separate method so the widely-used shared
+     * helpers stay untouched and other modules are unaffected.
+     */
+    async checkElementExistsAndClickStaleSafe(element:WebdriverIO.Element, appearTimeout: number = 3000){
+        // Presence must be *waited* for, not sampled. A fixed pause + one
+        // isDisplayed() snapshot loses the race against an antd modal's
+        // mount + zoom transition: the helper returns "not there", the modal
+        // then opens and is never confirmed, and its mask silently intercepts
+        // every later click on the page (each one burning the full
+        // waitForClickable timeout before elementClick's forceClick fallback
+        // punches through it) until something without a fallback — a hover —
+        // finally hard-fails, several steps away from the real cause.
+        const fresh = await this.refetch(element);
+        const appeared = await fresh
+            .waitForDisplayed({ timeout: appearTimeout, interval: 250 })
+            .then(() => true)
+            .catch(() => false);
+        if (!appeared) return false;
+
+        await this.clickWithStaleRetry(element, 40000);
+
+        // Confirm the modal actually went away: if it is still up, everything
+        // downstream is about to fail confusingly, so fail here instead.
+        const dismissed = await (await this.refetch(element))
+            .waitForDisplayed({ reverse: true, timeout: 20000, interval: 250 })
+            .then(() => true)
+            .catch(() => false);
+        if (!dismissed) {
+            throw new Error("Confirmation modal was clicked but is still displayed — it will block subsequent steps");
+        }
+        return true;
+    }
+
+    /**
+     * Use this when the element/input is optional (not mandatory).
+     * Does not throw if the element is not displayed; only logs and skips entering text.
+     */
+    async checkElemetExistsAndEnterText(element: WebdriverIO.Element, textToEnter: string) {
+        const isDisplayed = await element.isDisplayed();
+        if (isDisplayed) {
+            await element.waitForEnabled({
+                timeout: 40000,
+                interval: 1000,
+                timeoutMsg: await element.getHTML(false) + " is still not editable"
+            });
+            await element.setValue(textToEnter);
+        }
+    }
+
+    async isElementDisplayed(element:WebdriverIO.Element){
+        await browser.pause(1000)
+        let isDisplayed = await element.isDisplayed();
+        return isDisplayed;
+     }
+     
+     async elementHover(element: WebdriverIO.Element) {
+        try {
+            // Pause for 2 seconds before starting (optional)
+            await browser.pause(2000);
+    
+            // Wait for the element to be displayed
+            await element.waitForDisplayed({ timeout: 90000 });
+    
+            // Wait for the element to be interactable/clickable (often ensures it's not obscured)
+            await element.waitForClickable({ 
+                timeout: 40000, 
+                interval: 1000, 
+                timeoutMsg: await element.getHTML(false) + " is still not interactable for hover"
+            });
+    
+            // Perform the hover action
+            await element.moveTo();
+            console.log('Move to action performed');
+        } catch (error) {
+            throw new Error(error);
+        }
+    }
+        
+    /**
+     * Click the button only if it becomes clickable within the given timeout.
+     * Uses a short timeout (default 1s) to avoid waiting when the button stays disabled (e.g. after validation failure).
+     * Use during unmatched-braces checks: if Done/Save becomes clickable we click it; otherwise we skip and assert the error.
+     */
+    async clickIfClickable(button: WebdriverIO.Element, timeoutMs = 1000) {
+      try {
+        await button.waitForClickable({ timeout: timeoutMs });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/timeout|not clickable/i.test(message)) {
+          // Button stayed disabled within the timeout; caller will assert validation error.
+          return;
+        }
+        throw error;
+      }
+
+      // waitForClickable succeeded — click errors propagate normally.
+      await button.click();
+    }
+
+    /**
+     * Clear the input's current value then type new text.
+     * Delegates the clear step to selectAllAndClear (select-all + Backspace) so
+     * React-controlled inputs see the onChange event. Only calls setValue when
+     * textToEnter is non-empty.
+     */
+    async clearAndEnterText(element: WebdriverIO.Element, textToEnter: string) {
+        await this.selectAllAndClear(element);
+        if (textToEnter !== '') {
+            await element.setValue(textToEnter);
+        }
+    }
+
+    /**
+     * Clear text by sending Backspace key N times (N = textToRemove.length).
+     * If element is provided, focus it first (click) so backspaces apply to that field.
+     * Use for clearing content in inputs/editors (e.g. unmatched-braces recovery in Viber, Email CodeMirror).
+     */
+    async clearByBackspace(textToRemove: string, element?: WebdriverIO.Element) {
+      if (element) {
+        await element.waitForDisplayed({ timeout: 10000 });
+        await element.click();
+      }
+      const count = textToRemove.length;
+      for (let i = 0; i < count; i++) {
+        await browser.keys(["Backspace"]);
+      }
+    }
+
+    /**
+     * Wait for a spinner to appear (optional) then disappear.
+     * Mirrors the pattern in deleteTemplate: catches if spinner never appears (loaded too fast),
+     * then waits for it to vanish before proceeding.
+     */
+    async waitForSpinnerCycle(
+      spinner: WebdriverIO.Element,
+      appearTimeoutMs = 5000,
+      disappearTimeoutMs = 180000
+    ) {
+      await spinner.waitForDisplayed({ timeout: appearTimeoutMs }).catch(() => {
+        console.log("Spinner did not appear — may have loaded too fast, proceeding");
+      });
+      await spinner.waitForDisplayed({ timeout: disappearTimeoutMs, reverse: true });
+    }
+
+    /**
+     * Best-effort loader "settle" for the blank-screen -> loader -> content
+     * lifecycle. Waits (advisory) for a loader to APPEAR, then to DISAPPEAR, both
+     * swallowed so a slow/absent/stuck loader never hard-fails the caller. A bare
+     * reverse-only wait races: while the page is still a blank white screen the
+     * loader is not yet mounted, so "wait until no loader" is already true and
+     * returns instantly. The appear wait closes that race; callers that need a
+     * hard guarantee should follow this with a positive element check (e.g.
+     * waitForStableVisible on real content).
+     */
+    async waitForLoaderSettle(
+      loader: WebdriverIO.Element,
+      { appearTimeoutMs = 20000, disappearTimeoutMs = 180000 } = {}
+    ) {
+      await loader
+        .waitForDisplayed({ timeout: appearTimeoutMs })
+        .catch(() => console.log(`Loader did not appear within ${appearTimeoutMs}ms — proceeding`));
+      await loader
+        .waitForDisplayed({ timeout: disappearTimeoutMs, reverse: true })
+        .catch(() => console.log(`Loader still present after ${disappearTimeoutMs}ms — proceeding (positive check gates)`));
+    }
+
+    /**
+     * Reusable try-catch handler function for waiting and verifying elements
+     */
+    async waitForElementAndVerify({ element, timeout = 30000, label, name }) {
+        try {
+            await element.waitForDisplayed({ timeout });
+            console.log(`${label} found in search results:`, name);
+        } catch (error) {
+            console.error(`${label} not found in search results:`, name);
+            throw new Error(`${label} "${name}" not found in search results`);
+        }
+    }
+
+    /**
+     * Counts visible elements in a `$$` collection and asserts it equals `expected`.
+     * antd v6 keeps duplicate hidden DOM nodes around, so plain `.length` isn't reliable.
+     */
+    async assertVisibleCount(
+      elements: WebdriverIO.ElementArray,
+      expected: number,
+      label = "elements"
+    ) {
+      let visibleCount = 0;
+      for (const el of elements) {
+        if (await el.isDisplayed().catch(() => false)) visibleCount++;
+      }
+      assert.equal(
+        visibleCount,
+        expected,
+        `Expected ${expected} visible ${label} but found ${visibleCount}`
+      );
+      console.log(`🟢 Verified visible ${label} count = ${visibleCount}`);
+    }
+
+    /**
+     * Polls `$$(selector)` until one match is displayed, skipping hidden duplicates
+     * (e.g. antd keeps inactive tab panes mounted in the DOM).
+     */
+    async firstVisibleElement(selector: string, timeout = 90000): Promise<WebdriverIO.Element> {
+        let found: WebdriverIO.Element | undefined;
+        await browser.waitUntil(
+            async () => {
+                const elements = await $$(selector);
+                for (const element of elements) {
+                    if (await element.isDisplayed()) {
+                        found = element;
+                        return true;
+                    }
+                }
+                return false;
+            },
+            { timeout, timeoutMsg: `No visible element matched selector: ${selector}` }
+        );
+        return found as WebdriverIO.Element;
+    }
+
+    /**
+     * Races candidates and confirms the winner is stably displayed.
+     * After a candidate wins the race, waits stableMs then re-checks.
+     * If the winner disappeared, retries the full race with remaining timeout.
+     * Only throws when the total timeout is exhausted.
+     */
+    async waitForStableVisible(
+        candidates: WebdriverIO.Element[],
+        timeout: number,
+        stableMs: number = 5000,
+    ): Promise<WebdriverIO.Element> {
+        const deadline = Date.now() + timeout;
+        while (true) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error(`waitForStableVisible: no stable candidate within ${timeout}ms`);
+            }
+            await Promise.race(candidates.map((el) => el.waitForDisplayed({ timeout: remaining })));
+            for (const el of candidates) {
+                if (await el.isDisplayed()) {
+                    await browser.pause(stableMs);
+                    if (await el.isDisplayed()) return el;
+                    console.log(`waitForStableVisible: candidate "${el.selector}" disappeared — retrying race`);
+                    break;
+                }
+            }
+        }
+    }
+
+    /**
+     * Retries an async step until it completes without throwing, up to `maxAttempts`
+     * times (default 3). The flow only moves ahead once the step is acknowledged
+     * (resolves) — so a missing application/build that is not yet populated by the
+     * backend gets re-attempted instead of failing the whole test on the first miss.
+     *
+     * Between failed attempts it pauses `delayMs`, then optionally runs `beforeRetry`
+     * (e.g. refresh / re-trigger a search) before the next attempt. The last error is
+     * only re-thrown after every attempt is exhausted.
+     */
+    async retryStep<T>(
+        action: () => Promise<T>,
+        options: {
+            maxAttempts?: number;
+            delayMs?: number;
+            label?: string;
+            beforeRetry?: (attempt: number) => Promise<void>;
+        } = {}
+    ): Promise<T> {
+        const { maxAttempts = 3, delayMs = 3000, label = "step", beforeRetry } = options;
+        let lastError: unknown;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                console.log(`[retry] Attempt ${attempt}/${maxAttempts} for: '${label}'`);
+                const result = await action();
+                console.log(`[retry] '${label}' acknowledged on attempt ${attempt}/${maxAttempts}`);
+                return result;
+            } catch (error) {
+                lastError = error;
+                console.log(`[retry] '${label}' failed on attempt ${attempt}/${maxAttempts}: ${error}`);
+                if (attempt < maxAttempts) {
+                    await browser.pause(delayMs);
+                    if (beforeRetry) {
+                        await beforeRetry(attempt);
+                    }
+                }
+            }
+        }
+        throw new Error(`[retry] '${label}' failed after ${maxAttempts} attempts. Last error: ${lastError}`);
+    }
+
+    /**
+     * Guards a step's precondition: the element that the PREVIOUS step is expected to
+     * have produced must be present before the current step runs. If it is not displayed
+     * within `timeout`, throws a descriptive error naming the missing output, so a step
+     * never acts on a page that silently reset or where the prior step never delivered
+     * its result. Returns true when the precondition holds (use the return value inside
+     * a retry's beforeRetry hook to decide whether re-confirmation is needed).
+     */
+    async ensurePrecondition(element: WebdriverIO.Element, label: string, timeout = 15000): Promise<boolean> {
+        try {
+            await element.waitForDisplayed({ timeout, interval: 500 });
+            console.log(`[precondition] OK — previous step output present: '${label}'`);
+            return true;
+        } catch (error) {
+            throw new Error(
+                `[precondition] FAILED — expected output from the previous step is not present: '${label}'. ` +
+                `The current step will not run. Underlying: ${error}`
+            );
+        }
+    }
+
+    /**
+     * Selects all text in a React controlled input and clears it via Backspace,
+     * triggering React's onChange. Use instead of clearValue() for React inputs.
+     */
+    async selectAllAndClear(element: WebdriverIO.Element) {
+        await element.waitForEnabled({ timeout: 40000, interval: 1000 });
+        await browser.execute((el: any) => el.select(), element);
+        await browser.keys("Backspace");
+    }
+
+    async clearByKeysAndType(element: WebdriverIO.Element, textToEnter: string) {
+        await element.waitForDisplayed({ timeout: 20000 });
+        await element.waitForEnabled({ timeout: 40000, interval: 1000 });
+        await element.click();
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const current = await element.getValue();
+            if (!current) break;
+            await browser.keys("End");
+            await browser.keys(new Array(current.length + 2).fill("Backspace"));
+        }
+        if (textToEnter !== "") {
+            await element.addValue(textToEnter);
+        }
+    }
+
+    /**
+     * Moves the cursor to the absolute end of the currently focused contenteditable element
+     * (e.g. TinyMCE inline editor) using the DOM Selection API.
+     *
+     * Keyboard shortcuts (End, Ctrl+End, Cmd+Down+Cmd+Right) are unreliable in TinyMCE —
+     * the editor intercepts them or they only reach end of the current visual line when
+     * content wraps. Direct DOM manipulation bypasses all of that.
+     *
+     * Requires the target element to already have focus (call element.click() first).
+     * Runs in the current WebDriver frame context — call from inside the BeFree iframe
+     * after switchToIframe() so document refers to the iframe document.
+     */
+    async moveCursorToEndOfContentEditable(): Promise<void> {
+        await browser.execute(() => {
+            const el = document.activeElement as HTMLElement;
+            if (!el || !el.isContentEditable) return;
+            const range = document.createRange();
+            const sel = window.getSelection();
+            if (!sel) return;
+            range.selectNodeContents(el);
+            range.collapse(false); // collapse to end
+            sel.removeAllRanges();
+            sel.addRange(range);
+        });
+    }
+
+}
+
+export default new ElementUtils()