doc-detective 4.32.0 → 4.34.0

package/dist/core/tests.js

@@ -24,6 +24,7 @@ import { typeKeys } from "./tests/typeKeys.js";
 import { swipeSurface } from "./tests/swipe.js";
 import { wait } from "./tests/wait.js";
 import { saveScreenshot } from "./tests/saveScreenshot.js";
+import { capPathSegment, stepArtifactFileName, resolveCheckpointsConfig, captureRecordingCheckpoints, } from "./tests/recordingCheckpoints.js";
 import { startRecording } from "./tests/startRecording.js";
 import { stopRecording } from "./tests/stopRecording.js";
 import { browserCaptureTitle, browserDownloadDir, coerceRecordContextBrowser, jobIsFfmpegRecording, computeEffectiveConcurrency, jobExclusiveResources, checkSystemBinary, xvfbDisplay, startXvfb, XVFB_SCREEN_SIZE, isRecordingActive, recordStepName, detectRecordingNameConflict, getFfmpegPath, ffmpegPathEnv, } from "./tests/ffmpegRecorder.js";
@@ -50,7 +51,7 @@ import { dragAndDropElement } from "./tests/dragAndDrop.js";
 import { createSessionRegistry, registerSession, activeDriver, sweepSessions, } from "./tests/browserSessions.js";
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { setAppiumHome } from "./appium.js";
 import { contentHash } from "../common/src/detectTests.js";
 import { resolveExpression } from "./expressions.js";
@@ -2908,28 +2909,6 @@ function buildAutoRecordStep({ config, spec, test, context, }) {
         __autoRecord: true,
     };
 }
-// Directory/file segments built from IDs are capped so deeply nested doc
-// trees can't push the full path past Windows' MAX_PATH. The default cap is
-// 32: the REST artifact tree nests several id segments
-// (specs/<id>/tests/<id>/contexts/<id>/…), so a larger default could exceed
-// MAX_PATH on Windows.
-//
-// Plain tail truncation alone is unsafe: two distinct ids that share the same
-// trailing `max` characters (e.g. mirror directory trees that differ only in a
-// long prefix) would collapse into the same path segment, so one context's
-// screenshots/recording could overwrite another's and the reported relative
-// path would resolve to the wrong artifact. When a segment exceeds the cap,
-// prepend a short deterministic hash of the *full* segment so distinct ids stay
-// distinct, and keep the trailing chars (where generated ids carry their
-// content hash) for human correlation. Deterministic — the same id maps to the
-// same segment every run, preserving run-over-run comparison.
-function capPathSegment(segment, max = 32) {
-    if (segment.length <= max)
-        return segment;
-    const hash = createHash("sha1").update(segment).digest("hex").slice(0, 8);
-    const tail = segment.slice(segment.length - (max - hash.length - 1));
-    return `${hash}-${tail}`;
-}
 // Capture a post-step screenshot for `autoScreenshot` runs. The relative
 // path follows the REST resource tree — stable IDs (spec/test/context) as
 // nested collections plus the step's order, action, and ID (e.g.
@@ -2940,21 +2919,14 @@ function capPathSegment(segment, max = 32) {
 // missed capture must not fail the step it documents.
 async function captureAutoScreenshot({ config, driver, spec, test, context, step, stepIndex, stepCount, }) {
     try {
-        const action = driverActions.find((key) => typeof step[key] !== "undefined") || "step";
-        const sanitizedTestId = sanitizeFilesystemName(String(test.testId ?? ""), "test");
         const runDir = getRunOutputDir(config);
-        const dir = path.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizedTestId), "contexts", capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context")), "screenshots");
-        // The stepId usually embeds the testId (its parent folder) — strip that
-        // prefix so filenames stay short while still carrying the step's ID.
-        const stepIdString = sanitizeFilesystemName(String(step.stepId ?? ""), "step");
-        const stepRef = capPathSegment(stepIdString.startsWith(`${sanitizedTestId}~`)
-            ? stepIdString.slice(sanitizedTestId.length + 1)
-            : stepIdString);
-        // Zero-pad the step ordinal to the width of the context's step count
-        // (min 2), so file listings sort naturally even past 99 steps (100 would
-        // otherwise sort before 11).
-        const pad = Math.max(2, String(stepCount).length);
-        const fileName = `${String(stepIndex + 1).padStart(pad, "0")}-${action}-${stepRef}.png`;
+        const dir = path.join(runDir, "specs", capPathSegment(sanitizeFilesystemName(String(spec.specId ?? ""), "spec")), "tests", capPathSegment(sanitizeFilesystemName(String(test.testId ?? ""), "test")), "contexts", capPathSegment(sanitizeFilesystemName(String(context.contextId ?? ""), "context")), "screenshots");
+        const fileName = stepArtifactFileName({
+            step,
+            stepIndex,
+            stepCount,
+            testId: test.testId,
+        });
         const screenshotStep = {
             stepId: `${step.stepId}_auto`,
             description: "Automatic post-step screenshot",
@@ -3951,6 +3923,35 @@ async function runContext({ config, spec, test, context, runnerDetails, appiumPo
                 if (capturedPath)
                     stepReport.autoScreenshot = capturedPath;
             }
+            // Recording checkpoints (ADR 01075): while a checkpoint-enabled
+            // recording is active, capture a compare-only screenshot per handle
+            // after every step (final attempt only, same placement rationale as
+            // autoScreenshot — retry frames would poison the staged captures).
+            // The record step's own post-step capture is the opening bookend.
+            // The host is the ACTIVE session's driver — the same driver runStep
+            // pushed the handle onto — falling back to the app session's host for
+            // app-only contexts (which skip capture inside the helper: no browser
+            // driver to capture with).
+            // Recordings live per SESSION, so sweep every live session driver the
+            // way stopAllRecordings does — not just the active one. A span started
+            // on a second browser surface keeps its handle on that session's
+            // driver; checking only the active session would silently capture
+            // nothing for it. Each driver is both the host (whose recordings we
+            // read) and the capture source, so a checkpoint always photographs the
+            // surface its own recording is filming.
+            for (const checkpointDriver of sessionDrivers(browserSessions, driver)) {
+                await captureRecordingCheckpoints({
+                    config,
+                    driver: checkpointDriver,
+                    recordingHost: checkpointDriver,
+                    step,
+                    stepStatus: stepReport.result,
+                    stepIndex,
+                    stepCount: context.steps.length,
+                    testId: test.testId,
+                    appSession,
+                });
+            }
             pushStepReport(stepReport);
             // Apply the terminal routing decision. `continue` runs the next step; a
             // `stop` halts the remaining steps in this context (`spec`/`run` scope —
@@ -4262,6 +4263,22 @@ async function runStep({ config = {}, context = {}, step, driver, metaValues = {
             const handle = actionResult.recording;
             handle.id = handle.id ?? randomUUID();
             handle.name = handle.name ?? recordStepName(step.record);
+            // Recording checkpoints (ADR 01075): resolve the step's `checkpoints`
+            // field once, here, where the handle and its target path are both at
+            // hand — the post-step hook and stopRecord read the resolved config
+            // off the handle. resolveCheckpointsConfig returns null for every
+            // record form without a checkpoints field (string/boolean included),
+            // so `null` is the single "disabled" encoding. `overwrite` rides along
+            // for stopRecord's aboveVariation staging/promote decision (ADR 01078).
+            handle.overwrite = step.record?.overwrite;
+            handle.verify = step.record?.verify;
+            if (handle.targetPath) {
+                handle.checkpoints = resolveCheckpointsConfig({
+                    record: step.record,
+                    targetPath: handle.targetPath,
+                    handleId: handle.id,
+                });
+            }
             if (step.__autoRecord) {
                 handle.synthetic = true;
                 // Desktop app-only context: no window exists yet to crop to. Mark the