@capillarytech/cap-ui-utils 3.0.20 → 3.1.1

package/e2e/README.md

@@ -0,0 +1,57 @@
+# `@capillarytech/cap-ui-utils/e2e` — shared WDIO E2E toolkit
+
+The framework-agnostic, **data-free** E2E helpers that were duplicated byte-for-byte
+across the product repos (`wdio-ui-automation`, `garuda-ui`, …). Centralizing them
+here means one source of truth: a fix or a new helper lands once, and every product
+repo picks it up on the next `@capillarytech/cap-ui-utils` bump.
+
+## Usage
+
+```ts
+// whole toolkit
+import { elementUtil, loginPage, antdVersion } from '@capillarytech/cap-ui-utils/e2e';
+
+// or a single module (deep import — matches the old relative-path style)
+import elementUtil from '@capillarytech/cap-ui-utils/e2e/utils/elementUtil';
+import loginPage   from '@capillarytech/cap-ui-utils/e2e/pages/common/login.page';
+```
+
+The E2E test tooling (`webdriverio`, `@rpii/wdio-commands`, `axios`, `supertest`,
+`nanoid`) is declared as **optional `peerDependencies`** — only repos that actually
+run E2E install them; runtime apps that import `@capillarytech/cap-ui-utils` are
+unaffected.
+
+## What's here (this drop)
+
+Only helpers that are **self-contained and free of per-repo test data**:
+
+| Area | Modules |
+|---|---|
+| Element interaction | `utils/elementUtil` |
+| antd version detection | `utils/antdVersionUtil` |
+| Assertions | `utils/expectUtil` |
+| Login flow | `pages/common/login.page`, `pages/common/base.page` |
+| Reporting / recording | `utils/reportUploader`, `utils/logCollectorUtil`, `utils/requestRecorderUtil`, `utils/screenshotRecorderUtil` |
+| Mocking | `utils/setupMock`, `utils/mockResponse` |
+| Misc infra | `utils/debugModeUtil`, `utils/featureFlagUtil`, `utils/automationBypassUtil`, `utils/deletionRegistry`, `utils/garudaDropdownUtil`, `utils/htmlEditorUtil`, `utils/virtualListUtil`, `utils/unmatchedBracesUtil`, `utils/uploaders/*` |
+| Services | `services/lockService`, `services/locks/*` |
+| Config | `constants/common` (waits, log markers, `maxLoginAttempts`) |
+
+Two small decouplings were applied on the way in:
+- `logCollectorUtil` had a **dead** `import { config } from '../../test/wdio.conf'` (never used) — removed.
+- `login.page` imported `maxLoginAttempts` from the data aggregator `constants/constants`; repointed to `constants/common` so the toolkit carries no org/auth data.
+
+## Deliberately NOT here yet (data-coupled)
+
+These read the per-repo `cons` object (merged `org`/`auth`/`endpoints`/`url` test
+data, keyed by `cluster`/`module`) via `constants/constants`, so moving them as-is
+would drag the whole per-tenant data layer into this shared package:
+
+`utils/apiUtil`, `utils/helperUtil`, `utils/cookieUtil` (org switch),
+`utils/navigationUtil`, `utils/appNavigationUtil`, `services/requestRecorderService`,
+`pages/common/home.page`, `pages/common/testAndPreviewFlow.page`.
+
+**Follow-up:** introduce a tiny config-injection seam (e.g. `e2e/config.setConfig(cons)`
+called once in the consumer's `onPrepare`) so these helpers read config from the
+package instead of importing the data aggregator. Then navigation / org-switch can
+move too, and each repo keeps only its own `org`/`auth`/`endpoints` data.

package/e2e/constants/common.ts

@@ -0,0 +1,23 @@
+// Singapore clusters that require special handling
+export const SG_CLUSTERS = ['sgcrm', 'sgcrmasia'];
+
+export const INFO = "🟡";
+export const SUCCESS = "🟢";
+export const FAILURE = "🔴";
+
+export const WAIT_30S = 30000;
+export const WAIT_60S = 60000;
+export const WAIT_90S = 90000;
+export const WAIT_120S = 120000;
+
+export const common = {
+	"cluster" : process.env.cluster,
+	"validatorUrl" : "http://127.0.0.1:4000",
+	"maxLoginAttempts": 3,
+	"sgClusters": SG_CLUSTERS,
+	"isLoyaltyMigration": process.env.module === 'loyalty_migration',
+}
+
+// login.page.ts (shared) imports this by name; re-exported here so the toolkit
+// stays free of the data-heavy constants/constants aggregator (org/auth/endpoints).
+export const maxLoginAttempts = common.maxLoginAttempts;

package/e2e/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared WDIO E2E toolkit — the framework-agnostic, data-free helpers that were
+ * duplicated byte-for-byte across the product repos (wdio-ui-automation,
+ * garuda-ui, and every future migrated repo).
+ *
+ * Two ways to consume:
+ *   import { elementUtil, loginPage } from '@capillarytech/cap-ui-utils/e2e';
+ *   import elementUtil from '@capillarytech/cap-ui-utils/e2e/utils/elementUtil';
+ *
+ * NOT included yet (data-coupled — they read the per-repo `cons` org/auth/endpoint
+ * data via constants/constants): apiUtil, helperUtil, cookieUtil, navigationUtil,
+ * appNavigationUtil, requestRecorderService, home.page, testAndPreviewFlow.page.
+ * These need a small config-injection seam before they can move — see README.
+ */
+export { default as elementUtil } from './utils/elementUtil';
+export { default as antdVersion } from './utils/antdVersionUtil';
+export { default as expectUtil } from './utils/expectUtil';
+export { default as automationBypass } from './utils/automationBypassUtil';
+export { default as debugMode } from './utils/debugModeUtil';
+export { default as deletionRegistry } from './utils/deletionRegistry';
+export { default as dropdownUtil } from './utils/garudaDropdownUtil';
+export { default as logCollectorUtil } from './utils/logCollectorUtil';
+export { default as reportUploader } from './utils/reportUploader';
+export { default as requestRecorderUtil } from './utils/requestRecorderUtil';
+export { default as screenshotRecorderUtil } from './utils/screenshotRecorderUtil';
+export { default as setupMock } from './utils/setupMock';
+export { default as lockService } from './services/lockService';
+export { default as BasePage } from './pages/common/base.page';
+export { default as loginPage } from './pages/common/login.page';
+export * from './constants/common';

package/e2e/pages/common/base.page.ts

@@ -0,0 +1,11 @@
+export default class BasePage{
+    async launchApplication(url){
+        console.log('Browser Maximize') 
+        browser.maximizeWindow();
+        console.log('Triggered navigate to', url)  
+        await browser.navigateTo(url)
+        console.log('Navigated to URL: ', url);
+    
+    }
+    async quitApplication(){await browser.closeWindow()}
+}

package/e2e/pages/common/constant.ts

@@ -0,0 +1,2 @@
+export const EMAIL = 'email';
+export const WEBPUSH = 'webpush';

package/e2e/pages/common/login.page.ts

@@ -0,0 +1,95 @@
+import basePage from "./base.page"
+import elementUtil from "../../utils/elementUtil"
+import { maxLoginAttempts } from '../../constants/common';
+import commands from "@rpii/wdio-commands"
+
+class LoginPage extends basePage{
+
+get isV2Login(){return process.env.V2_LOGIN === 'true'}
+get inputUserName(){return this.isV2Login ? $('#login-username') : $('#login_user')}
+get inputPassword(){return this.isV2Login ? $('#login-password') : $('#login_cred')}
+get buttonLogin(){return this.isV2Login ? $('//button[.="Sign in"]') : $('#c-login-btn')}
+get continueButton(){return $('//button[.="Continue"]')}
+// Post-login readiness marker. The MFE Navigation Host replaced the old
+// Dashboard (which rendered ExplorePosts → "Explore features") with NewDashboard,
+// so the sidebar shell testid is the reliable signal the home shell has mounted.
+// Old text kept as a backward-compatible fallback for pre-MFE environments.
+get exploreFeatures(){return $('//*[@data-testid="cap-navigation-spa-sidebar"] | //*[text()="Explore features"]')}
+
+  async doLogin(url, username, password, loginTryCount=0){
+    try {
+      await browser.refresh();
+      await browser.pause(3000);
+      console.log('Browser launched')
+      await super.launchApplication(url)
+      if (loginTryCount > 0) {
+        let currentUrl = await browser.getUrl();
+        const isHome = currentUrl.includes("/home/ui");
+        if (isHome) {
+          try {
+            await (await this.exploreFeatures).waitForDisplayed({ timeout: 60000, interval: 5000 });
+            console.log('-----Logged In-----');
+            console.log('On retry login flow, /home/ui url and explore features text appeared after 60s probably, hence skipping entering username and password');
+            return;
+          } catch(e) {
+            console.log('proceeding with retry');
+          }
+        }
+      }
+      for(let i=0; i<=2; i++){
+        try{
+          await (await this.inputUserName).waitForDisplayed({ timeout: 60000 });
+          await this.inputUserName.waitForEnabled({ timeout: 30000,  timeoutMsg:"thrown from dologin", interval:1000 })
+          break;
+        }catch(error){
+          console.log('Failed to load login page- Refreshing browser')
+          await browser.refresh();
+        }
+      }
+      await elementUtil.enterText( await this.inputUserName, username)
+      if (this.isV2Login) {
+        await this.continueButton.waitForEnabled({ timeout: 10000 })
+        await elementUtil.elementClick( await this.continueButton)
+        await this.inputPassword.waitForDisplayed({ timeout: 30000 })
+      }
+      await elementUtil.enterText( await this.inputPassword, password)
+      await this.buttonLogin.waitForEnabled({ timeout: 10000 })
+      await elementUtil.elementClick( await this.buttonLogin)
+      await browser.waitUntil(
+        async () => {
+          let currentUrl = await browser.getUrl();
+          return currentUrl.includes("/home/ui")
+        },
+        {
+          timeout: 60000,
+          timeoutMsg: 'expected url to include /home/ui',
+          interval: 1000,
+        }
+      );
+      console.log('-----Browsers current url contains home/ui after login-----')
+      await (await this.exploreFeatures).waitForDisplayed({ timeout: 60000, interval: 5000 });
+      console.log('-----Logged In-----')
+    }
+    catch (error){
+      console.log('Throwed error from dologin, attempt #: ', loginTryCount, ', Error: ', error);
+      commands.logScreenshot("Failed to get the user logged in: "+error)
+      if (loginTryCount >= (maxLoginAttempts - 1)) {
+        console.log('Since login retry count exceeds 2. Exiting now.');
+        throw new Error("Failed to get the user logged in: "+error);
+      }
+      console.log('Retrying Login.. ');
+      await this.doLogin(url, username, password, ++loginTryCount);
+    }
+  }
+
+  async redirectHome(url){
+    try{
+    await super.launchApplication(url)
+    }
+    catch (error) {
+    commands.logScreenshot("Exception logged: "+error)
+    throw new Error(error)
+    }
+  }
+}
+export default new LoginPage()

package/e2e/services/lockService.ts

@@ -0,0 +1,215 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+// A publish section holds the lock for ~1-3 minutes; anything older than this
+// can only be a leftover from a run that died without releasing.
+const STALE_LOCK_TTL_MS = 15 * 60 * 1000;
+
+class LockService {
+    private baseLockDir: string;
+
+    constructor() {
+        // Lock/signal files default to <this dir>/locks, but can be redirected via LOCK_DIR so that
+        // independent suite runs (e.g. staging v3 + nightly v6 in parallel) don't share signal files
+        // like beeTemplateReady. Backward-compatible: unset LOCK_DIR keeps the original behaviour.
+        this.baseLockDir = process.env.LOCK_DIR
+            ? path.resolve(process.env.LOCK_DIR)
+            : path.resolve(__dirname, 'locks');
+        if (!fs.existsSync(this.baseLockDir)) {
+            fs.mkdirSync(this.baseLockDir, { recursive: true });
+        }
+    }
+
+    initialize() {
+        this.cleanStaleLocks();
+        console.log("Lock service initialized.");
+    }
+
+    private getLockFilePath(lockName: string): string {
+        return path.resolve(this.baseLockDir, `${lockName}.lock`);
+    }
+
+    /**
+     * A lock is stale when its owner can no longer release it: the owning worker
+     * process is dead (identifier format Test-<pid>-<timestamp>), or the file is
+     * older than STALE_LOCK_TTL_MS (covers pid reuse and foreign identifiers).
+     * A stale lock is unreleasable by design (releaseLock enforces owner match),
+     * so every later run would burn all its acquire retries and proceed
+     * UNSERIALIZED — which is how parallel workers end up publishing over each
+     * other. Locks owned by a live process are never touched, so a concurrently
+     * running suite on this machine keeps its serialization.
+     */
+    private isLockStale(lockFilePath: string): boolean {
+        let owner: string;
+        let mtimeMs: number;
+        try {
+            owner = fs.readFileSync(lockFilePath, 'utf8');
+            mtimeMs = fs.statSync(lockFilePath).mtimeMs;
+        } catch {
+            return false; // vanished meanwhile — nothing to clean
+        }
+        // Probe the owner's liveness FIRST — a live owner must never lose its lock,
+        // regardless of age (slow cluster, retried publish, debug SETTLE_MS pauses).
+        // The TTL only applies when the owner is dead, unknown, or a reused pid.
+        const match = /^Test-(\d+)-\d+$/.exec(owner.trim());
+        if (!match) return Date.now() - mtimeMs > STALE_LOCK_TTL_MS; // unknown format — TTL only
+        try {
+            process.kill(Number(match[1]), 0); // signal 0 = liveness probe, sends nothing
+            return false; // owner alive — never steal
+        } catch (error) {
+            // ESRCH: no such process → stale. EPERM: exists but not ours → TTL fallback (pid reuse).
+            if ((error as NodeJS.ErrnoException).code === 'EPERM') {
+                return Date.now() - mtimeMs > STALE_LOCK_TTL_MS;
+            }
+            return true;
+        }
+    }
+
+    private removeIfStale(lockFilePath: string): boolean {
+        if (!this.isLockStale(lockFilePath)) return false;
+        try {
+            fs.unlinkSync(lockFilePath);
+            console.log(`Removed stale lock '${path.basename(lockFilePath)}' (owner dead or TTL expired).`);
+            return true;
+        } catch {
+            return false; // another worker removed it first — fine
+        }
+    }
+
+    /** Sweep all *.lock files in the lock dir, removing only stale ones. */
+    cleanStaleLocks(): void {
+        let lockFiles: string[];
+        try {
+            lockFiles = fs.readdirSync(this.baseLockDir).filter(file => file.endsWith('.lock'));
+        } catch {
+            return;
+        }
+        for (const file of lockFiles) {
+            this.removeIfStale(path.resolve(this.baseLockDir, file));
+        }
+    }
+
+    async acquireLock({
+        testIdentifier,
+        lockName,
+        maxRetries = 10,
+        retryInterval = 1000
+        }: {
+        testIdentifier: string;
+        lockName: string;
+        maxRetries?: number;
+        retryInterval?: number;
+        }): Promise<boolean> {
+
+        const lockFilePath = this.getLockFilePath(lockName);
+
+        for (let retries = 0; ; retries++) {
+            // Self-heal locks left by crashed workers, then try an atomic
+            // create-exclusive: 'wx' fails with EEXIST if the file exists, so two
+            // waiters can never both believe they own the lock.
+            this.removeIfStale(lockFilePath);
+            try {
+                fs.writeFileSync(lockFilePath, testIdentifier, { flag: 'wx' });
+                console.log(`Lock for '${lockName}' acquired by ${testIdentifier}.`);
+                return true;
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+                    console.error(`Failed to acquire lock for '${lockName}':`, error);
+                    return false;
+                }
+            }
+
+            let currentLockOwner = 'unknown';
+            try {
+                currentLockOwner = fs.readFileSync(lockFilePath, 'utf8');
+            } catch {
+                // released between attempts — next loop iteration will grab it
+            }
+            if (retries >= maxRetries) {
+                console.log(`Max retries reached. Lock for '${lockName}' is still held by ${currentLockOwner}.`);
+                return false;
+            }
+            console.log(`Lock for '${lockName}' is already acquired by ${currentLockOwner}. Waiting for release... Retry ${retries + 1}/${maxRetries}`);
+            await browser.pause(retryInterval);
+        }
+    }
+
+    releaseLock(testIdentifier: string, lockName: string): boolean {
+        const lockFilePath = this.getLockFilePath(lockName);
+
+        if (!fs.existsSync(lockFilePath)) {
+            console.log(`Lock for '${lockName}' is not acquired, nothing to release.`);
+            return false;
+        }
+
+        const currentLockOwner = fs.readFileSync(lockFilePath, 'utf8');
+
+        if (currentLockOwner !== testIdentifier) {
+            console.log(`Lock for '${lockName}' cannot be released. Current owner is ${currentLockOwner}, but ${testIdentifier} is trying to release it.`);
+            return false;
+        }
+
+        try {
+            fs.unlinkSync(lockFilePath);
+            console.log(`Lock for '${lockName}' released by ${testIdentifier}.`);
+            return true;
+        } catch (error) {
+            console.error(`Failed to release lock for '${lockName}':`, error);
+            return false;
+        }
+    }
+
+    isLocked(lockName: string): boolean {
+        const lockFilePath = this.getLockFilePath(lockName);
+        return fs.existsSync(lockFilePath);
+    }
+
+    /**
+     * Writes a signal file so another worker can detect completion.
+     * The file persists until the next test run overwrites it.
+     */
+    writeSignal(signalName: string, value: string = "ready"): void {
+        const filePath = path.resolve(this.baseLockDir, `${signalName}.signal`);
+        fs.writeFileSync(filePath, value);
+        console.log(`Signal '${signalName}' written (value: ${value})`);
+    }
+
+    /**
+     * Polls for a signal file written by another worker via writeSignal().
+     * Skips "pending" values — waits until a terminal value (ready/skipped/failed) is written.
+     * Returns the terminal signal value, or throws on timeout.
+     * NOTE: If a `clearSignal()` helper is added in the future, the read loop
+     * inside this method should use a try/catch on `fs.readFileSync` (catching
+     * `ENOENT`) instead of a preceding `fs.existsSync` check, to avoid a TOCTOU
+     * race condition.
+     */
+    async waitForSignal(
+        signalName: string,
+        timeoutMs: number = 300000,
+        intervalMs: number = 5000,
+    ): Promise<string> {
+        const filePath = path.resolve(this.baseLockDir, `${signalName}.signal`);
+        const deadline = Date.now() + timeoutMs;
+        let elapsed = 0;
+
+        while (Date.now() < deadline) {
+            if (fs.existsSync(filePath)) {
+                const value = fs.readFileSync(filePath, 'utf8');
+                if (value !== 'pending') {
+                    console.log(`Signal '${signalName}' received (value: ${value}, waited ~${elapsed}ms)`);
+                    return value;
+                }
+                console.log(`Signal '${signalName}' is pending — waiting for terminal value... (${elapsed}ms elapsed)`);
+            } else {
+                console.log(`Waiting for signal '${signalName}'... (${elapsed}ms elapsed, timeout: ${timeoutMs}ms)`);
+            }
+            await browser.pause(intervalMs);
+            elapsed += intervalMs;
+        }
+
+        throw new Error(`Signal '${signalName}' not received within ${timeoutMs}ms`);
+    }
+
+}
+
+export default new LockService();

package/e2e/utils/antdVersionUtil.ts

@@ -0,0 +1,190 @@
+/**
+ * antd-version detection for the antd v3/v5 -> v6 (new "unified" lib) migration.
+ *
+ * The CRM apps are being moved onto a new antd-v6 based component library. While
+ * the rollout is in progress, the SAME automation must run against BOTH the old
+ * and new UIs, and a revert of the environment from v6 back to v5/v3 must NOT
+ * require reverting any wdio selector. So every migrated locator keeps BOTH
+ * variants (legacy + v6) and we pick the right one at runtime.
+ *
+ * The top nav bar (org switcher) is shared by ALL apps, so its version is the
+ * single source of truth: we detect ONCE per worker (each wdio worker is its own
+ * process) and that one result applies to every app. The detection logic lives in
+ * detect() below — change only that method if the marker ever moves.
+ */
+class AntdVersionUtil {
+    // undefined = not yet detected; true/false = cached result for this worker.
+    private _isV6: boolean | undefined;
+
+    /**
+     * Detect whether the app under test is the new antd-v6 build, and cache it for
+     * the rest of the worker. Apps do not use antd directly — they render through
+     * the internal `cap-ui-library` CSS bundle, of which exactly ONE version (old
+     * or new=v6) is loaded per page. So the loaded `cap-ui-library` stylesheet IS
+     * the app's version. The new (v6) lib ships an `ant-row-legacy` selector that
+     * the old lib never does, so a single same-origin CSS scan is an exact,
+     * render-independent discriminator. The bundle is served from the same pod
+     * (same origin), so `cssRules` is always readable (no CORS).
+     */
+    // Stylesheet whose presence means the internal UI lib (old OR new) has loaded.
+    private static readonly LIB_HREF_MARKER = 'cap-ui-library';
+    // Selector shipped only by the new (v6) lib; absent from the old lib's CSS.
+    private static readonly V6_CSS_MARKER = 'ant-row-legacy';
+
+    async detect(): Promise<boolean> {
+        // Runtime detection is DISABLED. selector() now always emits a combined
+        // v6-first selector, so we no longer need to know the version. This stub
+        // stays callable (wdio.conf's navigateTo hook and a campaigns getter call
+        // it) but does no browser work — no 30s waitUntil, no CSS scan. To restore
+        // detection, un-comment the block below and remove this early return.
+        return false;
+        /* ---- DISABLED detection logic (kept for easy restore) --------------
+        if (this._isV6 !== undefined) return this._isV6;
+        try {
+            // Wait until the page's CSS has loaded enough to decide the version.
+            // Some apps serve the internal UI-lib stylesheet under its own name
+            // (href contains `cap-ui-library`); others (e.g. badges) bundle it into
+            // hashed webpack chunks like `524.<hash>.css` where the href carries no
+            // recognizable marker. So we cannot gate solely on the href. The probe
+            // below succeeds as soon as we can DECIDE the version:
+            //  - the lib stylesheet is present by href (fast path, unchanged), OR
+            //  - the v6-only selector is already readable in any same-origin sheet
+            //    (definitive v6 for chunked builds), OR
+            //  - the document has fully loaded and at least one stylesheet is
+            //    readable (legacy chunked build — no v6 marker will ever appear).
+            await browser.waitUntil(
+                async () =>
+                    browser.execute(
+                        (hrefMarker: string, cssMarker: string) => {
+                            const sheets = Array.from(document.styleSheets);
+                            if (
+                                sheets.some((s) =>
+                                    (s.href || '').includes(hrefMarker),
+                                )
+                            )
+                                return true;
+                            let readableSheet = false;
+                            for (const sheet of sheets) {
+                                let rules: CSSRuleList | null;
+                                try {
+                                    rules = sheet.cssRules;
+                                } catch {
+                                    continue;
+                                }
+                                if (!rules) continue;
+                                readableSheet = true;
+                                for (const rule of Array.from(rules)) {
+                                    const sel = (rule as CSSStyleRule)
+                                        .selectorText;
+                                    if (sel && sel.includes(cssMarker))
+                                        return true;
+                                }
+                            }
+                            return (
+                                document.readyState === 'complete' &&
+                                readableSheet
+                            );
+                        },
+                        AntdVersionUtil.LIB_HREF_MARKER,
+                        AntdVersionUtil.V6_CSS_MARKER,
+                    ),
+                {
+                    timeout: 30000,
+                    interval: 500,
+                    timeoutMsg:
+                        'stylesheets did not load for antd-version detection',
+                },
+            );
+            // Scan same-origin stylesheets for the v6-only selector. Returns on the
+            // first match, so v6 short-circuits; only legacy pages scan fully.
+            this._isV6 = await browser.execute((cssMarker: string) => {
+                for (const sheet of Array.from(document.styleSheets)) {
+                    let rules: CSSRuleList | null;
+                    try {
+                        rules = sheet.cssRules;
+                    } catch {
+                        continue; // cross-origin sheet, not readable — skip
+                    }
+                    if (!rules) continue;
+                    for (const rule of Array.from(rules)) {
+                        const sel = (rule as CSSStyleRule).selectorText;
+                        if (sel && sel.includes(cssMarker)) return true;
+                    }
+                }
+                return false;
+            }, AntdVersionUtil.V6_CSS_MARKER);
+        } catch (err) {
+            console.log(`[antd-version] detection failed, assuming legacy: ${err}`);
+            this._isV6 = false;
+        }
+        console.log(
+            `[antd-version] app detected as ${this._isV6 ? 'antd v6 (new unified lib)' : 'legacy (antd v3/v5)'}`,
+        );
+        return this._isV6;
+        --------------------------------------------------------------------- */
+    }
+
+    /**
+     * Navigation hook (wired into a global `navigateTo` override in wdio.conf).
+     * The antd version is a property of the PAGE that is loaded, not of the worker
+     * or of an app — the same app can be flipped between legacy and v6 part-way
+     * through a run, so caching the version for the worker's lifetime goes stale.
+     * Instead we re-detect on every navigation: clear the cache, then detect afresh
+     * against the page that just loaded. Every navigateTo target carries the shared
+     * top nav (app pages and the home/org/member-care shells all render the org
+     * switcher), so one of the detection markers is always present and the probe
+     * resolves quickly rather than waiting out the timeout.
+     */
+    async onNavigate(): Promise<void> {
+        // No-op while detection is disabled. selector() emits both variants, so
+        // there is nothing to re-detect on navigation. Restore the two lines below
+        // if runtime detection is re-enabled in detect().
+        // this.reset();
+        // await this.detect();
+    }
+
+    /**
+     * Version flag for the FEW call sites that branch on the version directly
+     * (different interaction model, not just a different locator) rather than
+     * using selector()/element() pairs. Runtime detection is disabled and the
+     * environment under test is the new antd-v6 build, so this returns true so
+     * those branches take the v6 path. If the env is reverted to legacy, flip
+     * this back (or restore detection in detect() and return this._isV6).
+     */
+    get isV6(): boolean | undefined {
+        return true;
+    }
+
+    /**
+     * Build one combined selector that matches EITHER the v6 or the legacy
+     * variant, with the v6 variant placed FIRST. Runtime version detection is
+     * disabled (see the commented-out detect()/onNavigate() below) — instead of
+     * picking one variant we always emit both, so the same locator works on a v6
+     * page and on a legacy (reverted) page with no detection, no 30s waitUntil,
+     * and no per-navigation CSS scan.
+     *
+     * Every call site keeps its two selector STRINGS (legacy, v6) so a later
+     * cleanup is trivial: drop the legacy arg and this join.
+     *
+     * The two variants of a pair are always the same query language (verified:
+     * no mixed XPath/CSS pairs), so we join XPath with the `|` union and CSS with
+     * the `,` list. A page is either v6 or legacy, so only one side ever matches;
+     * ordering v6 first just expresses the preference.
+     */
+    selector(legacy: string, v6: string): string {
+        const isXPath = (s: string) => /^\s*(\/|\.\/|\.\.\/|\()/.test(s);
+        return isXPath(v6) ? `${v6} | ${legacy}` : `${v6}, ${legacy}`;
+    }
+
+    /** Resolve a legacy/v6 selector pair to a live element using the picked one. */
+    element(legacy: string, v6: string) {
+        return $(this.selector(legacy, v6));
+    }
+
+    /** Test hook: clear the cached detection (not used in normal runs). */
+    reset(): void {
+        this._isV6 = undefined;
+    }
+}
+
+export default new AntdVersionUtil();