doc-detective 4.19.0 → 4.20.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, } from "./utils.js";
+import { log, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, } from "./utils.js";
 import axios from "axios";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
@@ -33,6 +33,7 @@ import { httpRequest } from "./tests/httpRequest.js";
 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 { runBrowserScript } from "./tests/runBrowserScript.js";
 import { dragAndDropElement } from "./tests/dragAndDrop.js";
 import { createSessionRegistry, registerSession, activeDriver, sweepSessions, } from "./tests/browserSessions.js";
@@ -49,7 +50,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, 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, };
 // exports.appiumStart = appiumStart;
 // exports.appiumIsReady = appiumIsReady;
 // exports.driverStart = driverStart;
@@ -319,6 +320,48 @@ function isSupportedContext({ context, apps, platform }) {
     // Return boolean
     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).
+function isBrowserRequired({ test }) {
+    if (!Array.isArray(test?.steps))
+        return false;
+    return test.steps.some((step) => !step?.__autoRecord &&
+        driverActions.some((action) => typeof step[action] !== "undefined") &&
+        !stepTargetsAppSurface(step));
+}
+// Size the browser Appium server pool: the number of concurrent runner jobs
+// that will actually create a BROWSER session. App-only jobs are excluded —
+// they provision their own per-context Appium server (homed where the native
+// driver resolves), so counting them here would start an idle browser server
+// (and, on Linux, an unused Xvfb display). Using isBrowserRequired keeps this
+// count in lockstep with the per-context acquire predicate. Exported for a
+// focused unit test; the deep pool wiring is exercised end-to-end by CI.
+export function browserJobCount(jobs) {
+    if (!Array.isArray(jobs))
+        return 0;
+    return jobs.filter((job) => isBrowserRequired({ test: job?.context }))
+        .length;
+}
+// Evaluate a context's `requires` capability gate. Returns null when the gate
+// is absent or fully met; otherwise a skip message naming every unmet
+// requirement, so the context lands as SKIPPED (the same non-failing outcome
+// as a `platforms` mismatch). `deps` is passed through to
+// evaluateContextRequirements for hermetic tests.
+function contextRequirementsSkipMessage({ context, deps, }) {
+    if (context?.requires === undefined || context?.requires === null)
+        return null;
+    const { met, missing } = evaluateContextRequirements({
+        requires: context.requires,
+        deps,
+    });
+    if (met)
+        return null;
+    return `Skipping context on '${context.platform}': unmet requirements — ${missing.join(", ")}.`;
+}
 function getDefaultBrowser({ runnerDetails }) {
     let browser = {};
     const browserNames = ["firefox", "chrome", "safari"];
@@ -913,12 +956,14 @@ async function runSpecs({ resolvedTests }) {
     else if (concurrency.overlappingCaptures && limit > 1) {
         log(config, "warning", "autoRecord is running ffmpeg recordings concurrently on a shared display, so the captured videos will overlap (each context records the whole screen). For isolated concurrent recordings, run on Linux with Xvfb installed.");
     }
-    // Start one Appium server per concurrent runner that will actually use a
-    // driver (capped at the number of driver contexts). Each server owns a
-    // distinct port, so parallel contexts never create sessions on the same
-    // server — that contention crashed ChromeDriver when every context shared
-    // one server. Non-driver runs start none.
-    const driverJobCount = sizingJobs.filter((job) => isDriverRequired({ test: job.context })).length;
+    // Start one Appium server per concurrent runner that will actually create a
+    // BROWSER session (capped at the number of browser contexts). Each server
+    // owns a distinct port, so parallel contexts never create sessions on the
+    // same server — that contention crashed ChromeDriver when every context
+    // shared one server. App-only contexts run on their own per-context server
+    // (see startAppSurface) and are excluded here, so an app-only run starts no
+    // browser server. Non-driver runs start none.
+    const browserPoolJobCount = browserJobCount(sizingJobs);
     let appiumServers = [];
     let appiumPool;
     // Per-server virtual displays (Linux Xvfb) for concurrent ffmpeg recording,
@@ -927,7 +972,7 @@ async function runSpecs({ resolvedTests }) {
     const xvfbProcesses = [];
     const useXvfbDisplays = concurrency.xvfbContexts.length > 0;
     let portToDisplay;
-    if (driverJobCount > 0) {
+    if (browserPoolJobCount > 0) {
         setAppiumHome({ cacheDir: config?.cacheDir });
         // Resolve appium's actual JS entrypoint via `require.resolve` (shim
         // node_modules first, runtime cache second) and invoke it with
@@ -942,7 +987,7 @@ async function runSpecs({ resolvedTests }) {
         if (!appiumEntry) {
             throw new Error("appium is not installed. The runtime pre-flight should have installed it; check DOC_DETECTIVE_CACHE_DIR / config.cacheDir or run `doc-detective install runtime appium`.");
         }
-        const serverCount = Math.min(limit, driverJobCount);
+        const serverCount = Math.min(limit, browserPoolJobCount);
         log(config, "debug", `Starting ${serverCount} Appium server(s).`);
         // Start servers one at a time rather than all at once: concurrent
         // findFreePort() calls share a close-to-rebind window (two could hand out
@@ -1565,10 +1610,14 @@ function selectWarmUpTargets(jobs, runnerDetails) {
         // would defeat the warm-up/install de-racing the pre-pass exists for.
         if (!context.platform)
             context.platform = platform;
-        if (!context.browser && isDriverRequired({ test: context })) {
+        // 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
+        // written onto their context. Mirrors the browser pool sizing.
+        if (!context.browser && isBrowserRequired({ test: context })) {
             context.browser = getDefaultBrowser({ runnerDetails });
         }
-        if (!isDriverRequired({ test: context }))
+        if (!isBrowserRequired({ test: context }))
             continue;
         // No resolvable browser — runContext skips these per-context with its own
         // message; nothing to warm up.
@@ -2038,8 +2087,11 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             ...config.integrations.openApi,
         ];
     }
-    // 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
-    if (!context.browser && isDriverRequired({ test: context })) {
+    // 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 })) {
         context.browser = getDefaultBrowser({ runnerDetails });
     }
     // Set context report
@@ -2051,11 +2103,45 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     };
     // Set meta values (create-if-missing — ids aren't guaranteed unique)
     metaValues.specs[spec.specId].tests[test.testId].contexts[context.contextId] ??= { steps: {} };
+    // `requires` capability gate: any unmet requirement skips the context with a
+    // message naming what's missing. Evaluated only on the platform the context
+    // targets — a different-platform context keeps its platform skip reason, and
+    // requirements are host facts that would be meaningless to probe elsewhere.
+    if (context.platform === platform) {
+        const requirementsSkip = contextRequirementsSkipMessage({ context });
+        if (requirementsSkip) {
+            clog("warning", requirementsSkip);
+            contextReport.result = "SKIPPED";
+            contextReport.resultDescription = requirementsSkip;
+            return contextReport;
+        }
+    }
+    // App-surface preflight (native app phase A1): when the test provisions or
+    // targets app surfaces, verify the platform supports them and the native
+    // driver is (or can be) installed. Unmet -> SKIPPED with the reason, same
+    // gating semantics as `requires`. On success, the context gets an app
+    // session primed with the resolved Appium entry/home for the app server.
+    // Scoped to the current platform like the `requires` gate above: a context
+    // targeting another platform must skip with the platform-mismatch reason,
+    // not pay (or misreport) a driver-install attempt on this host.
+    let appSession;
+    if (context.platform === platform && isAppDriverRequired({ test: context })) {
+        const preflight = await appSurfacePreflight({ config, platform });
+        if (!preflight.ok) {
+            clog("warning", preflight.reason);
+            contextReport.result = "SKIPPED";
+            contextReport.resultDescription = preflight.reason;
+            return contextReport;
+        }
+        appSession = createAppSessionState();
+        appSession.appiumEntry = preflight.appiumEntry;
+        appSession.appiumHome = preflight.appiumHome;
+    }
     // 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
     // letting it fail later as "Failed to start context 'undefined'".
-    if (isDriverRequired({ test: context }) && !context.browser?.name) {
+    if (isBrowserRequired({ test: context }) && !context.browser?.name) {
         const errorMessage = `Skipping context on '${context.platform}': no supported browser is available in the current environment.`;
         clog("warning", errorMessage);
         contextReport.result = "SKIPPED";
@@ -2133,7 +2219,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     // Context-level browserFallback (authored on the runOn entry) overrides the
     // config-level policy; config defaults to "auto".
     const fallbackPolicy = resolveBrowserFallbackPolicy({ context, config });
-    const driverRequired = isDriverRequired({ test: context });
+    // Browser-required (not app): app-targeted steps run on the app session.
+    const driverRequired = isBrowserRequired({ test: context });
     const candidateEngines = platformMatches && driverRequired
         ? buildFallbackCandidates({
             requestedName: requestedBrowserName,
@@ -2185,8 +2272,9 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
     let fellBackNote = "";
     let fellBackPinned = false;
     if (driverRequired && !appiumPool) {
-        throw new Error("Driver requested but no Appium server pool was created; " +
-            "driverJobCount and isDriverRequired(context) disagreed; this is a bug.");
+        throw new Error("Browser driver requested but no Appium server pool was created; " +
+            "the pool sizing (browserJobCount) and this context's isBrowserRequired " +
+            "predicate disagreed; this is a bug.");
     }
     try {
         if (driverRequired) {
@@ -2605,6 +2693,7 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                         openApiDefinitions: context.openApi || [],
                     },
                     processRegistry: processRegistry,
+                    appSession: appSession,
                 });
                 clog("debug", `RESULT: ${r.status}\n${JSON.stringify(r, null, 2)}`);
                 r.result = r.status;
@@ -2740,10 +2829,19 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
         // Stop every recording still active at the end of the context (the
         // synthetic autoRecord capture plus any explicit record steps the author
         // didn't stop). Each produces an ordered stopRecord step report.
-        // Recordings live per session, so sweep every registered driver.
+        // Recordings live per session, so sweep every registered driver — and the
+        // app session's recordingHost, which holds app-only-context recordings.
         for (const d of sessionDrivers(browserSessions, driver)) {
             await stopAllRecordings({ config, context, driver: d, contextReport });
         }
+        if (appSession?.recordingHost.state.recordings.length) {
+            await stopAllRecordings({
+                config,
+                context,
+                driver: appSession.recordingHost,
+                contextReport,
+            });
+        }
     }
     finally {
         // Safety net: if the context threw before the normal sweep above, recordings
@@ -2759,6 +2857,14 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             for (const d of sessionDrivers(browserSessions, driver)) {
                 await stopAllRecordings({ config, context, driver: d, contextReport });
             }
+            if (appSession?.recordingHost.state.recordings.length) {
+                await stopAllRecordings({
+                    config,
+                    context,
+                    driver: appSession.recordingHost,
+                    contextReport,
+                });
+            }
         }
         catch (error) {
             clog("error", `Failed to stop recordings during cleanup: ${error?.message ?? error}`);
@@ -2780,6 +2886,27 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 clog("error", `Failed to delete driver session: ${error.message}`);
             }
         }
+        // Tear down app surfaces: close every remaining app session (the driver
+        // terminates apps it launched) and stop the app Appium server. Tree-kill
+        // in callback form so the server process is actually gone before the
+        // context returns (mirrors the run-level killTree closure in runSpecs).
+        if (appSession) {
+            try {
+                await teardownAppSession(appSession, (pid) => new Promise((resolve) => {
+                    if (!pid)
+                        return resolve();
+                    try {
+                        kill(pid, "SIGTERM", () => resolve());
+                    }
+                    catch {
+                        resolve();
+                    }
+                }));
+            }
+            catch (error) {
+                clog("error", `Failed to tear down app surfaces: ${error?.message ?? error}`);
+            }
+        }
         // Return the Appium server to the pool for the next queued context. Always
         // runs (even on the driver-start-failure early return) so a port can't
         // leak out of the pool and starve later contexts.
@@ -2867,7 +2994,7 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
     }
 }
 // Run a specific step
-async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {}, processRegistry, }) {
+async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {}, processRegistry, appSession, }) {
     let actionResult;
     // Load values from environment variables
     step = replaceEnvs(step);
@@ -2876,6 +3003,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             config: config,
             step: step,
             driver: driver,
+            appSession,
         });
     }
     else if (typeof step.dragAndDrop !== "undefined") {
@@ -2889,10 +3017,15 @@ 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 });
+        actionResult = await findElement({ config: config, step: step, driver, appSession });
     }
     else if (typeof step.stopRecord !== "undefined") {
-        actionResult = await stopRecording({ config: config, step: step, driver });
+        actionResult = await stopRecording({
+            config: config,
+            step: step,
+            // App-only contexts keep recordings on the app session's host.
+            driver: driver ?? appSession?.recordingHost,
+        });
     }
     else if (typeof step.goTo !== "undefined") {
         actionResult = await goTo({ config: config, step: step, driver: driver });
@@ -2922,24 +3055,51 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
         });
     }
     else if (typeof step.record !== "undefined") {
+        // App-only contexts have no browser driver: recordings live on the app
+        // session's recordingHost (same `.state.recordings` shape) instead.
+        // Threaded into startRecording too, so its already-recording dedupe
+        // checks consult the same store this block pushes into.
+        const recordingHost = driver ?? appSession?.recordingHost;
         actionResult = await startRecording({
             config: config,
             context: context,
             step: step,
             driver: driver,
+            recordingHost,
         });
         // Push the started recording onto the per-context stack so several can
         // overlap. Carry the step's `id`/`name` so a later stopRecord can target
         // it (by name) and end-of-context cleanup can identify the synthetic one.
-        if (actionResult.recording) {
-            if (!Array.isArray(driver.state.recordings))
-                driver.state.recordings = [];
+        if (actionResult.recording && !recordingHost) {
+            // Defensive: no driver session AND no app session — nowhere to track
+            // the handle, so the end-of-context sweep could never stop it. Kill
+            // the capture now and FAIL loudly rather than leak the process.
+            try {
+                actionResult.recording.process?.kill?.();
+            }
+            catch {
+                // best-effort
+            }
+            delete actionResult.recording;
+            actionResult.status = "FAIL";
+            actionResult.description =
+                "A recording started with no driver session or app session to own it; it was stopped. This context cannot record.";
+        }
+        else if (actionResult.recording) {
+            if (!Array.isArray(recordingHost.state.recordings))
+                recordingHost.state.recordings = [];
             const handle = actionResult.recording;
             handle.id = handle.id ?? randomUUID();
             handle.name = handle.name ?? recordStepName(step.record);
-            if (step.__autoRecord)
+            if (step.__autoRecord) {
                 handle.synthetic = true;
-            driver.state.recordings.push(handle);
+                // App-only context: no window exists yet to crop to. Mark the handle
+                // so the first app surface to open late-binds its window rect as the
+                // crop (startAppSurface), scoping the capture to the app under test.
+                if (!driver && appSession)
+                    handle.pendingAppWindowCrop = true;
+            }
+            recordingHost.state.recordings.push(handle);
         }
     }
     else if (typeof step.runCode !== "undefined") {
@@ -2956,13 +3116,43 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
         actionResult = await runShell({ config: config, step: step, driver, processRegistry });
     }
     else if (typeof step.closeSurface !== "undefined") {
-        actionResult = await closeSurface({ config: config, step: step, driver, processRegistry });
+        actionResult = await closeSurface({ config: config, step: step, driver, processRegistry, appSession });
+    }
+    else if (typeof step.startSurface !== "undefined") {
+        if (!appSession) {
+            actionResult = {
+                status: "FAIL",
+                description: "startSurface ran without an app session; this is a runner bug (runContext must preflight app-driver tests).",
+            };
+        }
+        else {
+            actionResult = await startAppSurface({
+                config: config,
+                step: step,
+                appSession,
+                platform: context?.platform ?? "",
+                serverDeps: {
+                    startServer: async (appiumEntry, appiumHome) => {
+                        // APPIUM_HOME points the server at the node_modules that holds
+                        // the native driver (shim or runtime cache). The preflight has
+                        // already invalidated a stale extensions manifest there, so the
+                        // server's startup scan discovers the driver.
+                        const server = await startAppiumServer(appiumEntry, config, undefined, {
+                            APPIUM_HOME: appiumHome,
+                        });
+                        return { port: server.port, process: server.process };
+                    },
+                    startDriver: (capabilities, port) => driverStart(capabilities, port, 2, { cacheDir: config?.cacheDir }),
+                },
+            });
+        }
     }
     else if (typeof step.screenshot !== "undefined") {
         actionResult = await saveScreenshot({
             config: config,
             step: step,
             driver: driver,
+            appSession,
         });
     }
     else if (typeof step.type !== "undefined") {
@@ -2971,6 +3161,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             step: step,
             driver: driver,
             processRegistry,
+            appSession,
         });
     }
     else if (typeof step.wait !== "undefined") {
@@ -2982,8 +3173,10 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             description: `Unknown step action: ${JSON.stringify(step)}`,
         };
     }
-    // If recording, wait until browser is loaded, then instantiate cursor
-    if (isRecordingActive(driver)) {
+    // If recording, wait until browser is loaded, then instantiate cursor.
+    // The `getUrl` guard skips the synthetic-cursor dance when `driver` is the
+    // app session's recordingHost (a bare state holder, not a browser session).
+    if (isRecordingActive(driver) && typeof driver.getUrl === "function") {
         const currentUrl = await driver.getUrl();
         if (currentUrl !== driver.state.url) {
             driver.state.url = currentUrl;
@@ -3031,13 +3224,21 @@ 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) {
+async function startAppiumServer(appiumEntry, config, display, extraEnv) {
     const port = await findFreePort();
     log(config, "debug", `Starting Appium on port ${port}`);
     // When a virtual display is supplied (Linux Xvfb recording), launch the
     // server with DISPLAY set so the browser it spawns (via chromedriver)
     // renders on that display — which is what ffmpeg x11grab then captures.
-    const env = display ? { ...process.env, DISPLAY: display } : process.env;
+    // `extraEnv` overrides (e.g. APPIUM_HOME for the app-surface server, which
+    // must be homed where the lazily-installed native driver lives).
+    const env = display || extraEnv
+        ? {
+            ...process.env,
+            ...(display ? { DISPLAY: display } : {}),
+            ...(extraEnv ?? {}),
+        }
+        : process.env;
     const proc = spawn(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port)], {
         windowsHide: true,
         cwd: path.join(__dirname, "../.."),