ccqa 1.60.0 → 1.60.1

package/dist/bin/ccqa.mjs

@@ -1612,13 +1612,14 @@ async function stampGeneratedTest(ref, testPathAbs) {
 	};
 	return writeRecording(ref, found.recording);
 }
-function buildRecording(actions, cleanup = []) {
+function buildRecording(actions, cleanup = [], stepDigests) {
 	const origin = actions.find((a) => a.action === "navigate")?.value;
 	return {
 		recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		...origin ? { origin } : {},
 		actions,
-		...cleanup.length > 0 ? { cleanup } : {}
+		...cleanup.length > 0 ? { cleanup } : {},
+		...stepDigests ? { stepDigests } : {}
 	};
 }
 /**
@@ -1634,9 +1635,9 @@ function parseRecording(content, path) {
 	return recording;
 }
 const LEGACY_RECORDING_FILES = ["actions.json", "route.md"];
-async function saveRecording(ref, actions, cleanup = []) {
+async function saveRecording(ref, actions, cleanup = [], stepDigests) {
 	await mkdir(ref.dir, { recursive: true });
-	const recording = buildRecording(actions, cleanup);
+	const recording = buildRecording(actions, cleanup, stepDigests);
 	const recordingPath = await writeRecording(ref, recording);
 	await Promise.all([...LEGACY_RECORDING_FILES, FAILED_RECORDING_FILE].map((f) => unlink(join(ref.dir, f)).catch(() => {})));
 	return {
@@ -6313,6 +6314,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;
@@ -25286,12 +25335,11 @@ function isPassiveAction(action) {
 * The previous recording as the commands that perform it, for the trace prompt:
 * a re-record is usually one moved screen in an otherwise intact route.
 */
-function renderPreviousRecording(actions, sessionName, currentStepIds) {
-	const current = new Set([SETUP_STEP_ID, ...currentStepIds]);
+function renderPreviousRecording(actions, sessionName, replayable) {
 	const brokenStep = actions.find(failedToReplay)?.stepId;
 	const byStep = /* @__PURE__ */ new Map();
 	for (const action of actions) {
-		if (action.stepId === void 0 || !current.has(action.stepId)) continue;
+		if (action.stepId === void 0 || !replayable.has(action.stepId)) continue;
 		const command = previousCommand(action, sessionName, action.stepId === brokenStep);
 		if (command === null) continue;
 		const lines = byStep.get(action.stepId) ?? [];
@@ -25303,9 +25351,9 @@ function renderPreviousRecording(actions, sessionName, currentStepIds) {
 ## Previous recording
 
 This case was recorded before. Below is what that recording did, step by step,
-as the commands that perform it. The application may have moved since, and the
-steps above may have been edited: **the steps above are the contract, this is a
-map.**
+as the commands that perform it, for the steps whose text has not changed since.
+The application may have moved since: **the steps above are the contract, this
+is a map.**
 
 For a step listed here, this replaces the snapshot-first routine of the
 Execution Workflow:
@@ -25319,19 +25367,16 @@ Execution Workflow:
 3. When it reports a failure, the commands before it are recorded and the
    page is where they left it: finish that step with the Execution Workflow —
    snapshot, find what works, record it — without re-running what was
-   recorded. A step whose instruction or \`Expected\` asks for something these
-   commands do not do skips \`replay_step\` and uses the Execution Workflow
-   from the start. The next step goes back to \`replay_step\`.
-4. A step you record yourself takes its assertions from its current
+   recorded. The next step goes back to \`replay_step\`.
+4. A step you finish yourself takes its assertions from its current
    \`Expected\`: keep a previous check only while it verifies what
-   \`Expected\` says now. A step whose \`Expected\` has changed is one to
-   record yourself, since \`replay_step\` records the previous checks as
-   they are.
+   \`Expected\` says now.
 5. A command marked \`# did not replay last time\` is where the previous
    recording's own validation found the route broken: expect that step to
    need the Execution Workflow, and do not keep a form that only half works.
 
-A step with no section here is recorded the usual way.
+A step with no section here — new, or edited since that recording — is
+recorded the usual way.
 
 ${[...byStep].map(([stepId, lines]) => `### ${stepId}\n\n\`\`\`bash\n${lines.join("\n")}\n\`\`\``).join("\n\n")}
 `;
@@ -25404,7 +25449,7 @@ ${input.instruction}
 	const expectationsText = renderExpectations(input.expectations ?? []) + renderCleanupExpectations(input.cleanupExpectations ?? []);
 	const contextText = renderContext(input.context ?? []);
 	const conventionsText = renderConventions(input.conventions ?? []);
-	const previousText = renderPreviousRecording(input.previousRecording ?? [], sessionName, input.steps.map((s) => s.id));
+	const previousText = input.previousRecording ? renderPreviousRecording(input.previousRecording.actions, sessionName, input.previousRecording.replayable) : "";
 	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
 
 ## Session
@@ -25541,6 +25586,7 @@ find nth <index> "<ALLOWED-css>" <action>
 6. If repeated labels make every ALLOWED selector ambiguous → use the \`find\` subset above.
 7. Never guess. If a selector fails, take a fresh snapshot before retrying.
 8. **A click that reports success but changes nothing means the element sits outside the visible part of an inner scroll container** — the event dispatches, the app never reacts, and no error is printed. Run \`scrollintoview\` on the element and click again. Scroll to the element itself, addressed by a CSS selector (\`scrollintoview "button.primary-action"\`); \`scrollintoview "text=…"\` can land on a text node that leaves the control still clipped. Do not read this as a product bug or reach for a \`@ref\` — verify by checking that the DOM changed (e.g. \`get count\` on what the click should have produced).
+9. **A click refused with \`is covered by\`** (a sticky footer or banner over the element) is not a product bug: \`run_commands\` scrolls the element to the centre and clicks again, so send it there.
 
 ### Special input types
 
@@ -25890,6 +25936,39 @@ ${conventions.map((c) => `### ${c.heading}\n\n${c.body}`).join("\n\n")}
 `;
 }
 //#endregion
+//#region src/ir/step-digests.ts
+/**
+* What each step was asked to do when it was recorded, by step id. Case-level
+* checks land on whichever step the recorder chose, so they are part of every
+* step's; setup has no text of its own and stands for the case's context.
+*/
+function stepDigests(testCase) {
+	return {
+		[SETUP_STEP_ID]: digest(testCase.context),
+		...Object.fromEntries(testCase.steps.filter(isExpandedActionStep).map((s) => [s.id, digest([
+			s.instruction,
+			s.expected,
+			testCase.expectations
+		])])),
+		...Object.fromEntries(testCase.cleanup.map((s) => [s.id, digest([
+			s.instruction,
+			s.expected,
+			testCase.cleanupExpectations
+		])]))
+	};
+}
+/**
+* The steps whose previous commands may be replayed: those still asked to do
+* what they were then. An edited, added or renumbered step, or any step of a
+* recording without digests, would replay what the old step asked.
+*/
+function unchangedSteps(previous, current) {
+	return new Set(Object.keys(current).filter((id) => previous?.[id] !== void 0 && previous[id] === current[id]));
+}
+function digest(value) {
+	return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}
+//#endregion
 //#region src/cli/trace-tools.ts
 const TRACE_TOOLS_SERVER = "ccqa";
 /** A wedged command must not hold the whole trace; agent-browser's own waits are far shorter. */
@@ -25935,10 +26014,12 @@ async function runCommands(commands, input) {
 		const checkpoint = input.beforeAbCommand(extractCcqaStepFromBashCommand(cmd) ?? void 0);
 		if (checkpoint) return stop(checkpoint);
 		info(`$ ${scrubEnvValues(cmd, input.envScrubMap)}`);
-		const result = await runShell(cmd, {
+		const env = {
 			...process.env,
 			...input.env
-		});
+		};
+		let result = await runShell(cmd, env);
+		if (result.status !== 0 && scrollCoveredIntoView(["--session", input.sessionName], abPositionalTokens(cmd), result)) result = await runShell(cmd, env);
 		const out = result.stdout.trim();
 		if (!(result.status === 0 && (recorded?.holds ? recorded.holds(out) : true))) {
 			const detail = (result.stderr || out || `exit ${result.status ?? "timeout"}`).trim().slice(0, 600);
@@ -25979,7 +26060,7 @@ function cap(out) {
 }
 function replayStep(step, input) {
 	const actions = input.previous.filter((a) => a.stepId === step && a.action !== "snapshot").map(({ replayUnstable: _u, replayReason: _r, ...a }) => a);
-	if (actions.length === 0) return `No previous commands for ${step}. Record it with the Execution Workflow.`;
+	if (actions.length === 0) return `No previous commands for ${step}: it is new or its text changed since the last recording. Record it with the Execution Workflow.`;
 	const { passed, unchecked, failed } = replayUntilFailure(actions, {
 		sessionName: input.sessionName,
 		envOverrides: { CCQA_RUN_ID: input.env["CCQA_RUN_ID"] ?? input.sessionName }
@@ -26041,9 +26122,12 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	for (const w of conventions.warnings) warn(w);
 	const caseRef = testCase.ref;
 	const previous = await tryGetRecording(caseRef);
+	const digests = stepDigests(testCase);
+	const replayable = unchangedSteps(previous?.stepDigests, digests);
 	const previousActions = previous ? [...previous.actions, ...previous.cleanup ?? []] : [];
-	if (previousActions.length > 0) meta("previous", opts.freshIr ? "ignored (--fresh-ir)" : `${previousActions.length} action(s) offered as a map`);
-	const offersMap = !opts.freshIr && previousActions.length > 0;
+	const replayableActions = previousActions.filter((a) => a.stepId !== void 0 && replayable.has(a.stepId));
+	if (previous) meta("previous", opts.freshIr ? "ignored (--fresh-ir)" : previous.stepDigests ? `${[...replayable].filter((id) => id !== SETUP_STEP_ID).length} unchanged step(s) offered as a map` : "not offered (recorded before step digests)");
+	const offersMap = !opts.freshIr && replayableActions.length > 0;
 	const baseSystemPrompt = buildTraceSystemPrompt({
 		title: testCase.title,
 		steps,
@@ -26056,7 +26140,10 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		...testCase.cleanupExpectations.length > 0 ? { cleanupExpectations: testCase.cleanupExpectations } : {},
 		...testCase.context.length > 0 ? { context: testCase.context } : {},
 		...opts.instruction ? { instruction: opts.instruction } : {},
-		...offersMap ? { previousRecording: previousActions } : {}
+		...offersMap ? { previousRecording: {
+			actions: previousActions,
+			replayable
+		} } : {}
 	});
 	const promptBundle = await loadPromptBundle(opts.hubContext ?? null, "record", opts.cwd ?? process.cwd());
 	if (promptBundle !== null) meta("prompt", promptBundle.loaded.join(" + "));
@@ -26115,7 +26202,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 		runId: sessionName
 	});
 	const traceTools = buildTraceTools({
-		previous: offersMap ? previousActions : [],
+		previous: offersMap ? replayableActions : [],
 		sessionName,
 		env: invokeBase.env ?? {},
 		envScrubMap,
@@ -26185,7 +26272,7 @@ async function runTrace(testCase, model, validationMode = "lenient", language, o
 	const routeActions = validatedActions.filter((a) => !cleanupIds.has(a.stepId ?? ""));
 	const cleanupActions = validatedActions.filter((a) => cleanupIds.has(a.stepId ?? ""));
 	if (overallStatus === "passed") {
-		const saved = await saveRecording(caseRef, routeActions, cleanupActions);
+		const saved = await saveRecording(caseRef, routeActions, cleanupActions, digests);
 		recordingPath = saved.path;
 		if (previous) await reportRouteDiff(caseRef, previous, saved.recording, steps);
 		else await removeRouteDiff(caseRef);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.60.0",
+  "version": "1.60.1",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/dist/runtime/test-helpers.cjs

@@ -118,6 +118,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;

package/dist/runtime/test-helpers.mjs

@@ -118,6 +118,54 @@ function subcommand(args) {
 */
 function spawnAB(args, opts) {
 	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	const result = spawnABRetrying(args, timeoutMs);
+	if (result.status === 0) return result;
+	const session = args[0] === "--session" ? args.slice(0, 2) : [];
+	return scrollCoveredIntoView(session, args.slice(session.length), result) ? spawnABRetrying(args, timeoutMs) : result;
+}
+const COVERED_PATTERN = /Element '(.+?)' is covered by /;
+/**
+* When agent-browser refused `command` because another element (a sticky
+* footer, a banner) covers the target's click point, scroll the target to the
+* centre and say whether the command is worth running again. The refusal comes
+* before any input is dispatched, so running it again cannot act twice.
+*/
+function scrollCoveredIntoView(session, command, failed) {
+	const covered = COVERED_PATTERN.exec(`${failed.stdout}\n${failed.stderr}`)?.[1];
+	if (covered === void 0) return false;
+	const scroll = command[0] === "find" ? scrollToFound(command, session) : ["scrollintoview", covered];
+	return scroll !== null && spawnABOnce([...session, ...scroll], PROCESS_HARD_TIMEOUT_MS).status === 0;
+}
+/** The `find` forms whose element can be addressed again; the rest stay refused. */
+function scrollToFound(find, session) {
+	const [, by = "", value = ""] = find;
+	switch (by) {
+		case "testid": return ["scrollintoview", `[data-testid=${JSON.stringify(value)}]`];
+		case "first": return scrollToNth(value, "0");
+		case "last": return scrollToNth(value, "els.length - 1");
+		case "nth": return scrollToNth(find[3] ?? "", String(Number(value)));
+		case "role": return scrollToRole(find, session);
+		default: return null;
+	}
+}
+function scrollToNth(css, index) {
+	return ["eval", `{ const els = document.querySelectorAll(${JSON.stringify(css)}); els[${index}]?.scrollIntoView({ block: "center" }); }`];
+}
+/** The snapshot's ref for the element `find role` matches: same role, name by `--exact` or case-insensitive substring. */
+function scrollToRole(find, session) {
+	const role = (find[2] ?? "").toLowerCase();
+	const flag = find.indexOf("--name");
+	const name = flag === -1 ? null : find[flag + 1] ?? "";
+	const named = (label) => name === null || (find.includes("--exact") ? label === name : label.toLowerCase().includes(name.toLowerCase()));
+	const snapshot = spawnABOnce([
+		...session,
+		"snapshot",
+		"-i"
+	], PROCESS_HARD_TIMEOUT_MS);
+	for (const [, r, label = "", ref] of snapshot.stdout.matchAll(/^\s*- (\S+)(?: "(.*)")?.*\bref=(e\d+)/gm)) if (r.toLowerCase() === role && named(label)) return ["scrollintoview", `@${ref}`];
+	return null;
+}
+function spawnABRetrying(args, timeoutMs) {
 	let result = spawnABOnce(args, timeoutMs);
 	let elapsed = 0;
 	let attempt = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.60.0",
+  "version": "1.60.1",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {