doc-detective 4.7.0 → 4.8.0

package/dist/index.cjs

@@ -130089,6 +130089,44 @@ var init_validate = __esm({
 });
 
 // dist/core/utils.js
+function createAppiumPool(ports) {
+  const available = [...ports];
+  const waiters = [];
+  return {
+    acquire() {
+      const port = available.shift();
+      if (port !== void 0)
+        return Promise.resolve(port);
+      return new Promise((resolve) => waiters.push(resolve));
+    },
+    release(port) {
+      const next = waiters.shift();
+      if (next)
+        next(port);
+      else
+        available.push(port);
+    }
+  };
+}
+async function runConcurrent(items, limit, fn) {
+  let next = 0;
+  const workerCount = Math.max(1, Math.min(Math.floor(limit) || 1, items.length));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (next < items.length) {
+      await fn(items[next++]);
+    }
+  });
+  await Promise.all(workers);
+}
+function rollUpResults(children) {
+  if (children.some((child) => child.result === "FAIL"))
+    return "FAIL";
+  if (children.some((child) => child.result === "WARNING"))
+    return "WARNING";
+  if (children.every((child) => child.result === "SKIPPED"))
+    return "SKIPPED";
+  return "PASS";
+}
 async function findFreePort() {
   return new Promise((resolve, reject) => {
     const server = import_node_net.default.createServer();
@@ -131001,12 +131039,27 @@ var init_loader = __esm({
 });
 
 // dist/core/appium.js
+function appiumHomeForDriverPath(driverEntry) {
+  const marker = `${import_node_path5.default.sep}node_modules${import_node_path5.default.sep}`;
+  const idx = driverEntry.lastIndexOf(marker);
+  return idx === -1 ? null : driverEntry.slice(0, idx);
+}
 function setAppiumHome(ctx = {}) {
   const runtimeAppium = import_node_path5.default.join(getRuntimeDir({ cacheDir: ctx.cacheDir }), "node_modules", "appium");
   if ((0, import_node_fs5.existsSync)(runtimeAppium)) {
     process.env.APPIUM_HOME = import_node_path5.default.join(getRuntimeDir({ cacheDir: ctx.cacheDir }));
     return;
   }
+  for (const driverName of ["appium-chromium-driver", "appium-geckodriver"]) {
+    const driverEntry = resolveHeavyDepPath(driverName, {
+      cacheDir: ctx.cacheDir
+    });
+    const home = driverEntry ? appiumHomeForDriverPath(driverEntry) : null;
+    if (home) {
+      process.env.APPIUM_HOME = home;
+      return;
+    }
+  }
   const corePath = import_node_path5.default.join(__dirname3, "../../node_modules");
   const pathArray = corePath.split("node_modules");
   let appiumParentPath = pathArray[0];
@@ -131026,6 +131079,7 @@ var init_appium = __esm({
     import_node_fs5 = require("node:fs");
     import_node_url4 = require("node:url");
     init_cacheDir();
+    init_loader();
     __dirname3 = import_node_path5.default.dirname((0, import_node_url4.fileURLToPath)(importMetaUrl));
   }
 });
@@ -131604,9 +131658,10 @@ async function setConfig({ config }) {
 }
 function resolveConcurrentRunners(config) {
   if (config.concurrentRunners === true) {
-    return Math.min(import_node_os3.default.cpus().length, 4);
+    return Math.max(1, Math.min(import_node_os3.default.cpus().length, 4));
   }
-  return config.concurrentRunners ?? 1;
+  const runners = Math.floor(Number(config.concurrentRunners));
+  return Number.isFinite(runners) && runners >= 1 ? runners : 1;
 }
 async function loadDescriptions(config) {
   if (config?.integrations?.openApi) {
@@ -132154,8 +132209,19 @@ var browsers_exports = {};
 __export(browsers_exports, {
   BROWSER_CHANNELS: () => BROWSER_CHANNELS,
   ensureBrowserInstalled: () => ensureBrowserInstalled,
-  getInstalledBrowsers: () => getInstalledBrowsers
+  getInstalledBrowsers: () => getInstalledBrowsers,
+  requiredBrowserAssets: () => requiredBrowserAssets
 });
+function requiredBrowserAssets(name) {
+  switch ((name ?? "").toLowerCase()) {
+    case "chrome":
+      return ["chrome", "chromedriver"];
+    case "firefox":
+      return ["firefox", "geckodriver"];
+    default:
+      return [];
+  }
+}
 async function loadPuppeteerBrowsers(deps, ctx) {
   if (deps.browsersModule)
     return deps.browsersModule;
@@ -135110,6 +135176,7 @@ init_utils();
 // dist/core/tests.js
 var import_tree_kill = __toESM(require("tree-kill"), 1);
 init_loader();
+init_browsers();
 var import_node_os8 = __toESM(require("node:os"), 1);
 init_utils();
 var import_axios6 = __toESM(require("axios"), 1);
@@ -135787,7 +135854,7 @@ async function typeKeys({ config, step, driver }) {
       return result;
     }
   }
-  if (config.recording) {
+  if (driver?.state?.recording) {
     let keys = [];
     step.type.keys.forEach((key) => {
       if (key.startsWith("$") && key.endsWith("$")) {
@@ -135817,7 +135884,7 @@ async function typeKeys({ config, step, driver }) {
     });
   }
   try {
-    if (config.recording) {
+    if (driver?.state?.recording) {
       for (let i = 0; i < step.type.keys.length; i++) {
         await driver.keys(step.type.keys[i]);
         await new Promise((resolve) => setTimeout(resolve, step.type.inputDelay));
@@ -135981,7 +136048,7 @@ async function findElement({ config, step, driver, click }) {
       result.description += " Typed keys.";
     }
   }
-  if (config.recording) {
+  if (driver?.state?.recording) {
     await wait({ config, step: { wait: 2e3 }, driver });
   }
   return result;
@@ -136883,13 +136950,13 @@ async function saveScreenshot({ config, step, driver }) {
     await driver.pause(100);
   }
   try {
-    if (config.recording) {
+    if (driver?.state?.recording) {
       await driver.execute(() => {
         document.querySelector("dd-mouse-pointer").style.display = "none";
       });
     }
     await driver.saveScreenshot(filePath);
-    if (config.recording) {
+    if (driver?.state?.recording) {
       await driver.execute(() => {
         document.querySelector("dd-mouse-pointer").style.display = "block";
       });
@@ -137124,7 +137191,6 @@ async function startRecording({ config, context, step, driver }) {
     return result;
   }
   if (context?.browser?.name === "chrome" && context?.browser?.headless === false) {
-    config.recording = {};
     const documentTitle = await driver.getTitle();
     const originalTab = await driver.getWindowHandle();
     await driver.execute(() => document.title = "RECORD_ME");
@@ -137133,7 +137199,6 @@ async function startRecording({ config, context, step, driver }) {
     await driver.switchToWindow(recorderTab.handle);
     await driver.url("chrome://new-tab-page");
     await driver.execute(() => document.title = "RECORDER");
-    config.recording.tab = await driver.getWindowHandle();
     const recorderStarted = await driver.executeAsync((baseName2, done) => {
       let doneCalled = false;
       const safeDone = (value) => {
@@ -137206,7 +137271,6 @@ async function startRecording({ config, context, step, driver }) {
       captureAndDownload();
     }, baseName);
     if (!recorderStarted) {
-      config.recording = null;
       result.status = "FAIL";
       result.description = "Failed to start recording. getDisplayMedia may have been rejected. On macOS, ensure Chrome has screen recording permission in System Preferences > Privacy & Security > Screen Recording.";
       log(config, "error", result.description);
@@ -137264,14 +137328,15 @@ async function stopRecording({ config, step, driver }) {
     return result;
   }
   step = isValidStep.object;
-  if (!config.recording) {
+  const recording = driver?.state?.recording;
+  if (!recording) {
     result.status = "SKIPPED";
     result.description = `Recording isn't started.`;
     return result;
   }
   try {
-    if (config.recording.type === "MediaRecorder") {
-      await driver.switchToWindow(config.recording.tab);
+    if (recording.type === "MediaRecorder") {
+      await driver.switchToWindow(recording.tab);
       const recorderExists = await driver.execute(() => {
         return typeof window.recorder !== "undefined" && window.recorder !== null;
       });
@@ -137280,35 +137345,36 @@ async function stopRecording({ config, step, driver }) {
         result.description = "Recording was not properly started. The recorder object doesn't exist in the browser context.";
         const allHandles2 = await driver.getWindowHandles();
         await driver.closeWindow();
-        const remainingHandles2 = allHandles2.filter((h) => h !== config.recording.tab);
+        const remainingHandles2 = allHandles2.filter((h) => h !== recording.tab);
         if (remainingHandles2.length > 0) {
           await driver.switchToWindow(remainingHandles2[0]);
         }
-        config.recording = null;
+        driver.state.recording = null;
         return result;
       }
       await driver.execute(() => {
         window.recorder.stop();
       });
       let waitCount = 0;
-      while (!import_node_fs13.default.existsSync(config.recording.downloadPath) && waitCount < 60) {
+      while (!import_node_fs13.default.existsSync(recording.downloadPath) && waitCount < 60) {
         await new Promise((r) => setTimeout(r, 1e3));
         waitCount++;
       }
-      if (!import_node_fs13.default.existsSync(config.recording.downloadPath)) {
+      if (!import_node_fs13.default.existsSync(recording.downloadPath)) {
         result.status = "FAIL";
         result.description = "Recording download timed out.";
+        driver.state.recording = null;
         return result;
       }
       const allHandles = await driver.getWindowHandles();
       await driver.closeWindow();
-      const remainingHandles = allHandles.filter((h) => h !== config.recording.tab);
+      const remainingHandles = allHandles.filter((h) => h !== recording.tab);
       if (remainingHandles.length > 0) {
         await driver.switchToWindow(remainingHandles[0]);
       }
-      const targetPath = `${config.recording.targetPath}`;
-      const downloadPath = `${config.recording.downloadPath}`;
-      const endMessage = `Finished processing file: ${config.recording.targetPath}`;
+      const targetPath = `${recording.targetPath}`;
+      const downloadPath = `${recording.downloadPath}`;
+      const endMessage = `Finished processing file: ${recording.targetPath}`;
       const ffmpegArgs = ["-y", "-i", downloadPath, "-pix_fmt", "yuv420p"];
       if (import_node_path13.default.extname(targetPath) === ".gif") {
         ffmpegArgs.push("-vf", "scale=iw:-1:flags=lanczos");
@@ -137331,12 +137397,13 @@ async function stopRecording({ config, step, driver }) {
           }
         }).on("error", reject);
       });
-      config.recording = null;
+      driver.state.recording = null;
     } else {
     }
   } catch (error) {
     result.status = "FAIL";
     result.description = `Couldn't stop recording. ${error}`;
+    driver.state.recording = null;
     return result;
   }
   return result;
@@ -138873,6 +138940,14 @@ var driverActions2 = [
   "type"
 ];
 var KNOWN_BROWSERS = ["firefox", "chrome", "safari", "webkit"];
+function combinationKey(context) {
+  const rawName = context?.browser?.name;
+  const name = rawName === "webkit" ? "safari" : rawName || "<none>";
+  return `${context?.platform}::${name}`;
+}
+function warmUpDecision(prev) {
+  return prev === "failed" ? "skip" : "attempt";
+}
 function getDriverCapabilities({ runnerDetails, name, options }) {
   let capabilities = {};
   let args = [];
@@ -138936,8 +139011,10 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
         args.push(`--auto-select-desktop-capture-source=RECORD_ME`);
         if (options.headless)
           args.push("--headless", "--disable-gpu");
-        if (process.platform === "linux")
+        if (process.platform === "linux") {
           args.push("--no-sandbox");
+          args.push("--disable-dev-shm-usage");
+        }
         capabilities = {
           platformName: runnerDetails.environment.platform,
           "appium:automationName": "Chromium",
@@ -138965,22 +139042,9 @@ function getDriverCapabilities({ runnerDetails, name, options }) {
   }
   return capabilities;
 }
-function isAppiumRequired(specs) {
-  let appiumRequired = false;
-  specs.forEach((spec) => {
-    spec.tests.forEach((test) => {
-      test.contexts.forEach((context) => {
-        if (isDriverRequired({ test: context })) {
-          appiumRequired = true;
-        }
-      });
-    });
-  });
-  return appiumRequired;
-}
 function isDriverRequired({ test }) {
   let driverRequired = false;
-  test.steps.forEach((step) => {
+  (test.steps || []).forEach((step) => {
     driverActions2.forEach((action) => {
       if (typeof step[action] !== "undefined")
         driverRequired = true;
@@ -139151,9 +139215,10 @@ async function runSpecs({ resolvedTests }) {
     allowUnsafeSteps: await allowUnsafeSteps({ config })
   };
   const platform = runnerDetails.environment.platform;
-  const availableApps = runnerDetails.availableApps;
+  let availableApps = runnerDetails.availableApps;
   const metaValues = { specs: {} };
-  let appium;
+  const installAttempts = /* @__PURE__ */ new Map();
+  const warmUpResults = /* @__PURE__ */ new Map();
   const report = {
     summary: {
       specs: {
@@ -139183,293 +139248,128 @@ async function runSpecs({ resolvedTests }) {
     },
     specs: []
   };
-  const appiumRequired = isAppiumRequired(specs);
-  let appiumPort;
-  if (appiumRequired) {
-    setAppiumHome({ cacheDir: config?.cacheDir });
-    appiumPort = await findFreePort();
-    log(config, "debug", `Starting Appium on port ${appiumPort}`);
-    const appiumEntry = resolveHeavyDepPath("appium", { cacheDir: config?.cacheDir });
-    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`.");
-    }
-    appium = (0, import_node_child_process5.spawn)(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(appiumPort)], {
-      windowsHide: true,
-      cwd: import_node_path18.default.join(__dirname5, "../..")
-    });
-    appium.on("error", (err) => {
-      log(config, "warning", `Appium process error: ${err?.stack ?? err?.message ?? String(err)}`);
-    });
-    appium.stdout.on("data", (data) => {
-    });
-    appium.stderr.on("data", (data) => {
-    });
-    try {
-      await appiumIsReady(appiumPort);
-    } catch (error) {
-      try {
-        if (appium && appium.pid)
-          (0, import_tree_kill.default)(appium.pid);
-      } catch {
-      }
-      throw error;
-    }
-    log(config, "debug", "Appium is ready.");
-  }
+  const limit = resolveConcurrentRunners(config);
   log(config, "info", "Running test specs.");
+  const jobs = [];
   for (const spec of specs) {
     log(config, "debug", `SPEC: ${spec.specId}`);
-    let specReport = {
+    metaValues.specs[spec.specId] ??= { tests: {} };
+    const specReport = {
       specId: spec.specId,
       description: spec.description,
       contentPath: spec.contentPath,
       tests: []
     };
-    metaValues.specs[spec.specId] = { tests: {} };
+    report.specs.push(specReport);
     for (const test of spec.tests) {
       log(config, "debug", `TEST: ${test.testId}`);
-      let testReport = {
+      metaValues.specs[spec.specId].tests[test.testId] ??= { contexts: {} };
+      const testReport = {
         testId: test.testId,
         description: test.description,
         contentPath: test.contentPath,
         detectSteps: test.detectSteps,
-        contexts: []
+        contexts: new Array(test.contexts.length)
       };
-      metaValues.specs[spec.specId].tests[test.testId] = { contexts: {} };
-      for (const context of test.contexts) {
-        if (!context.platform)
-          context.platform = runnerDetails.environment.platform;
-        if (config.integrations?.openApi) {
-          context.openApi = [
-            ...context.openApi || [],
-            ...config.integrations.openApi
-          ];
-        }
-        if (!context.browser && isDriverRequired({ test: context })) {
-          context.browser = getDefaultBrowser({ runnerDetails });
+      specReport.tests.push(testReport);
+      test.contexts.forEach((context, slot) => {
+        context.contextId = context.contextId || (0, import_node_crypto5.randomUUID)();
+        jobs.push({ spec, test, context, contexts: testReport.contexts, slot });
+      });
+    }
+  }
+  if (limit > 1 && jobs.some((job) => job.context.steps?.some((step) => step.record !== void 0))) {
+    log(config, "warning", "Tests include record steps while concurrentRunners is greater than 1. Concurrent recordings can capture the wrong window; set concurrentRunners to 1 for recording runs.");
+  }
+  const driverJobCount = jobs.filter((job) => isDriverRequired({ test: job.context })).length;
+  let appiumServers = [];
+  let appiumPool;
+  if (driverJobCount > 0) {
+    setAppiumHome({ cacheDir: config?.cacheDir });
+    const appiumEntry = resolveHeavyDepPath("appium", {
+      cacheDir: config?.cacheDir
+    });
+    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);
+    log(config, "debug", `Starting ${serverCount} Appium server(s).`);
+    try {
+      for (let i = 0; i < serverCount; i++) {
+        appiumServers.push(await startAppiumServer(appiumEntry, config));
+      }
+    } catch (error) {
+      for (const server of appiumServers) {
+        try {
+          (0, import_tree_kill.default)(server.process.pid);
+        } catch {
         }
-        let contextReport = {
-          contextId: context.contextId || (0, import_node_crypto5.randomUUID)(),
-          platform: context.platform,
-          browser: context.browser,
+      }
+      throw error;
+    }
+    appiumPool = createAppiumPool(appiumServers.map((s) => s.port));
+  }
+  try {
+    if (limit > 1 && appiumPool) {
+      await warmUpContexts({
+        jobs,
+        config,
+        runnerDetails,
+        appiumPool,
+        installAttempts,
+        warmUpResults
+      });
+    }
+    await runConcurrent(jobs, limit, async (job) => {
+      try {
+        job.contexts[job.slot] = await runContext({
+          config,
+          spec: job.spec,
+          test: job.test,
+          context: job.context,
+          runnerDetails,
+          appiumPool,
+          metaValues,
+          installAttempts,
+          warmUpResults,
+          logPrefix: limit > 1 ? `[${job.test.testId}/${job.context.contextId}]` : ""
+        });
+      } catch (error) {
+        const detail = error?.message ?? String(error);
+        log(config, "error", `Context '${job.context.contextId}' crashed: ${detail}`);
+        job.contexts[job.slot] = {
+          contextId: job.context.contextId,
+          platform: job.context.platform,
+          browser: job.context.browser,
+          result: "FAIL",
+          resultDescription: `Unexpected error: ${detail}`,
           steps: []
         };
-        metaValues.specs[spec.specId].tests[test.testId].contexts[context.contextId] = { steps: {} };
-        if (isDriverRequired({ test: context }) && !context.browser?.name) {
-          const errorMessage = `Skipping context on '${context.platform}': no supported browser is available in the current environment.`;
-          log(config, "warning", errorMessage);
-          contextReport = {
-            ...contextReport,
-            result: "SKIPPED",
-            resultDescription: errorMessage
-          };
-          report.summary.contexts.skipped++;
-          testReport.contexts.push(contextReport);
-          continue;
-        }
-        const supportedContext = isSupportedContext({
-          context,
-          apps: availableApps,
-          platform
-        });
-        if (!supportedContext) {
-          log(config, "info", `Skipping context. The current system doesn't support this context: {"platform": "${context.platform}", "apps": ${JSON.stringify(context.apps)}}`);
-          contextReport = { result: "SKIPPED", ...contextReport };
-          report.summary.contexts.skipped++;
-          testReport.contexts.push(contextReport);
-          continue;
-        }
-        log(config, "debug", `CONTEXT:
-${JSON.stringify(context, null, 2)}`);
-        let driver;
-        if (!context.steps) {
-          context.steps = [];
-        }
-        const driverRequired = isDriverRequired({ test: context });
-        if (driverRequired) {
-          let caps = getDriverCapabilities({
-            runnerDetails,
-            name: context.browser.name,
-            options: {
-              width: context.browser?.window?.width || 1200,
-              height: context.browser?.window?.height || 800,
-              headless: context.browser?.headless !== false
-            }
-          });
-          log(config, "debug", "CAPABILITIES:");
-          log(config, "debug", caps);
-          if (appiumPort === void 0) {
-            throw new Error("Driver requested but Appium was not started. isAppiumRequired(specs) and isDriverRequired(context) disagreed; this is a bug.");
-          }
-          try {
-            driver = await driverStart(caps, appiumPort, 4, { cacheDir: config?.cacheDir });
-          } catch (error) {
-            try {
-              log(config, "warning", `Failed to start context '${context.browser?.name}' on '${platform}'. Retrying as headless.`);
-              context.browser.headless = true;
-              caps = getDriverCapabilities({
-                runnerDetails,
-                name: context.browser.name,
-                options: {
-                  width: context.browser?.window?.width || 1200,
-                  height: context.browser?.window?.height || 800,
-                  headless: context.browser?.headless !== false
-                }
-              });
-              driver = await driverStart(caps, appiumPort, 4, { cacheDir: config?.cacheDir });
-            } catch (error2) {
-              let errorMessage = `Failed to start context '${context.browser?.name}' on '${platform}'.`;
-              if (context.browser?.name === "safari")
-                errorMessage = errorMessage + " Make sure you've run `safaridriver --enable` in a terminal and enabled 'Allow Remote Automation' in Safari's Develop menu.";
-              log(config, "error", errorMessage);
-              contextReport = {
-                result: "SKIPPED",
-                resultDescription: errorMessage,
-                ...contextReport
-              };
-              report.summary.contexts.skipped++;
-              testReport.contexts.push(contextReport);
-              continue;
-            }
-          }
-          if (context.browser?.viewport?.width || context.browser?.viewport?.height) {
-            await setViewportSize(context, driver);
-          } else if (context.browser?.window?.width || context.browser?.window?.height) {
-            const windowSize = await driver.getWindowSize();
-            await driver.setWindowSize(context.browser?.window?.width || windowSize.width, context.browser?.window?.height || windowSize.height);
-          }
-        }
-        let stepExecutionFailed = false;
-        for (let step of context.steps) {
-          if (!step.stepId)
-            step.stepId = (0, import_node_crypto5.randomUUID)();
-          log(config, "debug", `STEP:
-${JSON.stringify(step, null, 2)}`);
-          if (step.unsafe && runnerDetails.allowUnsafeSteps === false) {
-            log(config, "warning", `Skipping unsafe step: ${step.description} in test ${test.testId} context ${context.contextId}`);
-            const stepReport2 = {
-              ...step,
-              result: "SKIPPED",
-              resultDescription: "Skipped because unsafe steps aren't allowed."
-            };
-            contextReport.steps.push(stepReport2);
-            report.summary.steps.skipped++;
-            continue;
-          }
-          if (stepExecutionFailed) {
-            const stepReport2 = {
-              ...step,
-              result: "SKIPPED",
-              resultDescription: "Skipped due to previous failure in context."
-            };
-            contextReport.steps.push(stepReport2);
-            report.summary.steps.skipped++;
+      }
+    });
+    for (const specReport of report.specs) {
+      for (const testReport of specReport.tests) {
+        for (const contextReport of testReport.contexts) {
+          if (!contextReport)
             continue;
+          for (const stepReport of contextReport.steps) {
+            report.summary.steps[stepReport.result.toLowerCase()]++;
           }
-          metaValues.specs[spec.specId].tests[test.testId].contexts[context.contextId].steps[step.stepId] = {};
-          const stepResult = await runStep({
-            config,
-            context,
-            step,
-            driver,
-            metaValues,
-            options: {
-              openApiDefinitions: context.openApi || []
-            }
-          });
-          log(config, "debug", `RESULT: ${stepResult.status}
-${JSON.stringify(stepResult, null, 2)}`);
-          stepResult.result = stepResult.status;
-          stepResult.resultDescription = stepResult.description;
-          delete stepResult.status;
-          delete stepResult.description;
-          const stepReport = {
-            ...step,
-            ...stepResult
-          };
-          contextReport.steps.push(stepReport);
-          report.summary.steps[stepReport.result.toLowerCase()]++;
-          if (stepReport.result === "FAIL") {
-            stepExecutionFailed = true;
-          }
-        }
-        if (config.recording) {
-          const stopRecordStep = {
-            stopRecord: true,
-            description: "Stopping recording",
-            stepId: (0, import_node_crypto5.randomUUID)()
-          };
-          const stepResult = await runStep({
-            config,
-            context,
-            step: stopRecordStep,
-            driver,
-            options: {
-              openApiDefinitions: context.openApi || []
-            }
-          });
-          stepResult.result = stepResult.status;
-          stepResult.resultDescription = stepResult.description;
-          delete stepResult.status;
-          delete stepResult.description;
-          const stepReport = {
-            ...stopRecordStep,
-            ...stepResult
-          };
-          contextReport.steps.push(stepReport);
-          report.summary.steps[stepReport.result.toLowerCase()]++;
-        }
-        let contextResult;
-        if (contextReport.steps.find((step) => step.result === "FAIL"))
-          contextResult = "FAIL";
-        else if (contextReport.steps.find((step) => step.result === "WARNING"))
-          contextResult = "WARNING";
-        else if (contextReport.steps.length === contextReport.steps.filter((step) => step.result === "SKIPPED").length)
-          contextResult = "SKIPPED";
-        else
-          contextResult = "PASS";
-        contextReport = { result: contextResult, ...contextReport };
-        testReport.contexts.push(contextReport);
-        report.summary.contexts[contextResult.toLowerCase()]++;
-        if (driverRequired) {
-          try {
-            await driver.deleteSession();
-          } catch (error) {
-            log(config, "error", `Failed to delete driver session: ${error.message}`);
-          }
+          report.summary.contexts[contextReport.result.toLowerCase()]++;
         }
+        testReport.result = rollUpResults(testReport.contexts.filter(Boolean));
+        report.summary.tests[testReport.result.toLowerCase()]++;
       }
-      let testResult;
-      if (testReport.contexts.find((context) => context.result === "FAIL"))
-        testResult = "FAIL";
-      else if (testReport.contexts.find((context) => context.result === "WARNING"))
-        testResult = "WARNING";
-      else if (testReport.contexts.length === testReport.contexts.filter((context) => context.result === "SKIPPED").length)
-        testResult = "SKIPPED";
-      else
-        testResult = "PASS";
-      testReport = { result: testResult, ...testReport };
-      specReport.tests.push(testReport);
-      report.summary.tests[testResult.toLowerCase()]++;
+      specReport.result = rollUpResults(specReport.tests);
+      report.summary.specs[specReport.result.toLowerCase()]++;
     }
-    let specResult;
-    if (specReport.tests.find((test) => test.result === "FAIL"))
-      specResult = "FAIL";
-    else if (specReport.tests.find((test) => test.result === "WARNING"))
-      specResult = "WARNING";
-    else if (specReport.tests.length === specReport.tests.filter((test) => test.result === "SKIPPED").length)
-      specResult = "SKIPPED";
-    else
-      specResult = "PASS";
-    specReport = { result: specResult, ...specReport };
-    report.specs.push(specReport);
-    report.summary.specs[specResult.toLowerCase()]++;
-  }
-  if (appium) {
-    log(config, "debug", "Closing Appium server");
-    try {
-      (0, import_tree_kill.default)(appium.pid);
-    } catch {
+  } finally {
+    for (const server of appiumServers) {
+      log(config, "debug", `Closing Appium server on port ${server.port}`);
+      try {
+        (0, import_tree_kill.default)(server.process.pid);
+      } catch {
+      }
     }
   }
   const herettoConfigs = config?.integrations?.heretto || [];
@@ -139495,6 +139395,330 @@ ${JSON.stringify(stepResult, null, 2)}`);
   }
   return report;
 }
+function selectWarmUpTargets(jobs, runnerDetails) {
+  const platform = runnerDetails.environment.platform;
+  const seen = /* @__PURE__ */ new Set();
+  const targets = [];
+  for (const job of jobs) {
+    const context = job.context;
+    if (!context.steps)
+      context.steps = [];
+    if (!context.platform)
+      context.platform = platform;
+    if (!context.browser && isDriverRequired({ test: context })) {
+      context.browser = getDefaultBrowser({ runnerDetails });
+    }
+    if (!isDriverRequired({ test: context }))
+      continue;
+    if (!context.browser?.name)
+      continue;
+    const combo = combinationKey(context);
+    if (seen.has(combo))
+      continue;
+    seen.add(combo);
+    targets.push({ context, combo });
+  }
+  return targets;
+}
+async function warmUpContexts({ jobs, config, runnerDetails, appiumPool, installAttempts, warmUpResults }) {
+  const platform = runnerDetails.environment.platform;
+  for (const { context } of selectWarmUpTargets(jobs, runnerDetails)) {
+    const combo = combinationKey(context);
+    let supported = isSupportedContext({
+      context,
+      apps: runnerDetails.availableApps,
+      platform
+    });
+    if (!supported && context.platform === platform && Array.isArray(context?.steps) && requiredBrowserAssets(context.browser?.name).length > 0) {
+      const firstAttempt = !installAttempts.has((context.browser?.name ?? "<none>").toLowerCase());
+      const outcome = await ensureContextBrowserInstalled({
+        browserName: context.browser?.name,
+        config,
+        installAttempts,
+        deps: {
+          ensureBrowser: (asset, options) => ensureBrowserInstalled(asset, options),
+          log
+        }
+      });
+      if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
+        clearAppCache(config);
+        runnerDetails.availableApps = await getAvailableApps({ config });
+        supported = isSupportedContext({
+          context,
+          apps: runnerDetails.availableApps,
+          platform
+        });
+      }
+    }
+    if (!supported)
+      continue;
+    const port = await appiumPool.acquire();
+    let warmDriver;
+    try {
+      const options = {
+        width: context.browser?.window?.width || 1200,
+        height: context.browser?.window?.height || 800,
+        headless: context.browser?.headless !== false
+      };
+      try {
+        warmDriver = await driverStart(getDriverCapabilities({
+          runnerDetails,
+          name: context.browser.name,
+          options
+        }), port, 4, { cacheDir: config?.cacheDir });
+      } catch {
+        log(config, "warning", `Warm-up for ${combo} failed headed; retrying headless.`);
+        warmDriver = await driverStart(getDriverCapabilities({
+          runnerDetails,
+          name: context.browser.name,
+          options: { ...options, headless: true }
+        }), port, 4, { cacheDir: config?.cacheDir });
+      }
+      warmUpResults.set(combo, "ok");
+      log(config, "debug", `Warm-up succeeded for ${combo}.`);
+    } catch (error) {
+      warmUpResults.set(combo, "failed");
+      log(config, "warning", `Warm-up failed for ${combo}; contexts using it will be skipped: ${error?.message ?? String(error)}`);
+    } finally {
+      if (warmDriver) {
+        try {
+          await warmDriver.deleteSession();
+        } catch {
+        }
+      }
+      appiumPool.release(port);
+    }
+  }
+}
+async function runContext({ config, spec, test, context, runnerDetails, appiumPool, metaValues, installAttempts, warmUpResults, logPrefix = "" }) {
+  const platform = runnerDetails.environment.platform;
+  let availableApps = runnerDetails.availableApps;
+  const clog = (level, message) => log(config, level, logPrefix && typeof message === "string" ? `${logPrefix} ${message}` : message);
+  if (!context.steps) {
+    context.steps = [];
+  }
+  if (!context.platform)
+    context.platform = runnerDetails.environment.platform;
+  if (config.integrations?.openApi) {
+    context.openApi = [
+      ...context.openApi || [],
+      ...config.integrations.openApi
+    ];
+  }
+  if (!context.browser && isDriverRequired({ test: context })) {
+    context.browser = getDefaultBrowser({ runnerDetails });
+  }
+  const contextReport = {
+    contextId: context.contextId,
+    platform: context.platform,
+    browser: context.browser,
+    steps: []
+  };
+  metaValues.specs[spec.specId].tests[test.testId].contexts[context.contextId] ??= { steps: {} };
+  if (isDriverRequired({ 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";
+    contextReport.resultDescription = errorMessage;
+    return contextReport;
+  }
+  let supportedContext = isSupportedContext({
+    context,
+    apps: availableApps,
+    platform
+  });
+  let freshInstallRedetected = false;
+  if (!supportedContext && context.platform === platform && // Mirror isSupportedContext's own guard: isDriverRequired iterates
+  // context.steps, so a malformed context without a steps array would
+  // otherwise crash here instead of skipping cleanly.
+  Array.isArray(context?.steps) && isDriverRequired({ test: context }) && requiredBrowserAssets(context.browser?.name).length > 0) {
+    const firstAttempt = !installAttempts.has((context.browser?.name ?? "<none>").toLowerCase());
+    const outcome = await ensureContextBrowserInstalled({
+      browserName: context.browser?.name,
+      config,
+      installAttempts,
+      deps: {
+        ensureBrowser: (asset, options) => ensureBrowserInstalled(asset, options),
+        log
+      }
+    });
+    if (firstAttempt && (outcome === "installed" || outcome === "failed")) {
+      freshInstallRedetected = true;
+      clearAppCache(config);
+      availableApps = await getAvailableApps({ config });
+      runnerDetails.availableApps = availableApps;
+      supportedContext = isSupportedContext({
+        context,
+        apps: availableApps,
+        platform
+      });
+    }
+  }
+  if (!supportedContext) {
+    const errorMessage = freshInstallRedetected ? `Skipping context '${context.browser?.name}' on '${context.platform}': the missing browser dependency was installed but still could not be detected.` : `Skipping context. The current system doesn't support this context: {"platform": "${context.platform}", "apps": ${JSON.stringify(context.apps)}}`;
+    clog(freshInstallRedetected ? "warning" : "info", errorMessage);
+    contextReport.result = "SKIPPED";
+    contextReport.resultDescription = errorMessage;
+    return contextReport;
+  }
+  clog("debug", `CONTEXT:
+${JSON.stringify(context, null, 2)}`);
+  let driver;
+  let appiumPort;
+  const driverRequired = isDriverRequired({ test: context });
+  if (driverRequired && !appiumPool) {
+    throw new Error("Driver requested but no Appium server pool was created; driverJobCount and isDriverRequired(context) disagreed; this is a bug.");
+  }
+  const combo = combinationKey(context);
+  try {
+    if (driverRequired) {
+      if (warmUpDecision(warmUpResults.get(combo)) === "skip") {
+        const errorMessage = `Skipping context '${context.browser?.name}' on '${context.platform}': this context combination could not start a driver earlier in this run.`;
+        clog("warning", errorMessage);
+        contextReport.result = "SKIPPED";
+        contextReport.resultDescription = errorMessage;
+        return contextReport;
+      }
+      appiumPort = await appiumPool.acquire();
+      let caps = getDriverCapabilities({
+        runnerDetails,
+        name: context.browser.name,
+        options: {
+          width: context.browser?.window?.width || 1200,
+          height: context.browser?.window?.height || 800,
+          headless: context.browser?.headless !== false
+        }
+      });
+      clog("debug", "CAPABILITIES:");
+      clog("debug", caps);
+      try {
+        driver = await driverStart(caps, appiumPort, 4, { cacheDir: config?.cacheDir });
+      } catch (error) {
+        try {
+          clog("warning", `Failed to start context '${context.browser?.name}' on '${platform}'. Retrying as headless.`);
+          context.browser.headless = true;
+          caps = getDriverCapabilities({
+            runnerDetails,
+            name: context.browser.name,
+            options: {
+              width: context.browser?.window?.width || 1200,
+              height: context.browser?.window?.height || 800,
+              headless: context.browser?.headless !== false
+            }
+          });
+          driver = await driverStart(caps, appiumPort, 4, { cacheDir: config?.cacheDir });
+        } catch (error2) {
+          let errorMessage = `Failed to start context '${context.browser?.name}' on '${platform}'.`;
+          if (context.browser?.name === "safari" || context.browser?.name === "webkit")
+            errorMessage = errorMessage + " Make sure you've run `safaridriver --enable` in a terminal and enabled 'Allow Remote Automation' in Safari's Develop menu.";
+          clog("error", errorMessage);
+          if (!warmUpResults.has(combo))
+            warmUpResults.set(combo, "failed");
+          contextReport.result = "SKIPPED";
+          contextReport.resultDescription = errorMessage;
+          return contextReport;
+        }
+      }
+      if (!warmUpResults.has(combo))
+        warmUpResults.set(combo, "ok");
+      if (context.browser?.viewport?.width || context.browser?.viewport?.height) {
+        await setViewportSize(context, driver);
+      } else if (context.browser?.window?.width || context.browser?.window?.height) {
+        const windowSize = await driver.getWindowSize();
+        await driver.setWindowSize(context.browser?.window?.width || windowSize.width, context.browser?.window?.height || windowSize.height);
+      }
+    }
+    let stepExecutionFailed = false;
+    for (let step of context.steps) {
+      if (!step.stepId)
+        step.stepId = (0, import_node_crypto5.randomUUID)();
+      clog("debug", `STEP:
+${JSON.stringify(step, null, 2)}`);
+      if (step.unsafe && runnerDetails.allowUnsafeSteps === false) {
+        clog("warning", `Skipping unsafe step: ${step.description} in test ${test.testId} context ${context.contextId}`);
+        const stepReport2 = {
+          ...step,
+          result: "SKIPPED",
+          resultDescription: "Skipped because unsafe steps aren't allowed."
+        };
+        contextReport.steps.push(stepReport2);
+        continue;
+      }
+      if (stepExecutionFailed) {
+        const stepReport2 = {
+          ...step,
+          result: "SKIPPED",
+          resultDescription: "Skipped due to previous failure in context."
+        };
+        contextReport.steps.push(stepReport2);
+        continue;
+      }
+      metaValues.specs[spec.specId].tests[test.testId].contexts[context.contextId].steps[step.stepId] = {};
+      const stepResult = await runStep({
+        config,
+        context,
+        step,
+        driver,
+        metaValues,
+        options: {
+          openApiDefinitions: context.openApi || []
+        }
+      });
+      clog("debug", `RESULT: ${stepResult.status}
+${JSON.stringify(stepResult, null, 2)}`);
+      stepResult.result = stepResult.status;
+      stepResult.resultDescription = stepResult.description;
+      delete stepResult.status;
+      delete stepResult.description;
+      const stepReport = {
+        ...step,
+        ...stepResult
+      };
+      contextReport.steps.push(stepReport);
+      if (stepReport.result === "FAIL") {
+        stepExecutionFailed = true;
+      }
+    }
+    if (driver?.state?.recording) {
+      const stopRecordStep = {
+        stopRecord: true,
+        description: "Stopping recording",
+        stepId: (0, import_node_crypto5.randomUUID)()
+      };
+      const stepResult = await runStep({
+        config,
+        context,
+        step: stopRecordStep,
+        driver,
+        options: {
+          openApiDefinitions: context.openApi || []
+        }
+      });
+      stepResult.result = stepResult.status;
+      stepResult.resultDescription = stepResult.description;
+      delete stepResult.status;
+      delete stepResult.description;
+      const stepReport = {
+        ...stopRecordStep,
+        ...stepResult
+      };
+      contextReport.steps.push(stepReport);
+    }
+  } finally {
+    if (driver) {
+      try {
+        await driver.deleteSession();
+      } catch (error) {
+        clog("error", `Failed to delete driver session: ${error.message}`);
+      }
+    }
+    if (appiumPort !== void 0 && appiumPool) {
+      appiumPool.release(appiumPort);
+    }
+  }
+  contextReport.result = rollUpResults(contextReport.steps);
+  return contextReport;
+}
 async function runStep({ config = {}, context = {}, step, driver, metaValues = {}, options = {} }) {
   let actionResult;
   step = replaceEnvs(step);
@@ -139545,7 +139769,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
       step,
       driver
     });
-    config.recording = actionResult.recording;
+    driver.state.recording = actionResult.recording ?? null;
   } else if (typeof step.runCode !== "undefined") {
     actionResult = await runCode({ config, step });
   } else if (typeof step.runShell !== "undefined") {
@@ -139570,7 +139794,7 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
       description: `Unknown step action: ${JSON.stringify(step)}`
     };
   }
-  if (config?.recording) {
+  if (driver?.state?.recording) {
     const currentUrl = await driver.getUrl();
     if (currentUrl !== driver.state.url) {
       driver.state.url = currentUrl;
@@ -139592,6 +139816,33 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
   }
   return actionResult;
 }
+async function startAppiumServer(appiumEntry, config) {
+  const port = await findFreePort();
+  log(config, "debug", `Starting Appium on port ${port}`);
+  const proc = (0, import_node_child_process5.spawn)(process.execPath, [appiumEntry, "-a", "127.0.0.1", "-p", String(port)], {
+    windowsHide: true,
+    cwd: import_node_path18.default.join(__dirname5, "../..")
+  });
+  proc.on("error", (err) => {
+    log(config, "warning", `Appium process error: ${err?.stack ?? err?.message ?? String(err)}`);
+  });
+  proc.stdout.on("data", () => {
+  });
+  proc.stderr.on("data", () => {
+  });
+  try {
+    await appiumIsReady(port);
+  } catch (error) {
+    try {
+      if (proc && proc.pid)
+        (0, import_tree_kill.default)(proc.pid);
+    } catch {
+    }
+    throw error;
+  }
+  log(config, "debug", `Appium is ready on port ${port}.`);
+  return { port, process: proc };
+}
 async function appiumIsReady(port, timeoutMs = 12e4) {
   let isReady = false;
   const start = Date.now();
@@ -139610,6 +139861,7 @@ async function appiumIsReady(port, timeoutMs = 12e4) {
   return isReady;
 }
 async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
+  const TRANSIENT = /ECONNREFUSED|ECONNRESET|socket hang up|could not proxy command|crashed during startup|cannot connect to|DevToolsActivePort|session not created/i;
   const wdio = await loadHeavyDep("webdriverio", { ctx });
   let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -139626,11 +139878,11 @@ async function driverStart(capabilities, port, maxAttempts = 4, ctx = {}) {
         waitforTimeout: 12e4
         // 2 minutes
       });
-      driver.state = { url: "", x: null, y: null };
+      driver.state = { url: "", x: null, y: null, recording: null };
       return driver;
     } catch (err) {
       lastError = err;
-      if (!/ECONNREFUSED/.test(String(err && err.message)))
+      if (!TRANSIENT.test(String(err && err.message)))
         throw err;
       if (attempt < maxAttempts) {
         await new Promise((r) => setTimeout(r, 500 * attempt));
@@ -139667,6 +139919,31 @@ async function ensureChromeAvailable(config, deps) {
   }
   return availableApps;
 }
+async function ensureContextBrowserInstalled({ browserName, config, installAttempts, deps }) {
+  const key = (browserName ?? "<none>").toLowerCase();
+  const cached = installAttempts.get(key);
+  if (cached)
+    return cached;
+  const assets = requiredBrowserAssets(browserName);
+  if (assets.length === 0) {
+    installAttempts.set(key, "notInstallable");
+    return "notInstallable";
+  }
+  const ctx = { cacheDir: config?.cacheDir };
+  const logger = (msg, level = "info") => deps.log?.(config, level === "warn" ? "warning" : level, msg);
+  try {
+    deps.log?.(config, "info", `Browser '${browserName}' is not available; attempting on-demand install of: ${assets.join(", ")}.`);
+    for (const asset of assets) {
+      await deps.ensureBrowser(asset, { ctx, deps: { logger } });
+    }
+    installAttempts.set(key, "installed");
+    return "installed";
+  } catch (err) {
+    deps.log?.(config, "warning", `On-demand install for '${browserName}' failed: ${err?.message ?? err}`);
+    installAttempts.set(key, "failed");
+    return "failed";
+  }
+}
 async function getRunner(options = {}) {
   const environment = getEnvironment();
   const config = { ...options.config, environment };
@@ -139880,22 +140157,19 @@ async function runTests(config, options = {}) {
       if (needs.browsers.size > 0) {
         try {
           const { getAvailableApps: getAvailableApps2, clearAppCache: clearAppCache2 } = await Promise.resolve().then(() => (init_config(), config_exports));
-          const { ensureBrowserInstalled: ensureBrowserInstalled2 } = await Promise.resolve().then(() => (init_browsers(), browsers_exports));
+          const { ensureBrowserInstalled: ensureBrowserInstalled2, requiredBrowserAssets: requiredBrowserAssets2 } = await Promise.resolve().then(() => (init_browsers(), browsers_exports));
           const available = await getAvailableApps2({ config });
           const availableNames = new Set(available.map((a) => a.name));
           let installedAnything = false;
           for (const browser of needs.browsers) {
             if (availableNames.has(browser))
               continue;
-            if (browser === "chrome") {
-              await ensureBrowserInstalled2("chrome", { ctx, deps: { logger: preflightLogger } });
-              await ensureBrowserInstalled2("chromedriver", { ctx, deps: { logger: preflightLogger } });
-              installedAnything = true;
-            } else if (browser === "firefox") {
-              await ensureBrowserInstalled2("firefox", { ctx, deps: { logger: preflightLogger } });
-              await ensureBrowserInstalled2("geckodriver", { ctx, deps: { logger: preflightLogger } });
-              installedAnything = true;
+            const assets = requiredBrowserAssets2(browser);
+            for (const asset of assets) {
+              await ensureBrowserInstalled2(asset, { ctx, deps: { logger: preflightLogger } });
             }
+            if (assets.length > 0)
+              installedAnything = true;
           }
           if (installedAnything)
             clearAppCache2(config);