doc-detective 4.41.6 → 4.42.0

package/dist/core/tests.js

@@ -15,7 +15,7 @@ import { requiredBrowserAssets, ensureBrowserInstalled, } from "../runtime/brows
 // Single source of truth for browser/driver-requiring step keys.
 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, classifyContextRetry, guardBlankDocumentNavigation, applyBrowserSize, isViewportFloored, loadAxios, } from "./utils.js";
+import { log, logLevelEnabled, replaceEnvs, selectSpecsForRun, findFreePort, runConcurrent, runResourceAware, createResourceRegistry, rollUpResults, createAppiumPool, getRunOutputDir, runArchivesArtifacts, sanitizeFilesystemName, evaluateContextRequirements, isRetryableSessionError, classifyContextRetry, guardBlankDocumentNavigation, applyBrowserSize, isViewportFloored, loadAxios, sessionVersions, } from "./utils.js";
 import { instantiateCursor } from "./tests/moveTo.js";
 import { goTo } from "./tests/goTo.js";
 import { findElement } from "./tests/findElement.js";
@@ -45,6 +45,7 @@ import { mobileBrowserGate, buildMobileBrowserCapabilities, CHROMEDRIVER_AUTODOW
 import { planWarmTasks, executeWarmTasks, raceBootInitiation, wrapInitiationEffects, RUNTIME_INSTALL_RESOURCE, } from "./warmPhase.js";
 import { locateManagedWda } from "../runtime/wdaProducts.js";
 import { getCacheDir } from "../runtime/cacheDir.js";
+import { packageRoot } from "../runtime/heavyDeps.js";
 import { detectAndroidSdk } from "../runtime/androidSdk.js";
 import { hostAbi, listInstalledSystemImages, installAndroid, } from "../runtime/androidInstaller.js";
 import { buildAcquireDeviceDeps, findUia2Helpers, checkEmulatorAcceleration, hostHasKvm, planDeviceAcquisition, planAndroidToolchain, normalizeDeviceDescriptor, acquireDevice, createDeviceRegistry, teardownDeviceRegistry, shutdownEmulator, } from "./tests/androidEmulator.js";
@@ -64,8 +65,6 @@ import { getEnvironment, getAvailableApps, clearAppCache, resolveConcurrentRunne
 import { uploadChangedFiles } from "./integrations/index.js";
 import http from "node:http";
 import https from "node:https";
-import { fileURLToPath } from "node:url";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Idle browser-pool Appium servers kept between runs in this process, only
 // when DOC_DETECTIVE_REUSE_APPIUM is set (ADR 01125). Empty otherwise.
 // killTree is a hoisted function declaration, called only when a server dies.
@@ -1017,6 +1016,8 @@ async function runViaApi({ resolvedTests, apiKey, config = {} }) {
                     steps: { pass: 0, fail: 0, warning: 0, skipped: 0 },
                 },
                 // Nothing ran, but the shape stays parity with runSpecs' short-circuit.
+                startedAt: new Date().toISOString(),
+                environment: getEnvironment(),
                 durationMs: 0,
                 specs: [],
             };
@@ -1163,6 +1164,8 @@ async function runSpecs({ resolvedTests }) {
                 contexts: { pass: 0, fail: 0, warning: 0, skipped: 0 },
                 steps: { pass: 0, fail: 0, warning: 0, skipped: 0 },
             },
+            startedAt: new Date(runStart).toISOString(),
+            environment: getEnvironment(),
             durationMs: Date.now() - runStart,
             specs: [],
         };
@@ -1212,6 +1215,10 @@ async function runSpecs({ resolvedTests }) {
     const report = {
         runId,
         runDir,
+        // Run metadata (ADR 01163): when execution started and the host that ran
+        // it, so a consumer can tell product drift from environment drift.
+        startedAt: new Date(runStart).toISOString(),
+        environment: runnerDetails.environment,
         summary: {
             specs: {
                 pass: 0,
@@ -1968,35 +1975,44 @@ async function runSpecs({ resolvedTests }) {
         process.off("SIGINT", onSignal);
         process.off("SIGTERM", onSignal);
     }
-    // Upload changed files back to source integrations (best-effort)
-    // This automatically syncs any changed screenshots back to their source CMS
-    // Only upload if uploadOnChange is enabled (defaults to true for backward compatibility)
-    // Check both global config.uploadOnChange and per-integration uploadOnChange settings
-    const herettoConfigs = config?.integrations?.heretto || [];
-    const hasUploadEnabledIntegration = herettoConfigs.some((h) => h.uploadOnChange !== false // Default to true if not explicitly set to false
-    );
-    const globalUploadOnChange = config?.uploadOnChange ?? true;
-    if (globalUploadOnChange && hasUploadEnabledIntegration && herettoConfigs.length > 0) {
-        try {
-            const uploadResults = await uploadChangedFiles({ config, report, log });
-            report.uploadResults = uploadResults;
-        }
-        catch (error) {
-            log(config, "warning", `Failed to upload changed files: ${error.message}`);
-            report.uploadResults = {
-                total: 0,
-                successful: 0,
-                failed: 0,
-                skipped: 0,
-                error: error.message,
-            };
-        }
-    }
+    // An absent `report.uploadResults` means no integration opted in, so no
+    // upload was attempted.
+    const uploadResults = await uploadChangedFilesIfEnabled({ config, report, log });
+    if (uploadResults)
+        report.uploadResults = uploadResults;
     // 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;
 }
+/**
+ * Upload changed files back to their source integrations (best-effort). Opt-in:
+ * runs only when some integration, of any type, sets `uploadOnChange: true`
+ * (schema default false); uploadChangedFiles then skips files from
+ * integrations that didn't. Returns undefined when nothing opted in. A thrown
+ * upload still returns the success shape, with empty `details` and `error`.
+ * `upload` is injectable for tests.
+ */
+export async function uploadChangedFilesIfEnabled({ config, report, log: logFn, upload = uploadChangedFiles, }) {
+    const integrationEntries = Object.values(config?.integrations ?? {}).flatMap((entries) => (Array.isArray(entries) ? entries : []));
+    if (!integrationEntries.some((entry) => entry?.uploadOnChange === true)) {
+        return undefined;
+    }
+    try {
+        return await upload({ config, report, log: logFn });
+    }
+    catch (error) {
+        logFn(config, "warning", `Failed to upload changed files: ${error.message}`);
+        return {
+            total: 0,
+            successful: 0,
+            failed: 0,
+            skipped: 0,
+            details: [],
+            error: error.message,
+        };
+    }
+}
 /**
  * Sequencer for a single ROUTED spec (one whose `specIsRouted` is true). Runs
  * the spec's tests in input order, evaluating test-level routing between them.
@@ -3633,6 +3649,16 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 engine: String(mobileWebBrowserName).toLowerCase(),
                 driver,
             });
+            // Device browser versions, as far as the session reports them (ADR
+            // 01163); there's no desktop app entry to fall back on.
+            const versions = sessionVersions({ capabilities: driver?.capabilities });
+            if (versions.browserVersion)
+                contextReport.browser = {
+                    ...contextReport.browser,
+                    version: versions.browserVersion,
+                };
+            if (versions.driver)
+                contextReport.driver = versions.driver;
             /* c8 ignore stop */
         }
         else if (driverRequired) {
@@ -3810,6 +3836,19 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 };
                 clog("warning", fellBackNote);
             }
+            // The browser and driver that actually ran, for the report (ADR 01163).
+            // A copy, so the version never feeds back into the context's settings.
+            const versions = sessionVersions({
+                capabilities: driver?.capabilities,
+                app: availableApps.find((app) => app.name === normalizeBrowserName(startedName)),
+            });
+            if (versions.browserVersion)
+                contextReport.browser = {
+                    ...contextReport.browser,
+                    version: versions.browserVersion,
+                };
+            if (versions.driver)
+                contextReport.driver = versions.driver;
             // Multi-surface Phase 4 (ADR 01019): register the default session in the
             // context's session registry under its engine name, so it resolves like
             // any named surface. The launcher closure lets goTo open ADDITIONAL
@@ -4106,7 +4145,12 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 // 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 };
+                return {
+                    ...step,
+                    ...r,
+                    startedAt: new Date(stepStart).toISOString(),
+                    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`
@@ -4480,6 +4524,7 @@ delayMs = (attempt) => 500 * (attempt + 1)) {
         const start = Date.now();
         const report = await runContextFn(a);
         if (report && typeof report === "object") {
+            report.startedAt = new Date(start).toISOString();
             report.durationMs = Date.now() - start;
         }
         return report;
@@ -4581,6 +4626,7 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
             contextReport.steps.push({
                 ...stopRecordStep,
                 ...stepResult,
+                startedAt: new Date(stopStart).toISOString(),
                 durationMs: Date.now() - stopStart,
             });
         }
@@ -4593,6 +4639,7 @@ async function stopAllRecordings({ config, context, driver, contextReport, }) {
                 ...stopRecordStep,
                 result: "FAIL",
                 resultDescription: `Couldn't stop recording. ${error?.message ?? error}`,
+                startedAt: new Date(stopStart).toISOString(),
                 durationMs: Date.now() - stopStart,
             });
         }
@@ -5011,7 +5058,7 @@ nodeArgs) {
         ...(extraArgs ?? []),
     ], {
         windowsHide: true,
-        cwd: path.join(__dirname, "../.."),
+        cwd: packageRoot(),
         env,
     });
     proc.on("error", (err) => {
@@ -5326,7 +5373,7 @@ async function getRunner(options = {}) {
         ...useDriversArgs(process.env.APPIUM_HOME, browserPoolDriverPackages(process.platform)),
     ], {
         windowsHide: true,
-        cwd: path.join(__dirname, "../.."),
+        cwd: packageRoot(),
     });
     // Without a listener an "error" event from spawn (e.g. ENOENT, EACCES)
     // would crash the process before appiumIsReady's timeout could surface