@camunda/e2e-test-suite 0.0.943 → 0.0.945

package/dist/pages/8.10/OperateProcessInstancePage.js

@@ -1,15 +1,156 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OperateProcessInstancePage = void 0;
+exports.watchOperateInstanceUrl = exports.OperateProcessInstancePage = void 0;
 const test_1 = require("@playwright/test");
 const sleep_1 = require("../../utils/sleep");
+// Operate bounces a deep link to an instance it has not imported yet: when
+// `GET /v2/process-instances/{key}` answers 404 it shows an
+// "Instance <id> could not be found" notification and replaces the URL with
+// the processes list (see `useEffect` on `error?.response?.status === 404` in
+// camunda/camunda `operate/client/src/App/ProcessInstance/index.tsx`). From
+// that moment on the tab sits on `/processes?active=true&incidents=true`, so
+// every `page.reload()` in a retry loop reloads the LIST, and neither the
+// instance header nor the "Instance History" panel can ever appear no matter
+// how long we keep retrying. Remember the deep-link URL and re-navigate to it
+// between attempts so each retry re-asks for the instance.
+const INSTANCE_PATH = /\/processes\/[^/]+/;
+// URLs the tab shows while the cluster SSO hand-off is still in flight. The
+// Operate popup is opened without a cluster session, so its first navigation
+// goes through that hand-off and `/<cluster>/sso-callback?...&code=...&state=...`
+// commits before the app itself does.
+//
+// The callback is only the LAST leg. Before it the tab visits the IdP
+// (`weblogin.<domain>/authorize?...&state=...`, plus its `/u/login/...` forms
+// when the session has to be re-established) and the cluster proxy's own
+// `/<cluster>/sso` entry point. Recognising only the callback classified every
+// one of those legs as "Operate bounced us to the processes list", so the
+// bounce recovery re-opened the deep link ~5s into a hand-off that was still
+// at the IdP -- aborting an authorization request that was about to come back
+// and leaving the cluster proxy holding a `state`/`code` pair that no longer
+// matches the tab. Every subsequent round did the same, which is how a wait
+// ended its whole 480000ms budget parked on
+// `/<cluster>/sso-callback?uuid=...&code=...&state=...` (27 of the 29 recorded
+// timeouts of this wait).
+const AUTH_TRANSIT_PATH = /\/(sso|sso-callback|login|login-callback)\/?$/;
+const AUTH_TRANSIT_HOST = /^(weblogin|login|auth)\./;
+const IDP_FORM_PATH = /^\/(u|authorize|oauth)(\/|$)/;
+// True while the tab is mid-authentication rather than on an Operate page.
+// `waitForInstanceLocator` must not re-navigate over a hand-off that is still
+// in flight: re-opening the deep link aborts the code-for-session exchange and
+// starts a fresh one, so a hand-off that needs longer than the retry interval
+// could never finish and the loop would re-trigger it until the whole budget is
+// gone. It therefore gives each hand-off a grace window to settle — but only a
+// bounded one, because an exchange the cluster has rejected never completes at
+// all and waiting it out spends the entire budget on a tab that was never asked
+// about the instance ("instance header not rendered,
+// url=<cluster>/sso-callback?uuid=...&code=...&state=..." after 480000ms with
+// the deep link captured).
+function isAuthTransit(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        if (AUTH_TRANSIT_HOST.test(url.hostname) ||
+            IDP_FORM_PATH.test(url.pathname) ||
+            AUTH_TRANSIT_PATH.test(url.pathname)) {
+            return true;
+        }
+        // The OAuth `state` parameter is carried by every leg of the hand-off and
+        // by nothing Operate itself serves (neither the instance deep link nor the
+        // `/processes?active=true&incidents=true` list it bounces to has one), so a
+        // URL carrying it is still in transit even when its path is not one of the
+        // shapes above. Requiring `code` as well missed the whole outbound half of
+        // the hand-off, where only `state` is present yet.
+        return url.searchParams.has('state');
+    }
+    catch {
+        // Not a parsable URL yet (e.g. the popup's initial about:blank).
+        return false;
+    }
+}
+// The cluster proxy appends a bare `?continue` marker to a deep link it served
+// WITHOUT a session. A tab showing it is not waiting on the Zeebe -> Operate
+// import at all — it is waiting on a hand-off that never happened, so plain
+// re-opens of the same URL can only bring the same marker back. That is what
+// reported "instance header not rendered,
+// url=<cluster>/operate/processes/<key>?continue" after a full 480000ms budget.
+function isSessionlessDeepLink(rawUrl) {
+    try {
+        return new URL(rawUrl).searchParams.has('continue');
+    }
+    catch {
+        // Not a parsable URL yet (e.g. the popup's initial about:blank).
+        return false;
+    }
+}
+// Returns the instance deep link out of a document request's redirect chain, or
+// undefined when no hop of the chain points at an instance. Oldest hop first:
+// prefer the URL the tab was opened with over whatever a redirect replaced it
+// by.
+function instanceUrlFromRequest(request) {
+    const chain = [];
+    for (let hop = request; hop !== null;) {
+        chain.push(hop.url());
+        hop = hop.redirectedFrom();
+    }
+    chain.reverse();
+    for (const url of chain) {
+        try {
+            if (INSTANCE_PATH.test(new URL(url).pathname)) {
+                return url;
+            }
+        }
+        catch {
+            // Not a parsable URL yet (e.g. the popup's initial about:blank).
+        }
+    }
+    return undefined;
+}
+// Starts latching Operate instance deep links across the whole browser context.
+// Call this BEFORE the action that opens the Operate popup, and pass the result
+// to `rememberInstanceUrl`.
+//
+// The popup's own events are always too late for its FIRST document request:
+// Playwright emits `popup` only "when the network request to the initial url is
+// done and its response has started loading", and its docs say outright that to
+// listen to that request you must use `browserContext.on('request')` instead of
+// the equivalent method on the Page. `rememberInstanceUrl` attaches its
+// listeners after `waitForEvent('popup')` has resolved, so the deep-link request
+// has already been and gone by then.
+//
+// That only matters because Modeler opens Operate in a fresh tab: while that tab
+// still has no cluster session the auth redirect chain answers the deep link and
+// drops its path, so the only navigation that ever COMMITS is the Operate app
+// root and `framenavigated`/`waitForURL` never see an instance URL either. The
+// deep link is then lost altogether ("instance deep link never captured"), which
+// silently disables the recovery in `waitForInstanceLocator`: `hasBouncedToList`
+// can no longer tell we are off the instance page and `reload` degrades to
+// reloading the app root, where the instance header can never render no matter
+// how long we poll. That is what spent the whole budget as "active/completed
+// icon in Operate timed out after 480000ms (instance header not rendered,
+// url=<cluster>/operate, instance deep link never captured)".
+//
+// The context-level `request` event is already live when the popup is created,
+// so it observes the deep link at its origin. By the time the loop retries, the
+// tab is authenticated and re-opening that URL lands on the instance page.
+function watchOperateInstanceUrl(context) {
+    let instanceUrl;
+    context.on('request', (request) => {
+        if (instanceUrl !== undefined || request.resourceType() !== 'document') {
+            return;
+        }
+        instanceUrl = instanceUrlFromRequest(request);
+    });
+    return () => instanceUrl;
+}
+exports.watchOperateInstanceUrl = watchOperateInstanceUrl;
 class OperateProcessInstancePage {
     page;
+    instanceUrl;
     diagram;
     completedIcon;
     diagramSpinner;
     activeIcon;
     incidentIcon;
+    incidentsBanner;
     userTaskOpenTasklistLink;
     taskDetailsPopOver;
     connectorResultVariableName;
@@ -30,6 +171,9 @@ class OperateProcessInstancePage {
         this.incidentIcon = page
             .getByTestId('instance-header')
             .getByTestId('INCIDENT-icon');
+        // Same test id Operate's own e2e suite uses for the incident bar
+        // (camunda/camunda `operate/client/e2e-playwright/pages/ProcessInstance.ts`).
+        this.incidentsBanner = page.getByTestId('incidents-banner');
         this.userTaskOpenTasklistLink = page.getByRole('link', {
             name: 'Open Tasklist',
         });
@@ -45,33 +189,591 @@ class OperateProcessInstancePage {
     async connectorResultVariableValue(variableName) {
         return await this.page.getByTestId(variableName).locator('td').last();
     }
-    async closePopOverIfVisible() {
-        // The instance-detail page is opened via a deep link right after the
-        // instance is started, so on freshly-provisioned SaaS clusters the
-        // instance is sometimes not yet imported when the popup lands and the
-        // page renders empty. A single fixed wait never recovers from that;
-        // reload between attempts so the "Instance History" panel appears once
-        // the import catches up.
-        const maxRetries = 5;
-        for (let attempt = 0; attempt < maxRetries; attempt++) {
+    // Records the instance deep link so the waits below can re-open it after
+    // Operate's 404 bounce to the processes list (see the note above the class).
+    // Called right after the Operate popup opens, before the query can fail.
+    //
+    // `waitForURL` alone loses this race: the bounce is a client-side navigation
+    // fired as soon as the 404 lands, so on a lagging import the deep link can be
+    // gone before the wait is evaluated. `waitForURL` then sits out its whole
+    // budget on the list page and leaves `instanceUrl` unset -- which silently
+    // disables the recovery: `hasBouncedToList` can no longer tell we bounced and
+    // `reload` degrades to reloading the LIST page, so every retry afterwards
+    // polls a page that can never render the instance header. That is what turns
+    // a slow import into "failed after N attempts". Latch the first
+    // instance-shaped URL from `framenavigated` instead, which fires on the deep
+    // link's own commit and therefore cannot be beaten by the bounce.
+    //
+    // `watchedUrl` is the getter returned by `watchOperateInstanceUrl`, primed on
+    // the browser context before the popup was opened. It is the ONLY observer
+    // that is already live when the popup issues its first document request, so
+    // for a Modeler-opened Operate tab it is the source that actually works; the
+    // listeners below stay as the in-tab path (a navigation that commits later,
+    // or a tab that is already on the instance page).
+    async rememberInstanceUrl(timeout = 60000, watchedUrl) {
+        const latch = (url) => {
+            if (this.instanceUrl !== undefined) {
+                return;
+            }
             try {
-                await (0, test_1.expect)(this.page.getByText('Instance History').first()).toBeVisible({ timeout: 60000 });
+                if (INSTANCE_PATH.test(new URL(url).pathname)) {
+                    this.instanceUrl = url;
+                }
+            }
+            catch {
+                // Not a parsable URL yet (e.g. the popup's initial about:blank).
+            }
+        };
+        // Latch what the context-level watcher already saw. This runs FIRST because
+        // for a Modeler-opened tab it is the only source that can have the deep
+        // link: `framenavigated` only ever reports a *committed* document, and the
+        // auth redirect chain drops the deep-link path before it commits (see
+        // `watchOperateInstanceUrl`), so neither the listeners below nor
+        // `waitForURL` ever see an instance URL in that tab.
+        const latchWatched = () => {
+            const seen = watchedUrl?.();
+            if (seen !== undefined) {
+                latch(seen);
+            }
+            return this.instanceUrl !== undefined;
+        };
+        if (latchWatched()) {
+            return;
+        }
+        // In-tab sources, for a navigation that commits later or a tab that is
+        // already on the instance page (e.g. after clicking through the processes
+        // list rather than opening a popup).
+        this.page.on('request', (request) => {
+            if (request.resourceType() !== 'document' ||
+                request.frame() !== this.page.mainFrame()) {
+                return;
+            }
+            const fromRequest = instanceUrlFromRequest(request);
+            if (fromRequest !== undefined) {
+                latch(fromRequest);
+            }
+        });
+        this.page.on('framenavigated', (frame) => {
+            if (frame === this.page.mainFrame()) {
+                latch(frame.url());
+            }
+        });
+        latch(this.page.url());
+        if (this.instanceUrl !== undefined) {
+            return;
+        }
+        try {
+            await this.page.waitForURL((url) => INSTANCE_PATH.test(url.pathname), {
+                timeout,
+            });
+            latch(this.page.url());
+        }
+        catch (error) {
+            if (!latchWatched()) {
+                // The tab never showed an instance URL (already bounced, or still on
+                // the auth redirect). Retries then behave as before rather than
+                // failing here.
+                console.warn(`Could not capture the Operate instance URL: ${error}`);
+            }
+        }
+    }
+    // True once Operate has replaced the deep link with the processes list.
+    // A tab that is still authenticating is NOT a bounce: it is on its way to the
+    // deep link, and re-opening it would restart the hand-off (see
+    // `isAuthTransit`).
+    hasBouncedToList() {
+        if (this.instanceUrl === undefined) {
+            return false;
+        }
+        if (isAuthTransit(this.page.url())) {
+            return false;
+        }
+        return !INSTANCE_PATH.test(new URL(this.page.url()).pathname);
+    }
+    // Lets the cluster SSO hand-off finish instead of re-navigating over it.
+    // Returns when the tab has left the auth URLs or when this slice runs out —
+    // the caller loops either way, so a hand-off that stalls for the whole
+    // budget still surfaces through `describeRenderedState`.
+    async waitForAuthToSettle(timeout) {
+        if (timeout <= 0) {
+            return;
+        }
+        try {
+            await this.page.waitForURL((url) => !isAuthTransit(url.toString()), {
+                timeout,
+            });
+        }
+        catch {
+            // Still authenticating — handled by the caller's loop.
+        }
+    }
+    // True when the awaited locator is one of the mutually exclusive instance
+    // state icons, which an incident makes unreachable. Everything else on the
+    // instance page (the "Instance History" panel, the variables list) renders
+    // regardless of the instance state, so those waits must NOT be cut short.
+    // Identity comparison against the locators this class exposes: a caller that
+    // builds its own equivalent locator simply keeps the plain timeout behaviour.
+    isStateIconWait(locator) {
+        return locator === this.activeIcon || locator === this.completedIcon;
+    }
+    // Reports the incident bar's text, so a terminal incident names itself
+    // instead of being reported as an import that never caught up.
+    async describeIncident() {
+        const banner = await this.incidentsBanner
+            .textContent({ timeout: 5000 })
+            .catch(() => null);
+        return banner === null || banner.trim() === ''
+            ? 'the instance header shows INCIDENT'
+            : `the instance raised an incident: ${banner.trim()}`;
+    }
+    // Reports what the instance-detail page actually rendered, so a timeout below
+    // distinguishes "the import never caught up" (no header at all, or the tab is
+    // parked on the processes list) from "the instance reached a different state"
+    // (e.g. the header shows INCIDENT while we wait for ACTIVE) -- the plain
+    // "element(s) not found" of the underlying assertion cannot tell those apart.
+    async describeRenderedState() {
+        const header = this.page.getByTestId('instance-header');
+        if (!(await header.isVisible().catch(() => false))) {
+            // Report whether the deep link was captured: without it the retries could
+            // only reload whatever page the tab was left on, which is a different
+            // failure from an import that never caught up.
+            const link = this.instanceUrl === undefined
+                ? 'instance deep link never captured'
+                : `instance deep link=${this.instanceUrl}`;
+            return `instance header not rendered, url=${this.page.url()}, ${link}`;
+        }
+        const states = ['ACTIVE', 'COMPLETED', 'INCIDENT', 'CANCELED'];
+        const rendered = [];
+        for (const state of states) {
+            const visible = await header
+                .getByTestId(`${state}-icon`)
+                .isVisible()
+                .catch(() => false);
+            if (visible) {
+                rendered.push(state);
+            }
+        }
+        return rendered.length > 0
+            ? `instance header shows ${rendered.join(', ')}`
+            : 'instance header rendered without a state icon';
+    }
+    // Waits for a locator on the instance-detail page, re-opening the deep link
+    // whenever Operate has bounced the tab to the processes list. Waiting a full
+    // per-attempt budget on the bounced list page can never succeed, so the time
+    // is spent re-asking Operate for the instance instead: the instance header
+    // and the "Instance History" panel only render once the Zeebe -> Operate
+    // import has caught up.
+    //
+    // The locator is checked in short slices so the bounce is noticed within
+    // seconds. Checking it once per `pollTimeout` meant the bounce -- which lands
+    // about a second after each re-navigation while the import lags -- was only
+    // seen at the END of that wait, so ~29 of every 30 seconds were spent idling
+    // on the list page and the whole 8 minute budget bought only ~16 re-asks.
+    // That is what ran out as "active/completed icon in Operate timed out after
+    // 480000ms" on a slow import. Same budget, but a bouncing page now re-asks
+    // every few seconds, while a page that stays on the instance keeps the
+    // original one-reload-per-`pollTimeout` cadence.
+    async waitForInstanceLocator(locator, description, totalTimeout = 300000, pollTimeout = 30000) {
+        const deadline = Date.now() + totalTimeout;
+        // Short enough that a bounce costs seconds rather than a full poll window,
+        // long enough not to fill the trace with hundreds of failed assertions.
+        const checkSlice = 5000;
+        // How long the FIRST cluster SSO hand-off is given to complete before it is
+        // treated as stalled. A healthy hand-off commits in a couple of seconds, so
+        // this is generous; it only has to be long enough that a merely slow
+        // exchange is never restarted underneath itself.
+        const authGrace = 60000;
+        // Every hand-off after that gets a much shorter window: once one has
+        // already stalled, the tab has proved this exchange does not just need a
+        // little longer, and repeating the generous wait is what limited the whole
+        // budget to ~7 restarts (60s idle + 5s backoff each).
+        const authRetryGrace = 15000;
+        let lastError;
+        let nextReload = Date.now() + pollTimeout;
+        // When the tab entered its current auth hand-off, or undefined while it is
+        // not on an auth URL.
+        let authTransitSince;
+        // How many hand-offs have already been restarted, and whether the last
+        // restart's navigation actually went through.
+        let authStalls = 0;
+        let authRestartFailed = false;
+        // Consecutive re-opens made while the instance header had not rendered at
+        // all. A tab that came back from a failed hand-off lands on the deep link
+        // itself carrying the cluster proxy's session-less `?continue` marker --
+        // neither an auth URL nor the processes list, so both recoveries above see
+        // nothing wrong and the loop only re-opens the same URL. Every round landed
+        // on the same session-less page, which is what reported "instance header
+        // not rendered, url=<cluster>/operate/processes/<key>?continue" after the
+        // full budget. Once a few re-opens have brought back no header at all, stop
+        // re-asking the cluster directly and re-enter through the Console.
+        let headerlessReopens = 0;
+        while (Date.now() < deadline) {
+            // Don't re-navigate over an in-flight cluster SSO hand-off: doing so
+            // aborts the code-for-session exchange and starts a fresh one, so a
+            // hand-off that needs longer than the retry interval could never finish
+            // (see `isAuthTransit`). But don't wait on it indefinitely either -- an
+            // exchange whose code was rejected never turns into a session, and the
+            // tab then sits on `/<cluster>/sso-callback?...&code=...&state=...`
+            // forever. Waiting that out consumed the ENTIRE budget without ever
+            // re-asking Operate anything, which is what reported "active icon in
+            // Operate timed out after 480000ms (instance header not rendered,
+            // url=<cluster>/sso-callback?uuid=...&code=...&state=...)" with the deep
+            // link captured. So: give each hand-off `authGrace` to settle, then
+            // re-open the deep link to start a genuinely fresh one.
+            if (isAuthTransit(this.page.url())) {
+                if (authTransitSince === undefined) {
+                    authTransitSince = Date.now();
+                }
+                const grace = authStalls === 0 ? authGrace : authRetryGrace;
+                // A restart whose navigation never happened left the tab exactly where
+                // it was, so there is no fresh exchange to wait on: retry the
+                // navigation instead of idling another window on the stalled one.
+                const graceLeft = authRestartFailed
+                    ? 0
+                    : grace - (Date.now() - authTransitSince);
+                if (graceLeft > 0) {
+                    await this.waitForAuthToSettle(Math.min(graceLeft, Math.max(0, deadline - Date.now())));
+                    continue;
+                }
+                // Back off before re-opening so a cluster that is throttling or
+                // rejecting the exchange gets room to recover instead of being hammered
+                // with a tight restart loop. It grows with each stall, because a
+                // hand-off that has failed several times in a row is not going to be
+                // fixed by asking again immediately.
+                const backoff = Math.min(30000, 5000 * 2 ** authStalls);
+                await (0, sleep_1.sleep)(Math.min(backoff, Math.max(0, deadline - Date.now())));
+                // Only a re-navigation that actually happened starts a new hand-off.
+                // `reload` reports a `goto` that aborted against the callback's own
+                // in-flight navigation instead of hiding it, so such a round no longer
+                // buys the untouched tab another full grace window.
+                //
+                // The first restart re-opens the deep link directly, which is enough
+                // for an exchange that was merely slow. Every restart after that goes
+                // through the Console root: a hand-off that has already failed once is
+                // not recovered by re-entering it from its own dead callback page (see
+                // `reenterViaConsole`), which is why ~10 direct restarts in a row still
+                // ended the budget parked on `sso-callback`.
+                authRestartFailed = !(await (authStalls === 0
+                    ? this.reload()
+                    : this.reenterViaConsole(deadline)));
+                authStalls++;
+                if (!authRestartFailed) {
+                    authTransitSince = undefined;
+                }
+                nextReload = Date.now() + pollTimeout;
+                continue;
+            }
+            authTransitSince = undefined;
+            authRestartFailed = false;
+            // The tab has left the callback, so the exchange that was in flight
+            // COMPLETED. `authStalls` shortens the grace window because "this
+            // exchange has proved it does not just need a little longer" -- that is
+            // a statement about one exchange, so it must count CONSECUTIVE stalls.
+            // Latching it for the whole wait meant that after a single early stall
+            // every later hand-off -- the ones the ordinary bounce recovery and the
+            // periodic re-opens below start, and the fresh one a Console re-entry
+            // mints -- was capped at `authRetryGrace` and torn down 15s in, then
+            // charged a longer backoff and another full Console re-entry. The loop
+            // thrashed instead of converging, which is the other half of how a wait
+            // ended its budget parked on
+            // `/<cluster>/sso-callback?...&code=...&state=...`.
+            authStalls = 0;
+            if (this.hasBouncedToList()) {
+                // Back off before re-opening so a still-importing instance is not
+                // hammered with a tight bounce/re-open loop.
+                await (0, sleep_1.sleep)(Math.min(5000, Math.max(0, deadline - Date.now())));
+                await this.reload();
+                nextReload = Date.now() + pollTimeout;
+                continue;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
                 break;
             }
+            try {
+                await (0, test_1.expect)(locator).toBeVisible({
+                    timeout: Math.min(checkSlice, remaining),
+                });
+                return;
+            }
             catch (error) {
-                if (attempt === maxRetries - 1) {
-                    throw error;
+                lastError = error;
+            }
+            // An incident ends this wait: the header renders exactly one state icon,
+            // so neither ACTIVE nor COMPLETED can appear while the instance sits in
+            // an incident, and nothing in these flows resolves one. Waiting out the
+            // rest of the budget only delays the failure by minutes and then reports
+            // it as an import lag ("timed out after 480000ms (instance header shows
+            // INCIDENT)"), which hides the cause. Confirm it once after a short pause
+            // first, so a header rendered from partially imported records is not
+            // mistaken for a settled incident.
+            if (this.isStateIconWait(locator) &&
+                (await this.incidentIcon.isVisible().catch(() => false))) {
+                await (0, sleep_1.sleep)(Math.min(10000, Math.max(0, deadline - Date.now())));
+                if (await this.incidentIcon.isVisible().catch(() => false)) {
+                    throw new Error(`Assertion of ${description} in Operate cannot succeed: ` +
+                        `${await this.describeIncident()}. The awaited state is no ` +
+                        `longer reachable, so failing now instead of waiting out the ` +
+                        `remaining budget of ${totalTimeout}ms.`);
                 }
-                await this.page.reload();
-                await (0, sleep_1.sleep)(5000);
+            }
+            if (Date.now() >= nextReload && Date.now() < deadline) {
+                // A rendered header means the app booted and we are only waiting on the
+                // instance state, so keep re-opening the deep link directly. No header
+                // at all points at the app never having booted -- escalate to the
+                // Console re-entry once a couple of plain re-opens have not changed it.
+                const headerRendered = await this.page
+                    .getByTestId('instance-header')
+                    .isVisible()
+                    .catch(() => false);
+                headerlessReopens = headerRendered ? 0 : headerlessReopens + 1;
+                // A session-less deep link escalates straight away: the `?continue`
+                // marker is proof the cluster hand-off never happened, so the two
+                // plain re-opens the counter would otherwise spend first can only
+                // bring the same marker back (see `isSessionlessDeepLink`).
+                const sessionless = !headerRendered && isSessionlessDeepLink(this.page.url());
+                if (headerlessReopens > 2 || sessionless) {
+                    await this.reenterViaConsole(deadline);
+                }
+                else {
+                    await this.reload();
+                }
+                nextReload = Date.now() + pollTimeout;
             }
         }
+        throw new Error(`Assertion of ${description} in Operate timed out after ` +
+            `${totalTimeout}ms (${await this.describeRenderedState()}): ` +
+            `${lastError}`);
+    }
+    // Dismisses Operate's "what's new" popup without re-gating on the import.
+    // Use this when the caller has already waited for something on the instance
+    // page (the instance header, the COMPLETED icon): that wait is a strictly
+    // stronger gate than "Instance History" is visible, so repeating it here
+    // just spends a second full budget proving what is already known -- and on
+    // a lagging import it is the duplicate gate, not the real assertion, that
+    // reports the failure. `closePopOverIfVisible` keeps the combined behaviour
+    // for callers that have not waited for the instance page yet.
+    async dismissWhatsNewIfVisible() {
         if (await this.whatsNewPopUp.isVisible()) {
             await this.gotItButton.click();
         }
     }
+    async closePopOverIfVisible() {
+        // The instance-detail page is opened via a deep link right after the
+        // instance is started, so on a busy SaaS cluster the instance is often not
+        // imported yet when the popup lands and Operate bounces the tab to the
+        // processes list. Poll the deep link rather than the bounced page; the
+        // 8 minute budget matches the previous 8 x 60s attempts.
+        await this.waitForInstanceLocator(this.page.getByText('Instance History').first(), 'Instance History panel', 480000);
+        if (await this.whatsNewPopUp.isVisible()) {
+            await this.gotItButton.click();
+        }
+    }
+    // The host that serves the instance deep link, i.e. the origin whose cluster
+    // session the Operate app needs. Undefined only before any cluster URL has
+    // been seen at all.
+    clusterHost() {
+        for (const raw of [this.instanceUrl, this.page.url()]) {
+            if (raw === undefined) {
+                continue;
+            }
+            try {
+                return new URL(raw).hostname;
+            }
+            catch {
+                // Not a parsable URL yet (e.g. the popup's initial about:blank).
+            }
+        }
+        return undefined;
+    }
+    // Re-opens the instance by way of the Console's apps menu instead of going
+    // straight back at the cluster deep link.
+    //
+    // Once a tab's cluster SSO hand-off has actually failed, re-opening the deep
+    // link cannot recover it: that starts the exchange again from the dead
+    // callback page, whose `code` is single use, so the tab just lands back on
+    // `/<cluster>/sso-callback?...&code=...&state=...` (or on the deep link
+    // itself carrying the proxy's session-less `?continue` marker) and the
+    // Operate app never boots. Repeating it only buys more identical rounds --
+    // that is what spent whole 480000ms budgets as "instance header not
+    // rendered" with the deep link captured.
+    //
+    // The Console is the one origin whose session is known good in these flows
+    // (the test logged in there), so letting IT drive a fresh hand-off -- by
+    // clicking Operate in its apps menu -- hands the cluster a real session
+    // rather than chaining off the failed callback. Merely LOADING the Console
+    // root is not enough: that establishes a Console session only, and the
+    // deep-link re-open then puts the cluster proxy back in charge of the very
+    // exchange that is wedged (see the click below). This is the same recovery
+    // `AppsPage.openOperateWithRetry` / `openModelerWithRetry` already use for
+    // the identical Operate and Modeler `login-callback` stalls.
+    async reenterViaConsole(deadline) {
+        // Clamp every wait below to the time the caller's budget actually has
+        // left, so one escalation can never overrun the loop's own deadline (and
+        // through it the flow's reserve for the afterEach screenshot). Never 0 —
+        // Playwright reads that as "no timeout".
+        const left = (want) => deadline === undefined
+            ? want
+            : Math.max(1000, Math.min(want, deadline - Date.now()));
+        let booted = false;
+        try {
+            // Drop the CLUSTER origin's own cookies before re-entering. A hand-off
+            // that parked on `/<cluster>/sso-callback?...&code=...&state=...` left
+            // the cluster proxy holding that exchange's state/session cookie, and
+            // every restart re-sends it -- so the proxy keeps validating the fresh
+            // `code` against the dead flow and bounces the tab straight back to the
+            // callback. Neither recovery above touches those cookies (re-opening the
+            // deep link sends them again, and the Console root is a different
+            // origin), which is why ~8 restarts in a row all ended on that same URL
+            // and whole 480000ms budgets went by with the Operate app never booting.
+            // Scoped to the cluster host, so the Console and weblogin IdP sessions
+            // the test logged in with are untouched and no re-login is needed -- the
+            // same recovery `AppsPage.clickModeler` already uses for a wedged
+            // Modeler hand-off.
+            //
+            // `clearCookies` matches its `domain` filter by exact string equality,
+            // and Chromium reports a cookie that was set with an explicit `Domain=`
+            // attribute with a LEADING DOT. Filtering on the bare host therefore
+            // re-added every `.<host>` cookie -- the proxy's own session/CSRF pair,
+            // i.e. precisely the dead exchange's state this clear exists to drop --
+            // so each restart re-sent them and the proxy kept validating the fresh
+            // `code` against the wedged flow. Match both forms, still scoped to the
+            // cluster host itself so the Console and weblogin IdP sessions on the
+            // parent domain stay untouched and no re-login is needed.
+            const host = this.clusterHost();
+            if (host !== undefined) {
+                const escaped = host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                await this.page
+                    .context()
+                    .clearCookies({ domain: new RegExp(`^\\.?${escaped}$`) });
+            }
+            await this.page.goto('/', { waitUntil: 'domcontentloaded' });
+            // Wait for the Console APP, not just for its shell document.
+            // `domcontentloaded` resolves as soon as the root HTML is parsed, which
+            // is well before the Console has booted and run its own auth/token
+            // refresh. Gate on the app switcher -- the same marker the flows use to
+            // know the Console is ready -- so the re-entry below starts from a
+            // Console session that actually exists.
+            const appSwitcher = this.page
+                .getByLabel('Camunda components')
+                .or(this.page.getByLabel('Camunda apps'))
+                .or(this.page.getByLabel('App Switcher'))
+                .first();
+            await appSwitcher.waitFor({ state: 'visible', timeout: left(30000) });
+            // Now re-enter the CLUSTER through the apps menu, instead of going
+            // straight back at the deep link. Reaching the Console root only
+            // establishes a CONSOLE session; the CLUSTER session is minted by the
+            // hand-off, and re-requesting the deep link makes the cluster PROXY
+            // drive that hand-off -- which is precisely the exchange that is wedged
+            // (it is what emits `/<cluster>/sso-callback?...&code=...&state=...` and
+            // the session-less `?continue` marker). Without this click every
+            // "Console re-entry" degenerated into just another plain deep-link
+            // re-open, which is why ~8 of them in a row all ended on that same URL
+            // and whole 480000ms budgets went by with Operate never booting.
+            // Clicking Operate here makes the CONSOLE mint a fresh authorization
+            // request off its own known-good session -- the same hand-off
+            // `AppsPage.openOperateWithRetry` uses successfully elsewhere in these
+            // flows. The locators mirror `AppsPage.clickOperate`; they are inlined
+            // rather than imported because `AppsPage` -> `UtilitiesPage` imports
+            // this module back.
+            // Give the menu clicks the same tolerance `AppsPage` uses for the very
+            // same hand-off (30s), not the config-wide 10s `actionTimeout`: a Console
+            // that is still settling made this single click lapse at 10s and threw
+            // the WHOLE re-entry away -- 50 to 73 of the recorded re-entry failures
+            // in a nightly are exactly `locator.click: Timeout 10000ms exceeded`.
+            // Still clamped to the caller's budget through `left`.
+            await appSwitcher.click({ timeout: left(30000) });
+            const operateLink = this.page.getByRole('link', {
+                name: 'Operate',
+                exact: true,
+            });
+            const operateGroup = this.page.getByRole('button', {
+                name: 'Operate',
+                exact: true,
+            });
+            // The apps panel populates asynchronously after the switcher click, and
+            // `isVisible()` IGNORES its `timeout` option -- it reports the state as
+            // of right now and returns (see the `@deprecated This option is ignored`
+            // note on `locator.isVisible` in playwright-core's types). Probing
+            // immediately after the click therefore almost always answered "no
+            // link", fell through to the multi-cluster branch, and threw when that
+            // button was not rendered yet either -- so the whole re-entry was
+            // swallowed by the catch below and degenerated into exactly the plain
+            // deep-link re-open it exists to replace. That is why every "Console
+            // re-entry" left the tab back on
+            // `/<cluster>/sso-callback?...&code=...&state=...`. Wait for the panel
+            // to actually render first, the same way `AppsPage.clickTasklist` does.
+            await operateLink
+                .or(operateGroup)
+                .first()
+                .waitFor({ state: 'visible', timeout: left(30000) });
+            if (await operateLink.isVisible()) {
+                // Single cluster.
+                await operateLink.click({ timeout: left(30000) });
+            }
+            else {
+                // Multiple clusters: expand the Operate group, then pick the cluster
+                // serving this instance.
+                await operateGroup.click({ timeout: left(30000) });
+                await this.page
+                    .getByRole('listitem')
+                    .filter({ hasText: 'Operate' })
+                    .getByRole('link')
+                    .first()
+                    .click({ timeout: left(30000) });
+            }
+            // Gate on Operate itself, not on the Console shell: only a booted
+            // Operate proves the cluster session now exists, which is exactly what
+            // the deep-link re-open below needs. Returning any earlier would hand
+            // the cluster the same missing session as the round before it.
+            await this.page
+                .getByRole('link', { name: 'Camunda logo Operate' })
+                .waitFor({ state: 'visible', timeout: left(60000) });
+            booted = true;
+        }
+        catch (error) {
+            // Left to the caller's loop, exactly as in `reload` below: the re-open
+            // that follows is what matters, and it is retried anyway.
+            console.warn(`Could not re-enter through the Console root: ${error}`);
+        }
+        // Report whether a cluster session was actually minted, not merely whether
+        // the deep-link re-open navigated. Only a re-entry that booted Operate has
+        // started a NEW hand-off; returning `reload()`'s result said "restarted"
+        // for every round whose re-entry had timed out, so the caller granted the
+        // untouched, still-wedged callback another full grace window (and a longer
+        // backoff) before trying again -- roughly a third of the budget spent
+        // idling on an exchange nothing had restarted.
+        const reopened = await this.reload();
+        return booted && reopened;
+    }
+    // Returns whether the re-navigation actually went through, so the auth
+    // recovery in `waitForInstanceLocator` can tell "a new hand-off was started"
+    // apart from "the tab never moved".
     async reload() {
-        await this.page.reload();
+        // A failed re-navigation is logged and left to the caller's loop rather
+        // than thrown: this runs as the recovery step of `waitForInstanceLocator`,
+        // and a navigation that races the page's own in-flight one fails with
+        // `net::ERR_ABORTED; maybe frame was detached?` (a DNS blip with
+        // `net::ERR_NAME_NOT_RESOLVED`). Those used to escape the retry loop and
+        // fail the test outright, even though the very next poll would have
+        // re-opened the deep link anyway. A page that genuinely never comes back
+        // still fails, through the loop's own timeout and rendered-state report.
+        try {
+            // Always re-open the remembered instance deep link: once Operate has
+            // replaced the URL with the processes list, reloading that list can never
+            // bring the instance back (see the class note).
+            if (this.instanceUrl !== undefined) {
+                await this.page.goto(this.instanceUrl, { waitUntil: 'domcontentloaded' });
+                return true;
+            }
+            await this.page.reload();
+            await this.page.waitForLoadState('domcontentloaded');
+            return true;
+        }
+        catch (error) {
+            console.warn(`Could not re-open the Operate instance page: ${error}`);
+            return false;
+        }
     }
     async assertProcessCompleteStatusWithRetry(timeout = 60000, maxRetries = 10) {
         for (let attempt = 0; attempt < maxRetries; attempt++) {