doc-detective 4.35.0 → 4.37.0

package/dist/core/tests.js

@@ -13,9 +13,9 @@ import { resolveTheme } from "./annotations/model.js";
 import { annotate, pruneExpired, renderLayer } from "./tests/annotate.js";
 import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/browsers.js";
 // Single source of truth for browser/driver-requiring step keys.
-import { BROWSER_STEP_KEYS as driverActions, startSurfaceDescriptors, stepOpensBrowserSurface, } from "../runtime/browserStepKeys.js";
+import { BROWSER_STEP_KEYS as driverActions, startSurfaceDescriptors, stepOpensBrowserSurface, stepTargetsProcessSurface, stepIsSurfacelessInteraction, testHasNonBrowserSurfaceSignal, } from "../runtime/browserStepKeys.js";
 import os from "node:os";
-import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, realizeViewport, isViewportFloored, } from "./utils.js";
+import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, classifyContextRetry, realizeViewport, isViewportFloored, } from "./utils.js";
 import axios from "axios";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
@@ -39,6 +39,7 @@ import { runCode } from "./tests/runCode.js";
 import { closeSurface } from "./tests/closeSurface.js";
 import { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, teardownAppSession, APP_DRIVER_PLATFORMS, probeIosToolchain, } from "./tests/appSurface.js";
 import { startSurfaceStep } from "./tests/startSurface.js";
+import { createActiveSurfaceTracker, } from "./tests/activeSurface.js";
 import { isMobileTargetPlatform } from "./tests/mobilePlatform.js";
 import { mobileBrowserGate, buildMobileBrowserCapabilities, CHROMEDRIVER_AUTODOWNLOAD_ARGS, } from "./tests/mobileBrowser.js";
 import { planWarmTasks, executeWarmTasks, raceBootInitiation, wrapInitiationEffects, RUNTIME_INSTALL_RESOURCE, } from "./warmPhase.js";
@@ -64,7 +65,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, withChromedriverPort, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, buildWarmPlanDeps, warmBrowserInstall, prefetchMobileChromedriver, appiumIsReady, };
+export { runSpecs, runViaApi, getRunner, ensureChromeAvailable, ensureContextBrowserInstalled, combinationKey, warmUpDecision, selectWarmUpTargets, getDriverCapabilities, withChromedriverPort, getDefaultBrowser, buildFallbackCandidates, driverSkipDiagnostic, resolveBrowserFallbackPolicy, resolveRetryPolicy, runContextWithRetries, shouldRepairBeforeFallback, isSupportedContext, contextRequirementsSkipMessage, resolveAutoScreenshot, resolveAutoRecord, buildAutoRecordStep, specIsRouted, killTree, jobDisplayResources, buildWarmPlanDeps, warmBrowserInstall, prefetchMobileChromedriver, appiumIsReady, };
 // exports.driverStart = driverStart;
 // Browser names getDriverCapabilities knows how to build caps for. `safari` is
 // rewritten to `webkit` during context resolution, so both appear here.
@@ -471,17 +472,25 @@ function isSupportedContext({ context, apps, platform }) {
     return Boolean(isSupportedApp && isSupportedPlatform);
 }
 // Like isDriverRequired, but only counts driver steps that need a BROWSER: a
-// step whose payload targets an app surface (object form) is driven by the
-// app session instead, and the synthetic autoRecord capture is an ffmpeg
-// screen grab — neither may force a default browser into existence (in a
-// browser test the authored steps already require one, so excluding the
-// synthetic step never changes the outcome there).
+// step whose payload targets an app or process surface (object form) is
+// driven by the app session / process registry instead, and the synthetic
+// autoRecord capture is an ffmpeg screen grab — none may force a default
+// browser into existence (in a browser test the authored steps already
+// require one, so excluding the synthetic step never changes the outcome
+// there). Uniform routing (ADR 01081) adds one more exclusion: a
+// surface-less interaction step in a test that opens or targets a
+// non-browser surface routes to the active surface at runtime, so it doesn't
+// force a browser either — a test with no such signal keeps the browser
+// default unchanged.
 function isBrowserRequired({ test }) {
     if (!Array.isArray(test?.steps))
         return false;
+    const hasNonBrowserSignal = testHasNonBrowserSurfaceSignal(test.steps);
     return test.steps.some((step) => !step?.__autoRecord &&
         ((driverActions.some((action) => typeof step[action] !== "undefined") &&
-            !stepTargetsAppSurface(step)) ||
+            !stepTargetsAppSurface(step) &&
+            !stepTargetsProcessSurface(step) &&
+            !(hasNonBrowserSignal && stepIsSurfacelessInteraction(step))) ||
             // Phase 6: `startSurface: { browser: … }` opens a browser session
             // (the goTo-opener sibling); app/process descriptors don't.
             stepOpensBrowserSurface(step)));
@@ -850,6 +859,14 @@ function buildFallbackCandidates({ requestedName, explicit, policy, availableApp
 function resolveBrowserFallbackPolicy({ context, config, }) {
     return context?.browserFallback || config?.browserFallback || "auto";
 }
+// Resolve the mid-run session-death context-retry budget (the `retries` policy):
+// how many times to re-run a whole context on a fresh session when its session
+// dies mid-run. Context overrides config; default 1. Uses `??` (NOT `||`) so an
+// explicit `retries: 0` (disable) is preserved instead of falling through to the
+// default the way a falsy `||` would. Pure and exported for unit testing.
+function resolveRetryPolicy({ context, config, }) {
+    return context?.retries ?? config?.retries ?? 1;
+}
 /**
  * Whether to attempt a driver repair before falling back away from a browser
  * whose session just failed to start. We only repair the *requested* engine
@@ -958,6 +975,8 @@ async function runViaApi({ resolvedTests, apiKey, config = {} }) {
                     contexts: { pass: 0, fail: 0, warning: 0, skipped: 0 },
                     steps: { pass: 0, fail: 0, warning: 0, skipped: 0 },
                 },
+                // Nothing ran, but the shape stays parity with runSpecs' short-circuit.
+                durationMs: 0,
                 specs: [],
             };
         }
@@ -1075,6 +1094,14 @@ async function runViaApi({ resolvedTests, apiKey, config = {} }) {
  */
 async function runSpecs({ resolvedTests }) {
     const config = resolvedTests.config;
+    // Run-level wall clock, scoped to the EXECUTION phase — detection,
+    // resolution, and JIT dependency installs happen in runTests before this
+    // point and are deliberately excluded (see ADR 01083). Started before the
+    // filter short-circuit so a zero-spec run reports a real (tiny) duration
+    // rather than omitting the field. Unlike the spec/test sums, this IS elapsed
+    // time — so under concurrency it can be LESS than the sum of the per-spec
+    // durations.
+    const runStart = Date.now();
     // Narrow the spec set to what specFilter / testFilter allow before running.
     // Filtered-out specs / tests do not appear in the report (true filter, not
     // skip). Pass-through when neither filter is set.
@@ -1095,6 +1122,7 @@ async function runSpecs({ resolvedTests }) {
                 contexts: { pass: 0, fail: 0, warning: 0, skipped: 0 },
                 steps: { pass: 0, fail: 0, warning: 0, skipped: 0 },
             },
+            durationMs: Date.now() - runStart,
             specs: [],
         };
     }
@@ -1623,7 +1651,7 @@ async function runSpecs({ resolvedTests }) {
         // ordering to a single pool over input-ordered jobs.
         const runJob = async (job) => {
             try {
-                job.contexts[job.slot] = await runContext({
+                job.contexts[job.slot] = await runContextWithRetries({
                     config,
                     spec: job.spec,
                     test: job.test,
@@ -1729,7 +1757,9 @@ async function runSpecs({ resolvedTests }) {
         // Phase 3: roll results up the tree and count the summary in one
         // deterministic pass after all contexts have finished.
         for (const specReport of report.specs) {
+            let specDurationMs = 0;
             for (const testReport of specReport.tests) {
+                let testDurationMs = 0;
                 for (const contextReport of testReport.contexts) {
                     // Every slot is assigned by the pool callback (even on crash), so
                     // this guard should never fire — it documents the invariant and
@@ -1738,13 +1768,30 @@ async function runSpecs({ resolvedTests }) {
                         continue;
                     for (const stepReport of contextReport.steps) {
                         report.summary.steps[stepReport.result.toLowerCase()]++;
+                        // Default here rather than at each construction site: this pass is
+                        // the only place that sees EVERY node from both execution paths
+                        // (flat pool and routed sequencer), real and synthetic alike. A
+                        // node that never ran — a guard-skipped context, a routing marker
+                        // — has no clock, and a future synthetic site can't forget the
+                        // field. Nodes that ran keep their measured value (ADR 01083).
+                        stepReport.durationMs ??= 0;
                     }
                     report.summary.contexts[contextReport.result.toLowerCase()]++;
+                    contextReport.durationMs ??= 0;
+                    testDurationMs += contextReport.durationMs;
                 }
                 testReport.result = rollUpResults(testReport.contexts.filter(Boolean));
+                // Test and spec durations are SUMS of their children, not wall-clock
+                // spans: contexts from every test and spec share one concurrent pool,
+                // so a span would count idle time while unrelated specs ran. The sum
+                // is total work — what slow-test triage and JUnit's `<testsuite time>`
+                // both want. See ADR 01083.
+                testReport.durationMs = testDurationMs;
+                specDurationMs += testDurationMs;
                 report.summary.tests[testReport.result.toLowerCase()]++;
             }
             specReport.result = rollUpResults(specReport.tests);
+            specReport.durationMs = specDurationMs;
             report.summary.specs[specReport.result.toLowerCase()]++;
         }
     }
@@ -1821,6 +1868,9 @@ async function runSpecs({ resolvedTests }) {
             };
         }
     }
+    // Stamped last, after teardown and any Heretto upload, so the number matches
+    // the elapsed time a user actually observes.
+    report.durationMs = Date.now() - runStart;
     return report;
 }
 /**
@@ -2008,7 +2058,7 @@ async function runRoutedSpec({ spec, specReport, specGuardSkip, config, runnerDe
         // limit===1 keep the byte-identical runConcurrent path.
         const runRoutedJob = async (job) => {
             try {
-                job.contexts[job.slot] = await runContext({
+                job.contexts[job.slot] = await runContextWithRetries({
                     config,
                     spec: job.spec,
                     test: job.test,
@@ -3028,6 +3078,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;
+    // Cross-kind active-surface tracker (ADR 01081): one MRU per context,
+    // shared by the browser session registry, the app session, and the process
+    // lanes, so surface-less steps route to the most recently active surface
+    // regardless of kind.
+    const surfaceTracker = createActiveSurfaceTracker();
     // 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
@@ -3142,6 +3197,10 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
         appSession.appiumEntry = preflight.appiumEntry;
         appSession.appiumHome = preflight.appiumHome;
     }
+    // Whichever branch created the app session (android/ios/desktop), it shares
+    // the context's active-surface tracker with the browser registry below.
+    if (appSession)
+        appSession.tracker = surfaceTracker;
     // If a driver is required but no browser could be resolved (e.g.
     // getDefaultBrowser found nothing installed, or the context supplied a
     // browser object with no name), skip with an explicit reason instead of
@@ -3282,6 +3341,10 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     // WARNING when an explicitly pinned engine was substituted.
     let fellBackNote = "";
     let fellBackPinned = false;
+    // Set by the post-loop liveness probe: true when the context failed AND its
+    // session was found dead mid-run. The caller (runContextWithRetries) reads
+    // this off the returned report to decide whether to retry on a fresh session.
+    let sessionDiedMidRun = false;
     if (driverRequired && !appiumPool) {
         throw new Error("Browser driver requested but no Appium server pool was created; " +
             "the pool sizing (browserJobCount) and this context's isBrowserRequired " +
@@ -3391,6 +3454,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                     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),
+                tracker: surfaceTracker,
             });
             registerSession(browserSessions, {
                 name: String(mobileWebBrowserName).toLowerCase(),
@@ -3591,6 +3655,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                         return res.driver;
                     },
                     isNameTaken: (name) => !!processRegistry?.has(name),
+                    tracker: surfaceTracker,
                 });
                 registerSession(browserSessions, {
                     name: String(startedName).toLowerCase(),
@@ -3844,6 +3909,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             // it. Surface-less browser steps in that (pathological) state fail on the
             // dead session — acceptable; the run closed its own browser mid-test.
             const runStepOnce = async () => {
+                const stepStart = Date.now();
                 const r = await runStep({
                     config: config,
                     context: context,
@@ -3856,6 +3922,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                     },
                     processRegistry: processRegistry,
                     appSession: appSession,
+                    surfaceTracker: surfaceTracker,
                 });
                 if (logLevelEnabled(config, "debug"))
                     clog("debug", `RESULT: ${r.status}\n${JSON.stringify(r, null, 2)}`);
@@ -3863,7 +3930,12 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 r.resultDescription = r.description;
                 delete r.status;
                 delete r.description;
-                return { ...step, ...r };
+                // Stamp AFTER the spread: `step` may carry an authored `duration`
+                // input (a click's press duration, an annotation's display duration),
+                // and `r` is the runStep result — neither may clobber the timing.
+                // On retry the loop below discards this report wholesale, so the
+                // surviving value is the FINAL attempt's, per ADR 01083.
+                return { ...step, ...r, durationMs: Date.now() - stepStart };
             };
             // Run the step, then resolve routing. A `retry` decision re-runs the step
             // (up to `limit` retries — so `limit + 1` total runs — waiting `delay`
@@ -4034,6 +4106,59 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 contextReport,
             });
         }
+        // Mid-run session-death detection for the `retries` context-retry policy.
+        // A dead session's step FAIL is indistinguishable from a real assertion FAIL
+        // at the result level (handlers catch driver errors and return FAIL), so if
+        // any step failed we probe the session directly here — while it is still
+        // registered, before the finally tears it down. A dead session means the
+        // FAIL is spurious and the whole context can be retried on a fresh session; a
+        // live session means the FAIL is real and stands. Recording sweeps already
+        // ran above, so the probe never races an in-flight capture.
+        if (contextReport.steps.some((s) => s.result === "FAIL")) {
+            // Collect EVERY session the context holds — a multi-surface browser
+            // context plus an app session — not just the first, so a dead app/native
+            // session behind a live browser (or vice versa) is still caught. Which of
+            // these each check applies to differs, and classifyContextRetry owns that
+            // distinction. Primary session first (Map values() is insertion-ordered).
+            const probeDrivers = sessionDrivers(browserSessions, driver);
+            if (appSession?.recordingHost)
+                probeDrivers.push(appSession.recordingHost);
+            // Which sessions each probe applies to, and how they rank, lives in
+            // classifyContextRetry so it can be unit tested without a real context.
+            // A dead session is the silent case: it needs no explanation beyond the
+            // retry warning the wrapper already logs. The alive-but-unusable cases do,
+            // because "the session responded and we retried anyway" is otherwise
+            // surprising in a log.
+            const retryReason = await classifyContextRetry(probeDrivers);
+            if (retryReason) {
+                sessionDiedMidRun = true;
+                if (retryReason === "page-broken") {
+                    clog("debug", "Context session is alive but on a browser error page; treating it as a broken context for retry.");
+                }
+                else if (retryReason === "unnavigated") {
+                    clog("debug", "Context session is alive but still on its initial blank document (never navigated); treating it as a broken context for retry.");
+                }
+            }
+            if (!sessionDiedMidRun &&
+                probeDrivers.length > 0 &&
+                logLevelEnabled(config, "debug") &&
+                typeof probeDrivers[0].getUrl === "function") {
+                // Diagnostic for whatever live-session modes remain uncovered: log the
+                // page URL of a live-session FAIL that was NOT retried. This is how the
+                // long-running `windows-chrome` flake was characterized — every
+                // occurrence, across both the recording and nav-capture bundles, logged
+                // `url=data:,`, which ADR 01084 now retries. What's left for it to catch
+                // is the same-URL-blank mode (page blanks without changing URL), which
+                // stays unretried because it can't be told apart from a genuine
+                // element-not-found on a correctly-loaded page.
+                try {
+                    clog("debug", `Context FAILed on a live, non-error-page session (url=${await probeDrivers[0].getUrl()}); not retried.`);
+                }
+                catch {
+                    /* best-effort diagnostic */
+                }
+            }
+        }
     }
     finally {
         // Safety net: if the context threw before the normal sweep above, recordings
@@ -4119,8 +4244,108 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             ? `${fellBackNote} ${contextReport.resultDescription}`
             : fellBackNote;
     }
+    // Internal hint for runContextWithRetries — a FAIL whose session died mid-run
+    // is retryable. Non-enumerable so it never leaks into the serialized report,
+    // and only set on the retryable case so the wrapper's check is a plain read.
+    if (contextReport.result === "FAIL" && sessionDiedMidRun) {
+        Object.defineProperty(contextReport, "_sessionDied", {
+            value: true,
+            enumerable: false,
+            configurable: true,
+        });
+    }
     return contextReport;
 }
+// Context fields runContext mutates non-idempotently: `openApi` appends the
+// config's definitions, and `browser` narrows to a fallback engine/headless
+// mode. A retry re-invokes runContext, so these are snapshotted and restored
+// before each attempt (`__display`/`__displaySize` too, so a retry re-resolves
+// them rather than reusing a stale display) — everything else runContext derives
+// fresh (contextReport is rebuilt each call; step IDs assign idempotently).
+const RUN_CONTEXT_MUTATED_KEYS = ["openApi", "browser", "__display", "__displaySize"];
+// SHALLOW clone — one level. Sufficient for the current RUN_CONTEXT_MUTATED_KEYS
+// (`openApi` entries are appended, never mutated in place; `browser`/`__display*`
+// are flat). If a future mutated field nests a value that runContext mutates *in
+// place*, the snapshot and the live context would share that nested reference and
+// restore wouldn't protect it — deepen this (or that key's snapshot) then.
+function cloneMutable(value) {
+    if (Array.isArray(value))
+        return [...value];
+    if (value && typeof value === "object")
+        return { ...value };
+    return value;
+}
+// Runs a context and retries the WHOLE context on a fresh session when its
+// session dies mid-run — an early step passes, then a later step fails on a
+// now-dead session (WebDriver ECONNREFUSED / invalid session id, or an element
+// that can't be found because the DOM is dead). Bounded by the resolved
+// `retries` policy (config/context, default 1). Detection is runContext's active
+// liveness probe, surfaced as the non-enumerable `_sessionDied` flag on a FAIL
+// report, so a live-session assertion FAIL is NEVER retried — a real bug still
+// fails all attempts. Retrying re-invokes runContext, which re-runs setup,
+// re-provisions every session, and restarts recordings cleanly; the job keeps
+// its concurrency slot and any exclusive resource (display / native-app-driver /
+// android-emulator), so only the Appium pool port churns. `runContextFn` is
+// injectable for unit testing. Exported for that test.
+async function runContextWithRetries(args, runContextFn = runContext, 
+// Backoff before each retry. Injectable so unit tests pass `() => 0` instead
+// of paying the real 500ms-per-attempt sleep.
+delayMs = (attempt) => 500 * (attempt + 1)) {
+    const { context, config } = args;
+    // Time each attempt here rather than inside runContext: runContext has a
+    // dozen exits (eleven early `requires`/preflight SKIPPED returns plus the
+    // normal one), and this wrapper is its only caller, so one clock here stamps
+    // every one of them. A retried context keeps the FINAL attempt's elapsed
+    // time — the attempt the reported `result` describes (ADR 01083).
+    const timedRunContext = async (a) => {
+        const start = Date.now();
+        const report = await runContextFn(a);
+        if (report && typeof report === "object") {
+            report.durationMs = Date.now() - start;
+        }
+        return report;
+    };
+    const retries = resolveRetryPolicy({ context, config });
+    if (!(retries > 0))
+        return timedRunContext(args);
+    // Snapshot the non-idempotent context fields so each retry starts from the
+    // originally-requested state instead of the prior attempt's narrowed one.
+    const had = {};
+    const snapshot = {};
+    for (const key of RUN_CONTEXT_MUTATED_KEYS) {
+        had[key] = key in context;
+        if (had[key])
+            snapshot[key] = cloneMutable(context[key]);
+    }
+    const restore = () => {
+        for (const key of RUN_CONTEXT_MUTATED_KEYS) {
+            if (!had[key])
+                delete context[key];
+            else
+                context[key] = cloneMutable(snapshot[key]);
+        }
+    };
+    let report;
+    let attempt = 0;
+    for (;; attempt++) {
+        report = await timedRunContext(args);
+        const retryable = report?.result === "FAIL" && report?._sessionDied === true;
+        if (!retryable || attempt >= retries)
+            break;
+        log(config, "warning", `Context '${context?.contextId}' session died mid-run; retrying on a fresh session (attempt ${attempt + 2} of ${retries + 1}).`);
+        restore();
+        // Linear backoff (mirrors driverStart's session-creation retry) so a
+        // transient runner blip has a moment to clear before the fresh session.
+        await new Promise((resolve) => setTimeout(resolve, delayMs(attempt)));
+    }
+    // Surface how many retries were spent, so a report consumer can tell a clean
+    // PASS from one recovered after a mid-run session death (the warning log alone
+    // isn't machine-readable). Stamped only when a retry actually happened.
+    if (attempt > 0 && report && typeof report === "object") {
+        report.retries = attempt;
+    }
+    return report;
+}
 // Every live session driver in the context, falling back to the lone default
 // driver when no registry exists (driver-start throw, or a driverless
 // context). Recording sweeps iterate this — recordings live per session.
@@ -4156,6 +4381,10 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
             description: "Stopping recording",
             stepId: randomUUID(),
         };
+        // These sweep steps really execute, so they carry a measured duration
+        // rather than the Phase-3 zero default. Timed in both the success and the
+        // failure path, so a stop that hangs before throwing still shows its cost.
+        const stopStart = Date.now();
         try {
             const stepResult = await runStep({
                 config,
@@ -4170,7 +4399,11 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
             delete stepResult.description;
             // Don't leak the internal routing marker into the report.
             delete stopRecordStep.__stopAny;
-            contextReport.steps.push({ ...stopRecordStep, ...stepResult });
+            contextReport.steps.push({
+                ...stopRecordStep,
+                ...stepResult,
+                durationMs: Date.now() - stopStart,
+            });
         }
         catch (error) {
             // A throw from runStep would otherwise strand the remaining handles.
@@ -4181,12 +4414,13 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
                 ...stopRecordStep,
                 result: "FAIL",
                 resultDescription: `Couldn't stop recording. ${error?.message ?? error}`,
+                durationMs: Date.now() - stopStart,
             });
         }
     }
 }
 // Run a specific step
-async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {}, processRegistry, appSession, }) {
+async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {}, processRegistry, appSession, surfaceTracker, }) {
     let actionResult;
     // Load values from environment variables
     step = replaceEnvs(step);
@@ -4196,6 +4430,8 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             step: step,
             driver: driver,
             appSession,
+            processRegistry,
+            surfaceTracker,
         });
     }
     else if (typeof step.dragAndDrop !== "undefined") {
@@ -4209,7 +4445,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
         actionResult = await checkLink({ config: config, step: step });
     }
     else if (typeof step.find !== "undefined") {
-        actionResult = await findElement({ config: config, step: step, driver, appSession });
+        actionResult = await findElement({ config: config, step: step, driver, appSession, processRegistry, surfaceTracker });
     }
     else if (typeof step.stopRecord !== "undefined") {
         actionResult = await stopRecording({
@@ -4344,6 +4580,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
                 appSession,
                 driver,
                 processRegistry,
+                surfaceTracker,
                 platform: context?.platform ?? "",
                 serverDeps: {
                     startServer: async (appiumEntry, appiumHome) => {
@@ -4412,6 +4649,8 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             step: step,
             driver: driver,
             appSession,
+            processRegistry,
+            surfaceTracker,
             annotationTheme: options?.annotationTheme,
         });
     }
@@ -4429,6 +4668,8 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             step: step,
             driver: driver,
             appSession,
+            processRegistry,
+            surfaceTracker,
         });
     }
     else if (typeof step.type !== "undefined") {
@@ -4438,6 +4679,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             driver: driver,
             processRegistry,
             appSession,
+            surfaceTracker,
         });
     }
     else if (typeof step.wait !== "undefined") {