ccqa 0.7.0 → 0.8.0

package/dist/package.json

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

package/dist/runtime/test-helpers.d.mts

@@ -1,4 +1,5 @@
 //#region src/runtime/test-helpers.d.ts
+declare function __setCurrentStep(stepId: string, source: string): void;
 declare function ab(...args: string[]): void;
 /** Wait for element/text with an explicit timeout so long-running async ops don't hang. */
 declare function abWait(selector: string, timeoutMs?: number): void;
@@ -18,5 +19,14 @@ declare function abAssertDisabled(selector: string): void;
 declare function abAssertChecked(selector: string): void;
 /** Assert checkbox is unchecked (via is checked). */
 declare function abAssertUnchecked(selector: string): void;
+/**
+ * Capture a step-boundary evidence pair (PNG + JSON metadata) so a reviewer
+ * can confirm at a glance that a passing spec actually drove the app to the
+ * state its `expected` describes. Opt-in at runtime via `CCQA_EVIDENCE_DIR` so
+ * generated scripts hand-run outside `ccqa run` don't write stray files. All
+ * errors are swallowed with a stderr warning — evidence capture must never
+ * flip a passing spec to red.
+ */
+declare function abStepEvidence(stepId: string, source: string): void;
 //#endregion
-export { ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abWait };
+export { __setCurrentStep, ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abStepEvidence, abWait };

package/dist/runtime/test-helpers.mjs

@@ -1,4 +1,6 @@
-import { n as spawnAB, t as sleepSync } from "../spawn-ab-DjRh1-4T.mjs";
+import { i as FAILURE_STEP_ID, n as spawnAB, r as FAILURE_SOURCE, t as sleepSync } from "../spawn-ab-Ja8NRRab.mjs";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 //#region src/runtime/test-helpers.ts
 const POST_OPEN_SETTLE_MS = 600;
 function logStep(action, args) {
@@ -9,8 +11,43 @@ function fail(summary, result) {
 	process.stdout.write(`  ✗ ${summary}\n`);
 	const details = [result.stdout, result.stderr].map((s) => s.trim()).filter(Boolean).join("\n");
 	if (details) for (const line of details.split("\n")) process.stdout.write(`      ${line}\n`);
+	captureFailureEvidence(summary);
 	throw new Error(summary);
 }
+/**
+* Tracks the step the test is currently inside. The codegen emits one of these
+* calls right after every `// step: ...` marker so when fail() fires we know
+* which step to attribute the failure to. Older generated scripts that don't
+* emit this still work — captureFailureEvidence() falls back to a generic
+* `failure.png` when currentStep is null.
+*/
+let currentStep = null;
+function __setCurrentStep(stepId, source) {
+	currentStep = {
+		stepId,
+		source
+	};
+}
+function captureFailureEvidence(summary) {
+	if (currentStep) {
+		const safe = currentStep.stepId.replace(/[^A-Za-z0-9_.-]/g, "_");
+		captureEvidence({
+			stepId: currentStep.stepId,
+			source: currentStep.source,
+			pngFile: `${safe}.png`,
+			failureSummary: summary,
+			silent: true
+		});
+		return;
+	}
+	captureEvidence({
+		stepId: FAILURE_STEP_ID,
+		source: FAILURE_SOURCE,
+		pngFile: "failure.png",
+		failureSummary: summary,
+		silent: true
+	});
+}
 function ab(...args) {
 	const [command = "", ...rest] = args;
 	logStep(command, rest);
@@ -170,5 +207,86 @@ function abAssertUnchecked(selector) {
 	const value = result.stdout.trim();
 	if (value !== "false") fail(`Assertion failed: ${JSON.stringify(selector)} is not unchecked (got: ${value})`, result);
 }
+/**
+* Capture a step-boundary evidence pair (PNG + JSON metadata) so a reviewer
+* can confirm at a glance that a passing spec actually drove the app to the
+* state its `expected` describes. Opt-in at runtime via `CCQA_EVIDENCE_DIR` so
+* generated scripts hand-run outside `ccqa run` don't write stray files. All
+* errors are swallowed with a stderr warning — evidence capture must never
+* flip a passing spec to red.
+*/
+function abStepEvidence(stepId, source) {
+	captureEvidence({
+		stepId,
+		source,
+		pngFile: `${stepId.replace(/[^A-Za-z0-9_.-]/g, "_")}.png`
+	});
+	if (currentStep && currentStep.stepId === stepId) currentStep = null;
+}
+/**
+* Shared screenshot+meta pipeline behind both abStepEvidence (step boundary)
+* and captureFailureEvidence (called from fail()). The url/title eval is one
+* round-trip; agent-browser wraps eval output in JSON.stringify, so the JS
+* expression must itself stringify the payload — hence the double JSON.parse.
+*/
+function captureEvidence(opts) {
+	const dir = process.env["CCQA_EVIDENCE_DIR"];
+	if (!dir) return;
+	const { stepId, source, pngFile, failureSummary, silent } = opts;
+	const pngPath = join(dir, pngFile);
+	const metaPath = join(dir, pngFile.replace(/\.png$/, ".json"));
+	try {
+		mkdirSync(dirname(pngPath), { recursive: true });
+	} catch (e) {
+		if (!silent) warnEvidence(`mkdir failed (${e.message})`);
+		return;
+	}
+	if (!silent) logStep("evidence", [stepId]);
+	const shot = spawnAB(["screenshot", pngPath]);
+	if (shot.status !== 0) {
+		if (!silent) warnEvidence(`screenshot failed for ${stepId} (${shot.stderr.trim() || shot.stdout.trim()})`);
+		return;
+	}
+	const { url, title } = readPageContext();
+	const meta = {
+		stepId,
+		source,
+		url,
+		title,
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		pngFile
+	};
+	if (failureSummary !== void 0) meta["failureSummary"] = failureSummary;
+	try {
+		writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+	} catch (e) {
+		if (!silent) warnEvidence(`meta write failed (${e.message})`);
+	}
+}
+function readPageContext() {
+	const ctx = spawnAB(["eval", "JSON.stringify({url: location.href, title: document.title})"]);
+	if (ctx.status !== 0) return {
+		url: null,
+		title: null
+	};
+	try {
+		const outer = JSON.parse(ctx.stdout.trim());
+		const inner = typeof outer === "string" ? JSON.parse(outer) : outer;
+		if (inner && typeof inner === "object") {
+			const obj = inner;
+			return {
+				url: typeof obj.url === "string" ? obj.url : null,
+				title: typeof obj.title === "string" ? obj.title : null
+			};
+		}
+	} catch {}
+	return {
+		url: null,
+		title: null
+	};
+}
+function warnEvidence(msg) {
+	process.stderr.write(`[ccqa] evidence: ${msg}\n`);
+}
 //#endregion
-export { ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abWait };
+export { __setCurrentStep, ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abStepEvidence, abWait };

package/dist/{spawn-ab-DjRh1-4T.mjs → spawn-ab-Ja8NRRab.mjs}

@@ -1,5 +1,18 @@
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
+//#region src/runtime/evidence-constants.ts
+/**
+* Shared constants for step-boundary evidence captured by abStepEvidence() /
+* captureFailureEvidence() and consumed by the run report. Kept under
+* `runtime/` so the test-helpers module — which generated test scripts import
+* via `ccqa/test-helpers` — can stay free of CLI-side imports while still
+* sharing the literal with run.ts.
+*/
+/** stepId reserved for the screenshot captured by fail() at the moment of an assertion failure. */
+const FAILURE_STEP_ID = "failure";
+/** source value paired with FAILURE_STEP_ID so the report can tell failure captures apart from step captures. */
+const FAILURE_SOURCE = "failed";
+//#endregion
 //#region src/runtime/spawn-ab.ts
 const AB = createRequire(import.meta.url).resolve("agent-browser/bin/agent-browser.js");
 const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
@@ -62,4 +75,4 @@ function spawnAB(args) {
 	return result;
 }
 //#endregion
-export { spawnAB as n, sleepSync as t };
+export { FAILURE_STEP_ID as i, spawnAB as n, FAILURE_SOURCE as r, sleepSync as t };

package/package.json

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