doc-detective 4.22.0 → 4.24.0

package/dist/core/tests.js

@@ -13,7 +13,7 @@ import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/brows
 // Single source of truth for browser/driver-requiring step keys.
 import { BROWSER_STEP_KEYS as driverActions } from "../runtime/browserStepKeys.js";
 import os from "node:os";
-import { log, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, } from "./utils.js";
+import { log, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, } from "./utils.js";
 import axios from "axios";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
@@ -21,6 +21,7 @@ import { findElement } from "./tests/findElement.js";
 import { runShell } from "./tests/runShell.js";
 import { checkLink } from "./tests/checkLink.js";
 import { typeKeys } from "./tests/typeKeys.js";
+import { swipeSurface } from "./tests/swipe.js";
 import { wait } from "./tests/wait.js";
 import { saveScreenshot } from "./tests/saveScreenshot.js";
 import { startRecording } from "./tests/startRecording.js";
@@ -34,7 +35,9 @@ import { clickElement } from "./tests/click.js";
 import { runCode } from "./tests/runCode.js";
 import { closeSurface } from "./tests/closeSurface.js";
 import { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, startAppSurface, teardownAppSession, } from "./tests/appSurface.js";
-import { isMobileTargetPlatform, mobileContextSkipReason, } from "./tests/mobilePlatform.js";
+import { isMobileTargetPlatform } from "./tests/mobilePlatform.js";
+import { mobileBrowserGate, buildMobileBrowserCapabilities, } from "./tests/mobileBrowser.js";
+import { getCacheDir } from "../runtime/cacheDir.js";
 import { detectAndroidSdk } from "../runtime/androidSdk.js";
 import { hostAbi, listInstalledSystemImages, installAndroid, } from "../runtime/androidInstaller.js";
 import { buildAcquireDeviceDeps, checkEmulatorAcceleration, hostHasKvm, planDeviceAcquisition, planAndroidToolchain, normalizeDeviceDescriptor, acquireDevice, createDeviceRegistry, teardownDeviceRegistry, } from "./tests/androidEmulator.js";
@@ -55,7 +58,7 @@ import http from "node:http";
 import https from "node:https";
 import { fileURLToPath } from "node:url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, };
+export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, };
 // exports.appiumStart = appiumStart;
 // exports.appiumIsReady = appiumIsReady;
 // exports.driverStart = driverStart;
@@ -295,11 +298,18 @@ function jobDisplayResources(job, ctx) {
     // emulator is GBs of RAM, so bound their concurrency to one at a time. This
     // is exclusivity-as-bound on a single resource name (a counted semaphore is
     // future work); it composes with any recording "display" resource above.
-    // Only android contexts that will actually attempt the emulator take it — an
-    // android+browser context deterministically SKIPs (phase A5) before any
-    // emulator/toolchain work, so it must not needlessly serialize other jobs.
+    // Only android contexts that will actually attempt the emulator take it.
+    // Native app contexts always do; a mobile-web context (phase A5) does when
+    // its browser gate proceeds — a context the gate deterministically SKIPs or
+    // FAILs (unsupported browser, mixed app+web, device-fixed config) never
+    // boots anything, so it must not needlessly serialize other jobs.
     const attemptsEmulator = job.context?.platform === "android" &&
-        !isBrowserRequired({ test: job.context });
+        mobileBrowserGate({
+            platform: "android",
+            browser: job.context?.browser,
+            hasBrowserStep: isBrowserRequired({ test: job.context }),
+            hasAppStep: isAppDriverRequired({ test: job.context }),
+        }).action === "proceed";
     const extra = attemptsEmulator ? ["android-emulator"] : [];
     if (base.length || extra.length)
         return [...new Set([...base, ...extra])];
@@ -399,19 +409,29 @@ function requiredAndroidOsVersions(context) {
 }
 // Android context preflight (native app phase A3b): host-capability probe →
 // lazy toolchain install (when the run needs it) → per-device resolvability →
-// UiAutomator2 driver install. Every gap is a gating SKIP (never FAIL). The
+// UiAutomator2 driver install. Every environment gap is a gating SKIP (never
+// FAIL); the one FAIL is authored device-fixed browser config (phase A5 gate),
+// which is a contradiction to surface loudly, not a missing capability. The
 // toolchain (SDK + system image) is NOT installed by default, but IS lazily
 // installed — with a loud warning surfaced to the terminal AND the output
 // report — when a run that reaches a capable host actually needs it. On ok,
 // returns the Appium entry/home, SDK root, injected device-effect bundle, and
 // any warnings to attach to the context report.
 async function androidContextPreflight({ config, context, clog, }) {
-    const hasBrowserStep = isBrowserRequired({ test: context });
-    if (hasBrowserStep) {
-        const { level, reason } = mobileContextSkipReason({
-            platform: "android",
-        });
-        return { ok: false, level, reason };
+    // Mobile-web gate (phase A5) — before ANY toolchain work, so unsupported
+    // browsers, mixed app+web contexts, and device-fixed browser config land
+    // deterministically on every host without touching the SDK.
+    const gate = mobileBrowserGate({
+        platform: "android",
+        browser: context.browser,
+        hasBrowserStep: isBrowserRequired({ test: context }),
+        hasAppStep: isAppDriverRequired({ test: context }),
+    });
+    if (gate.action === "skip") {
+        return { ok: false, level: gate.level, reason: gate.reason };
+    }
+    if (gate.action === "fail") {
+        return { ok: false, level: "warning", reason: gate.reason, fail: true };
     }
     /* c8 ignore start */
     // The rest is effectful (SDK detect/install, emulator probes) so it's
@@ -558,6 +578,7 @@ async function androidContextPreflight({ config, context, clog, }) {
             sdkRoot: sdk.sdkRoot,
             deviceDeps,
             warnings,
+            mobileWebBrowserName: gate.browserName,
         };
     }
     catch (error) {
@@ -569,19 +590,26 @@ async function androidContextPreflight({ config, context, clog, }) {
     }
     /* c8 ignore stop */
 }
-// iOS context preflight (native app phase A4): mobile-browser contexts are
-// still gated to A5; native app contexts probe host capability/toolchain via
-// appSurfacePreflight, then validate that the context's default simulator can
-// be resolved (booted/created) via simctl. On success return the appium
-// entry/home plus the injected simctl effect bundle for the run's
-// acquireSimulator closure.
+// iOS context preflight (native app phase A4 + mobile web phase A5): the
+// mobile-browser gate decides first (support matrix / device-fixed config /
+// mixed-context deferral — all pure, all pre-toolchain); then host
+// capability/toolchain probes via appSurfacePreflight, then validation that
+// the context's default simulator can be resolved (booted/created) via
+// simctl. On success return the appium entry/home, the injected simctl effect
+// bundle for the run's acquireSimulator closure, and the device browser (if
+// any) to open a session for.
 async function iosContextPreflight({ config, context, }) {
-    const hasBrowserStep = isBrowserRequired({ test: context });
-    if (hasBrowserStep) {
-        const { level, reason } = mobileContextSkipReason({
-            platform: "ios",
-        });
-        return { ok: false, level, reason };
+    const gate = mobileBrowserGate({
+        platform: "ios",
+        browser: context.browser,
+        hasBrowserStep: isBrowserRequired({ test: context }),
+        hasAppStep: isAppDriverRequired({ test: context }),
+    });
+    if (gate.action === "skip") {
+        return { ok: false, level: gate.level, reason: gate.reason };
+    }
+    if (gate.action === "fail") {
+        return { ok: false, level: "warning", reason: gate.reason, fail: true };
     }
     const pre = await appSurfacePreflight({ config, platform: "ios" });
     if (!pre.ok)
@@ -622,6 +650,7 @@ async function iosContextPreflight({ config, context, }) {
         appiumEntry: pre.appiumEntry,
         appiumHome: pre.appiumHome,
         simulatorDeps,
+        mobileWebBrowserName: gate.browserName,
     };
     /* c8 ignore stop */
 }
@@ -1911,6 +1940,14 @@ function selectWarmUpTargets(jobs, runnerDetails) {
         // would defeat the warm-up/install de-racing the pre-pass exists for.
         if (!context.platform)
             context.platform = platform;
+        // Mobile contexts (android/ios targets) never warm up a desktop engine:
+        // their browser runs ON the device through the per-context app Appium
+        // server (phase A5), so a desktop warm-up would launch the wrong browser
+        // on the wrong machine — and must not write a desktop default browser
+        // onto the context (runContext's mobile branch resolves the device
+        // browser itself).
+        if (isMobileTargetPlatform(context.platform))
+            continue;
         // Size and target the warm-up by isBrowserRequired (not isDriverRequired):
         // app-only contexts run on their own per-context Appium server, so they
         // must not pull a browser into the pre-pass or get a default browser
@@ -2391,8 +2428,13 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     // If "browser" isn't defined but is required by the test, set it to the
     // first available browser in the sequence of Firefox, Chrome, Safari.
     // App-targeted steps don't count: they run on the app session, so an
-    // app-only test never boots a browser it won't use.
-    if (!context.browser && isBrowserRequired({ test: context })) {
+    // app-only test never boots a browser it won't use. Mobile contexts don't
+    // count either: their browser is the device's (chrome/safari), resolved by
+    // the mobile branch below — a desktop default here would be wrong on both
+    // the engine and the machine.
+    if (!context.browser &&
+        isBrowserRequired({ test: context }) &&
+        !isMobileTargetPlatform(context.platform)) {
         context.browser = getDefaultBrowser({ runnerDetails });
     }
     // Set context report
@@ -2419,6 +2461,11 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     // context that passes its preflight (phase A3b). Declared here so the mobile
     // branch can set it and fall through to the shared step-execution path.
     let appSession;
+    // Mobile web (phase A5): set when the mobile preflight resolved a device
+    // browser for this context. The try block below then opens the browser
+    // session on the device (through the app session's Appium server) instead
+    // of the desktop engine path.
+    let mobileWebBrowserName;
     const mobileTarget = isMobileTargetPlatform(context.platform);
     if (mobileTarget) {
         const requirementsSkip = contextRequirementsSkipMessage({ context });
@@ -2428,59 +2475,71 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             contextReport.resultDescription = requirementsSkip;
             return contextReport;
         }
+        // Both preflights run the mobile-browser gate first (support matrix,
+        // device-fixed config, mixed app+web) — `fail: true` marks an authored
+        // contradiction (FAIL loudly); everything else lands SKIPPED. Applied via
+        // this shared closure so the two typed branches below stay narrowed to
+        // their platform's ok-shape (no cross-platform union casts).
+        const gateOutcome = (pre) => {
+            clog(pre.fail ? "error" : pre.level, pre.reason);
+            contextReport.result = pre.fail ? "FAIL" : "SKIPPED";
+            contextReport.resultDescription = pre.reason;
+            return contextReport;
+        };
+        let gateBrowserName;
         if (mobileTarget === "android") {
-            // Android (phase A3b): full preflight. SDK detection is lazy (probed
-            // only here, only for android contexts), so a run that never targets
-            // android pays nothing. On skip, land SKIPPED with the actionable reason;
-            // on ok, prime the app session with the device layer and FALL THROUGH to
-            // run the steps.
+            // Android (phase A3b): SDK detection is lazy (probed only here, only
+            // for android contexts), so a run that never targets android pays
+            // nothing. On ok, prime the app session with the device layer and FALL
+            // THROUGH to run the steps.
             const pre = await androidContextPreflight({ config, context, clog });
-            if (!pre.ok) {
-                clog(pre.level, pre.reason);
-                contextReport.result = "SKIPPED";
-                contextReport.resultDescription = pre.reason;
-                return contextReport;
-            }
+            if (!pre.ok)
+                return gateOutcome(pre);
             /* c8 ignore start */
             // The ok path only runs on a host with a real SDK + emulator (CI legs).
             appSession = createAppSessionState();
             appSession.appiumEntry = pre.appiumEntry;
             appSession.appiumHome = pre.appiumHome;
-            appSession.defaultDevice = context.device;
             appSession.androidSdkRoot = pre.sdkRoot;
             appSession.androidDeviceRegistry = deviceRegistry;
             appSession.androidDeviceDeps = pre.deviceDeps;
-            // resolved device (name) joins the context report the way resolved
-            // browser versions do; the concrete udid is known once a surface boots
-            // it.
-            contextReport.device = context.device ?? { platform: "android" };
             // Surface any preflight warnings (e.g. a lazy toolchain install) in the
             // output report — not just the terminal — so a run that quietly
             // downloaded the multi-GB SDK is auditable after the fact.
             if (pre.warnings.length)
                 contextReport.warnings = pre.warnings;
+            gateBrowserName = pre.mobileWebBrowserName;
             /* c8 ignore stop */
         }
         else {
+            // iOS (phase A4): on ok, prime the app session with the simulator layer.
             const pre = await iosContextPreflight({ config, context });
-            if (!pre.ok) {
-                clog(pre.level, pre.reason);
-                contextReport.result = "SKIPPED";
-                contextReport.resultDescription = pre.reason;
-                return contextReport;
-            }
+            if (!pre.ok)
+                return gateOutcome(pre);
             /* c8 ignore start */
-            // The ok path only runs on a capable macOS host (CI fixture legs): prime
-            // the app session with the simulator layer and FALL THROUGH to run steps.
+            // The ok path only runs on a capable macOS host (CI fixture legs).
             appSession = createAppSessionState();
             appSession.appiumEntry = pre.appiumEntry;
             appSession.appiumHome = pre.appiumHome;
-            appSession.defaultDevice = context.device;
             appSession.iosSimulatorRegistry = simulatorRegistry;
             appSession.iosSimulatorDeps = pre.simulatorDeps;
-            contextReport.device = context.device ?? { platform: "ios" };
+            gateBrowserName = pre.mobileWebBrowserName;
             /* c8 ignore stop */
         }
+        /* c8 ignore start */
+        appSession.defaultDevice = context.device;
+        // resolved device (name) joins the context report the way resolved
+        // browser versions do; the concrete udid is known once a device boots.
+        contextReport.device = context.device ?? { platform: mobileTarget };
+        if (gateBrowserName) {
+            // Mobile web: pin the context's browser to the device browser the gate
+            // resolved (the authored one, or the platform default) so the report
+            // and the session capabilities agree.
+            mobileWebBrowserName = gateBrowserName;
+            context.browser = { ...(context.browser ?? {}), name: mobileWebBrowserName };
+            contextReport.browser = context.browser;
+        }
+        /* c8 ignore stop */
     }
     // `requires` capability gate: any unmet requirement skips the context with a
     // message naming what's missing. Evaluated only on the platform the context
@@ -2609,8 +2668,10 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
         })
         : [];
     // A driver context with no startable engine is skipped with a diagnostic that
-    // names the requested engine and the partial-download cause.
-    if (driverRequired && candidateEngines.length === 0) {
+    // names the requested engine and the partial-download cause. Mobile-web
+    // contexts don't participate: their browser lives on the device, not in the
+    // host's engine list (their session path is the mobile block below).
+    if (driverRequired && !mobileWebBrowserName && candidateEngines.length === 0) {
         const errorMessage = freshInstallRedetected
             ? freshInstallOutcome === "installed"
                 ? `Skipping context '${requestedBrowserName}' on '${context.platform}': the missing browser dependency was installed but still could not be detected.`
@@ -2659,7 +2720,120 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             "predicate disagreed; this is a bug.");
     }
     try {
-        if (driverRequired) {
+        /* c8 ignore start */
+        // Mobile web (phase A5): only reachable on a capable host (the mobile
+        // preflight gates everything else), so it's exercised by the
+        // mobile-web fixture legs, not the unit suite.
+        if (driverRequired && mobileWebBrowserName) {
+            // The browser session lives ON the managed device, through the app
+            // session's Appium server (homed where the mobile driver lives) — not
+            // the desktop engine pool. Acquire/boot the context's default device,
+            // then open one webdriver session with browserName set so Appium starts
+            // it in a web context; goTo/find/click/screenshot then behave exactly
+            // as on desktop.
+            const env = {
+                APPIUM_HOME: appSession.appiumHome,
+            };
+            if (appSession.androidSdkRoot) {
+                env.ANDROID_HOME = appSession.androidSdkRoot;
+                env.ANDROID_SDK_ROOT = appSession.androidSdkRoot;
+            }
+            // Chromedriver autodownload is an Appium insecure feature; opt in
+            // scoped to the uiautomator2 driver on this run-owned server so it can
+            // fetch the chromedriver matching the device's Chrome.
+            const extraArgs = mobileTarget === "android"
+                ? ["--allow-insecure", "uiautomator2:chromedriver_autodownload"]
+                : [];
+            // Server start + device boot are environment work: any failure there
+            // (port pressure, an emulator that can't finish booting on this host,
+            // simctl trouble) is a gating SKIP with the reason named — never a
+            // FAIL — matching the mobile rule that every environment gap SKIPs.
+            let acquired;
+            try {
+                const server = await startAppiumServer(appSession.appiumEntry, config, undefined, env, extraArgs);
+                appSession.server = { port: server.port, process: server.process };
+                const desc = normalizeDeviceDescriptor({
+                    contextDevice: context.device,
+                    platform: mobileTarget,
+                });
+                acquired =
+                    mobileTarget === "android"
+                        ? await acquireDevice({
+                            desc,
+                            registry: appSession.androidDeviceRegistry,
+                            sdkRoot: appSession.androidSdkRoot,
+                            deps: appSession.androidDeviceDeps,
+                        })
+                        : await acquireSimulator({
+                            desc,
+                            registry: appSession.iosSimulatorRegistry,
+                            deps: appSession.iosSimulatorDeps,
+                        });
+            }
+            catch (error) {
+                const errorMessage = `Skipping context on '${mobileTarget}': couldn't prepare the device for the ${mobileWebBrowserName} session (${error?.message ?? error}). Check the emulator/simulator toolchain (\`doc-detective install ${mobileTarget}\`).`;
+                clog("warning", errorMessage);
+                contextReport.result = "SKIPPED";
+                contextReport.resultDescription = errorMessage;
+                return contextReport;
+            }
+            if ("skip" in acquired) {
+                clog("warning", acquired.skip);
+                contextReport.result = "SKIPPED";
+                contextReport.resultDescription = acquired.skip;
+                return contextReport;
+            }
+            // The resolved device joins the context report the way resolved
+            // browser versions do.
+            contextReport.device = {
+                ...(typeof contextReport.device === "object"
+                    ? contextReport.device
+                    : {}),
+                platform: mobileTarget,
+                name: acquired.entry.name,
+            };
+            const capabilities = buildMobileBrowserCapabilities({
+                platform: mobileTarget,
+                udid: acquired.entry.udid,
+                // The resolved cache root (not the raw config field, which is
+                // usually unset) — the chromedriver autodownload dir lives here.
+                cacheDir: getCacheDir({ cacheDir: config?.cacheDir }),
+            });
+            try {
+                driver = await driverStart(capabilities, appSession.server.port, 2, {
+                    cacheDir: config?.cacheDir,
+                });
+            }
+            catch (error) {
+                // A capable host that can't open the device browser is an
+                // environment gap (the absent-browser precedent): SKIP with the
+                // likely cause named, never FAIL.
+                const hint = mobileTarget === "android"
+                    ? " Chrome may not be present on this emulator image — managed Android mobile-web needs a `google_apis` system image (see `doc-detective install android`)."
+                    : " Check that the simulator runtime includes Safari and that WebDriverAgent can build (see `doc-detective install ios`).";
+                const errorMessage = `Skipping context on '${mobileTarget}': couldn't start the ${mobileWebBrowserName} session on device '${acquired.entry.name}' (${error?.message ?? error}).${hint}`;
+                clog("warning", errorMessage);
+                contextReport.result = "SKIPPED";
+                contextReport.resultDescription = errorMessage;
+                return contextReport;
+            }
+            // Register the device browser as the context's one browser surface so
+            // surface-targeted steps resolve it by engine name, same as desktop.
+            // No additional sessions: one device, one browser.
+            browserSessions = createSessionRegistry({
+                open: async () => {
+                    throw new Error("Additional browser sessions aren't supported on a managed device; the device browser is the context's only browser surface.");
+                },
+                isNameTaken: (name) => !!processRegistry?.has(name),
+            });
+            registerSession(browserSessions, {
+                name: String(mobileWebBrowserName).toLowerCase(),
+                engine: String(mobileWebBrowserName).toLowerCase(),
+                driver,
+            });
+            /* c8 ignore stop */
+        }
+        else if (driverRequired) {
             // Check out a server for this context's lifetime — released in the
             // finally so the next queued context can reuse it.
             appiumPort = await appiumPool.acquire();
@@ -3564,6 +3738,14 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             appSession,
         });
     }
+    else if (typeof step.swipe !== "undefined") {
+        actionResult = await swipeSurface({
+            config: config,
+            step: step,
+            driver: driver,
+            appSession,
+        });
+    }
     else if (typeof step.type !== "undefined") {
         actionResult = await typeKeys({
             config: config,
@@ -3633,7 +3815,10 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
 // Start one Appium server on a free port and resolve once it answers /status.
 // Each concurrent runner gets its own server (own port) so parallel contexts
 // never create sessions on the same Appium instance.
-async function startAppiumServer(appiumEntry, config, display, extraEnv) {
+async function startAppiumServer(appiumEntry, config, display, extraEnv, 
+// Extra CLI args for the server, e.g. the scoped `--allow-insecure`
+// chromedriver-autodownload opt-in for android mobile-web sessions.
+extraArgs) {
     const port = await findFreePort();
     log(config, "debug", `Starting Appium on port ${port}`);
     // When a virtual display is supplied (Linux Xvfb recording), launch the
@@ -3648,7 +3833,7 @@ async function startAppiumServer(appiumEntry, config, display, extraEnv) {
             ...(extraEnv ?? {}),
         }
         : process.env;
-    const proc = spawn(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port)], {
+    const proc = spawn(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port), ...(extraArgs ?? [])], {
         windowsHide: true,
         cwd: path.join(__dirname, "../.."),
         env,
@@ -3693,20 +3878,11 @@ async function appiumIsReady(port, timeoutMs = 120000) {
 }
 // Start the Appium driver specified in `capabilities`.
 async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
-    // Two families of transient, retryable session-creation failures, both worse
-    // under concurrency (the TRANSIENT regex below enumerates the specific
-    // patterns):
-    //   1. POST /session races a just-spawned-or-still-dying Appium (Windows):
-    //      /status returns 200 from the outgoing process while /session no longer
-    //      accepts, or Appium's proxy to chromedriver drops the socket ->
-    //      ECONNREFUSED / ECONNRESET / "socket hang up" / "could not proxy command".
-    //   2. Several Chromes launching at once briefly starve resources and
-    //      ChromeDriver "crashed during startup" / "cannot connect to" /
-    //      "DevToolsActivePort" / "session not created". A staggered retry lets
-    //      the contention clear; it recovers on the next attempt in practice.
-    // Retry these with linear backoff; any other error is a real session-
-    // creation failure and propagates immediately.
-    const TRANSIENT = /ECONNREFUSED|ECONNRESET|socket hang up|could not proxy command|crashed during startup|cannot connect to|DevToolsActivePort|session not created/i;
+    // Retryable session-creation failures (transient races/contention, plus the
+    // client-side timeout abort for slow-startup native sessions) are enumerated
+    // by isRetryableSessionError in ./utils.js. Retry those with linear backoff;
+    // any other error is a real session-creation failure and propagates
+    // immediately.
     const wdio = await loadHeavyDep("webdriverio", { ctx });
     // The wdio client aborts the POST /session request after connectionRetryTimeout.
     // A cold native session can take far longer to create than the 2-minute
@@ -3741,7 +3917,7 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
         }
         catch (err) {
             lastError = err;
-            if (!TRANSIENT.test(String(err && err.message)))
+            if (!isRetryableSessionError(String(err && err.message), startupCeiling))
                 throw err;
             if (attempt < maxAttempts) {
                 await new Promise((r) => setTimeout(r, 500 * attempt));