doc-detective 4.25.1 → 4.26.0

package/dist/core/tests.js

@@ -11,7 +11,7 @@ import fs from "node:fs";
 import { loadHeavyDep, resolveHeavyDepPath } from "../runtime/loader.js";
 import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/browsers.js";
 // Single source of truth for browser/driver-requiring step keys.
-import { BROWSER_STEP_KEYS as driverActions } from "../runtime/browserStepKeys.js";
+import { BROWSER_STEP_KEYS as driverActions, startSurfaceDescriptors, stepOpensBrowserSurface, } from "../runtime/browserStepKeys.js";
 import os from "node:os";
 import { log, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, } from "./utils.js";
 import axios from "axios";
@@ -34,7 +34,8 @@ 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 { createAppSessionState, appSurfacePreflight, isAppDriverRequired, stepTargetsAppSurface, teardownAppSession, } from "./tests/appSurface.js";
+import { startSurfaceStep } from "./tests/startSurface.js";
 import { isMobileTargetPlatform } from "./tests/mobilePlatform.js";
 import { mobileBrowserGate, buildMobileBrowserCapabilities, } from "./tests/mobileBrowser.js";
 import { getCacheDir } from "../runtime/cacheDir.js";
@@ -300,6 +301,10 @@ function isDriverRequired({ test }) {
             if (typeof step[action] !== "undefined")
                 driverRequired = true;
         });
+        // A startSurface browser descriptor opens a WebDriver session (Phase 6);
+        // app/process descriptors provision their own runtimes and don't count.
+        if (stepOpensBrowserSurface(step))
+            driverRequired = true;
     });
     return driverRequired;
 }
@@ -446,8 +451,11 @@ 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));
+        ((driverActions.some((action) => typeof step[action] !== "undefined") &&
+            !stepTargetsAppSurface(step)) ||
+            // Phase 6: `startSurface: { browser: … }` opens a browser session
+            // (the goTo-opener sibling); app/process descriptors don't.
+            stepOpensBrowserSurface(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 —
@@ -478,14 +486,19 @@ function contextRequirementsSkipMessage({ context, deps, }) {
         return null;
     return `Skipping context on '${context.platform}': unmet requirements — ${missing.join(", ")}.`;
 }
-// The device descriptors a test needs: each startSurface's `device` (undefined
-// when it omits one — the context default / auto device). At least one entry so
-// a test with no explicit device still validates the default device.
-function collectDeviceDescriptors(context) {
+// The device descriptors a test needs: each APP startSurface descriptor's
+// `device` (undefined when it omits one — the context default / auto device),
+// across both the object form and the Phase 6 parallel array form. Browser /
+// process descriptors boot no device and contribute nothing. At least one
+// entry so a test with no explicit device still validates the default device.
+// Exported for a focused unit test.
+export function collectDeviceDescriptors(context) {
     const out = [];
     for (const step of context?.steps ?? []) {
-        if (step?.startSurface)
-            out.push(step.startSurface.device);
+        for (const d of startSurfaceDescriptors(step)) {
+            if (d && typeof d === "object" && typeof d.app === "string")
+                out.push(d.device);
+        }
     }
     return out.length ? out : [undefined];
 }
@@ -2956,18 +2969,34 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 downloadDir: browserDownloadDir(context.contextId),
             };
             // Start a session for one engine, headed first then (on failure) headless.
-            const startDriverForBrowser = async (browserName) => {
-                const wantHeadless = context.browser?.headless !== false;
-                const buildCaps = (headless) => getDriverCapabilities({
-                    runnerDetails,
-                    name: browserName,
-                    options: {
-                        width: context.browser?.window?.width || 1200,
-                        height: context.browser?.window?.height || 800,
-                        headless,
-                        ...recordOptions,
-                    },
-                });
+            // `overrides` carries a startSurface browser descriptor's launch knobs
+            // (Phase 6): explicit headless wins over the context setting, `size`
+            // wins over the context window dimensions, and `driverOptions` merges
+            // into the computed capabilities last (the app branch's escape-hatch
+            // precedent).
+            const startDriverForBrowser = async (browserName, overrides) => {
+                const wantHeadless = overrides?.headless !== undefined
+                    ? overrides.headless
+                    : context.browser?.headless !== false;
+                const buildCaps = (headless) => {
+                    const caps = getDriverCapabilities({
+                        runnerDetails,
+                        name: browserName,
+                        options: {
+                            width: overrides?.size?.width ||
+                                context.browser?.window?.width ||
+                                1200,
+                            height: overrides?.size?.height ||
+                                context.browser?.window?.height ||
+                                800,
+                            headless,
+                            ...recordOptions,
+                        },
+                    });
+                    if (overrides?.driverOptions)
+                        Object.assign(caps, overrides.driverOptions);
+                    return caps;
+                };
                 const startFailure = () => {
                     let error = `Failed to start context '${browserName}' on '${platform}'.`;
                     if (browserName === "safari" || browserName === "webkit") {
@@ -3102,8 +3131,8 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
             // stamps driver.state.engine and back-links driver.state.sessionRegistry.
             if (driver) {
                 browserSessions = createSessionRegistry({
-                    open: async (engine) => {
-                        const res = await startDriverForBrowser(engine);
+                    open: async (engine, overrides) => {
+                        const res = await startDriverForBrowser(engine, overrides);
                         if (!res.ok)
                             throw new Error(res.error);
                         return res.driver;
@@ -3781,17 +3810,17 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
         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({
+        {
+            // Multi-surface Phase 6: startSurfaceStep dispatches app / browser /
+            // process descriptors (and the parallel array form). The app lane
+            // FAILs per descriptor when no app session was preflighted; browser
+            // descriptors ride the context's session registry via `driver`.
+            actionResult = await startSurfaceStep({
                 config: config,
                 step: step,
                 appSession,
+                driver,
+                processRegistry,
                 platform: context?.platform ?? "",
                 serverDeps: {
                     startServer: async (appiumEntry, appiumHome) => {