ccqa 1.51.0 → 1.52.0

package/dist/runtime/step-evidence.cjs

@@ -0,0 +1,106 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_evidence_constants = require("../evidence-constants-BufWx8Bt.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+//#region src/runtime/step-evidence.ts
+/**
+* Caption recorded on the entry shot's metadata and cleared by
+* `ccqaStepAfter`. If the test dies inside the step, this is what survives —
+* so the report shows the failing step with the screen it started from,
+* marked failed, instead of dropping the step entirely.
+*/
+const INCOMPLETE_STEP_SUMMARY = "the test stopped inside this step (no closing screenshot)";
+/**
+* Capture the screen as the step is entered. Pair with `ccqaStepAfter` at the
+* end of the same step.
+*/
+async function ccqaStepBefore(page, stepId, source) {
+	const dir = process.env[require_evidence_constants.EVIDENCE_DIR_ENV];
+	if (!dir) return;
+	const id = require_evidence_constants.sanitizeStepId(stepId);
+	const beforeFile = `${id}.before.png`;
+	if (!await capture(page, dir, beforeFile)) return;
+	await writeMeta(page, dir, id, {
+		stepId,
+		source,
+		pngFile: beforeFile,
+		failureSummary: INCOMPLETE_STEP_SUMMARY
+	});
+}
+/**
+* Capture the screen as the step closes and finalise the step's metadata:
+* the closing shot becomes the step's primary screenshot, the entry shot (if
+* one was taken) rides along as `beforePngFile`, and the "did not complete"
+* caption written by `ccqaStepBefore` is cleared.
+*
+* If the closing shot itself fails, the step still COMPLETED — it just lost its
+* final frame. Rewrite the meta without the failure caption (keeping the entry
+* shot as the frame) so a passing step doesn't render red; the capture failure
+* is surfaced via the stderr warn in `capture()`.
+*/
+async function ccqaStepAfter(page, stepId, source) {
+	const dir = process.env[require_evidence_constants.EVIDENCE_DIR_ENV];
+	if (!dir) return;
+	const id = require_evidence_constants.sanitizeStepId(stepId);
+	const afterFile = `${id}.png`;
+	const beforeFile = `${id}.before.png`;
+	const hasBefore = (0, node_fs.existsSync)((0, node_path.join)(dir, beforeFile));
+	if (!await capture(page, dir, afterFile)) {
+		if (hasBefore) await writeMeta(page, dir, id, {
+			stepId,
+			source,
+			pngFile: beforeFile
+		});
+		return;
+	}
+	await writeMeta(page, dir, id, {
+		stepId,
+		source,
+		pngFile: afterFile,
+		...hasBefore ? { beforePngFile: beforeFile } : {}
+	});
+}
+/** Screenshot into `<dir>/<file>`; false when the shot could not be taken. */
+async function capture(page, dir, file) {
+	try {
+		(0, node_fs.mkdirSync)(dir, { recursive: true });
+		await page.screenshot({ path: (0, node_path.join)(dir, file) });
+		return true;
+	} catch (e) {
+		warn(`screenshot failed for ${file} (${message(e)})`);
+		return false;
+	}
+}
+/**
+* Write the step's meta sidecar. `url`/`title` are read here rather than by
+* the caller so a page that cannot answer them still yields a usable record
+* (the screenshot alone is worth keeping).
+*/
+async function writeMeta(page, dir, id, fields) {
+	let url = null;
+	let title = null;
+	try {
+		url = page.url();
+		title = await page.title();
+	} catch {}
+	const meta = {
+		...fields,
+		url,
+		title,
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		(0, node_fs.writeFileSync)((0, node_path.join)(dir, `${id}.json`), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+	} catch (e) {
+		warn(`meta write failed for ${id} (${message(e)})`);
+	}
+}
+function message(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+function warn(text) {
+	process.stderr.write(`[ccqa] step-evidence: ${text}\n`);
+}
+//#endregion
+exports.ccqaStepAfter = ccqaStepAfter;
+exports.ccqaStepBefore = ccqaStepBefore;

package/dist/runtime/step-evidence.d.cts

@@ -0,0 +1,53 @@
+//#region src/runtime/step-evidence.d.ts
+/**
+ * Step-boundary screenshot capture for tests ccqa generates for external
+ * targets (Playwright today). Generated tests import this through the
+ * `ccqa/step-evidence` subpath and call it at each spec-step boundary; the
+ * `<id>.png` + `<id>.json` pairs it writes are exactly what `ccqa run`'s
+ * report loader consumes, so an external target's rows carry the same
+ * per-step evidence the built-in agent-browser path produces.
+ *
+ * Two constraints shape the whole module:
+ *
+ *   - **No test-framework dependency.** The page handle is typed
+ *     structurally, so ccqa never imports `@playwright/test` and a consumer
+ *     installs nothing beyond ccqa itself. Any object exposing these three
+ *     members works — including a Playwright `Page`.
+ *   - **Never fail the user's test.** Capture is best-effort: every error is
+ *     swallowed with a stderr note. A missing screenshot costs a frame in the
+ *     report; it must never flip a passing spec to red.
+ *
+ * Capture is opt-in at runtime via `CCQA_EVIDENCE_DIR`, which only `ccqa run`
+ * sets. Running the generated test directly (or through the generation-time
+ * verify/fix loop) writes nothing.
+ */
+/**
+ * The subset of a browser page this module needs. Structural by design — see
+ * the module comment.
+ */
+interface CcqaEvidencePage {
+  screenshot(options: {
+    path: string;
+  }): Promise<unknown>;
+  url(): string;
+  title(): Promise<string>;
+}
+/**
+ * Capture the screen as the step is entered. Pair with `ccqaStepAfter` at the
+ * end of the same step.
+ */
+declare function ccqaStepBefore(page: CcqaEvidencePage, stepId: string, source: string): Promise<void>;
+/**
+ * Capture the screen as the step closes and finalise the step's metadata:
+ * the closing shot becomes the step's primary screenshot, the entry shot (if
+ * one was taken) rides along as `beforePngFile`, and the "did not complete"
+ * caption written by `ccqaStepBefore` is cleared.
+ *
+ * If the closing shot itself fails, the step still COMPLETED — it just lost its
+ * final frame. Rewrite the meta without the failure caption (keeping the entry
+ * shot as the frame) so a passing step doesn't render red; the capture failure
+ * is surfaced via the stderr warn in `capture()`.
+ */
+declare function ccqaStepAfter(page: CcqaEvidencePage, stepId: string, source: string): Promise<void>;
+//#endregion
+export { CcqaEvidencePage, ccqaStepAfter, ccqaStepBefore };

package/dist/runtime/step-evidence.mjs

@@ -1,4 +1,4 @@
-import { i as sanitizeStepId, t as EVIDENCE_DIR_ENV } from "../evidence-constants-Cm_S_5od.mjs";
+import { i as sanitizeStepId, t as EVIDENCE_DIR_ENV } from "../evidence-constants-C425F7ZG.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/runtime/step-evidence.ts

package/dist/runtime/test-helpers.cjs

@@ -0,0 +1,461 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_evidence_constants = require("../evidence-constants-BufWx8Bt.cjs");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
+let node_child_process = require("node:child_process");
+//#region src/runtime/agent-browser-bin.ts
+const require$1 = (0, require("node:module").createRequire)(require("url").pathToFileURL(__filename).href);
+function hasAgentBrowserShim(dir) {
+	try {
+		(0, node_fs.statSync)((0, node_path.join)(dir, "agent-browser"));
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Walks up from `start` looking for a `node_modules/.bin/agent-browser` shim.
+* Returns the .bin directory containing the shim, or null if none is found.
+*/
+function findNodeModulesBin(start) {
+	let cur = start;
+	while (true) {
+		const candidate = (0, node_path.join)(cur, "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+		const parent = (0, node_path.dirname)(cur);
+		if (parent === cur) return null;
+		cur = parent;
+	}
+}
+/** The shim-directory walk shared by every resolution below (no env override). */
+function resolveShimDir() {
+	const fromCwd = findNodeModulesBin(process.cwd());
+	if (fromCwd) return fromCwd;
+	const fromSelf = findNodeModulesBin((0, node_path.dirname)(require$1.resolve("agent-browser/package.json")));
+	if (fromSelf) return fromSelf;
+	try {
+		const candidate = (0, node_path.join)((0, node_path.dirname)(require$1.resolve("agent-browser/package.json")), "node_modules", ".bin");
+		if (hasAgentBrowserShim(candidate)) return candidate;
+	} catch {}
+	return null;
+}
+/**
+* INVARIANT: every agent-browser invocation in one ccqa process — the host
+* side (`spawnAB`: state load, replay probes, …) and the Claude subprocess
+* (via the PATH prepended by `pathWithAgentBrowserShim`) — must resolve to
+* the SAME binary. agent-browser runs one daemon per binary, and a state
+* loaded into one daemon's session is invisible to a same-named session on
+* another daemon, so a split resolution silently loses session restores.
+* Both entry points below therefore share one resolution order:
+* `CCQA_AB_BIN` (explicit override, e.g. the e2e harness or a dev build
+* driving a consumer project's agent-browser) → the peer-installed shim
+* (consumer project first, then ccqa's own tree).
+*/
+/**
+* Resolves the executable `spawnAB` should invoke. Falls back to the package
+* JS entry (resolvable whenever the peer dependency is installed) when no
+* shim directory exists; throws only if agent-browser is missing entirely.
+*/
+function resolveAgentBrowserBin() {
+	const override = process.env["CCQA_AB_BIN"];
+	if (override) return override;
+	const shimDir = resolveShimDir();
+	if (shimDir) return (0, node_path.join)(shimDir, "agent-browser");
+	return require$1.resolve("agent-browser/bin/agent-browser.js");
+}
+//#endregion
+//#region src/runtime/spawn-ab.ts
+const AB = resolveAgentBrowserBin();
+const EAGAIN_PATTERN = /Resource temporarily unavailable|os error 35/i;
+const EAGAIN_TOTAL_BUDGET_MS = 3e4;
+const EAGAIN_BACKOFF_MS = [
+	100,
+	200,
+	300,
+	500,
+	700,
+	1e3,
+	1500,
+	2e3,
+	2500,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3,
+	3e3
+];
+const PROCESS_HARD_TIMEOUT_MS = 35e3;
+function sleepSync(ms) {
+	const buf = new SharedArrayBuffer(4);
+	Atomics.wait(new Int32Array(buf), 0, 0, ms);
+}
+function spawnABOnce(args, timeoutMs) {
+	const result = (0, node_child_process.spawnSync)(AB, args, {
+		stdio: "pipe",
+		timeout: timeoutMs
+	});
+	const wedged = result.error?.code === "ETIMEDOUT";
+	return {
+		status: result.status,
+		stdout: result.stdout?.toString() ?? "",
+		stderr: (result.stderr?.toString() ?? "") + (wedged ? `\n[ccqa] agent-browser ${subcommand(args)} did not answer in ${timeoutMs}ms — killed after hard timeout` : ""),
+		wedged
+	};
+}
+/** The verb a reader recognises, past the one prefix every caller writes. */
+function subcommand(args) {
+	return (args[0] === "--session" ? args[2] : args[0]) ?? "(no command)";
+}
+/**
+* Invoke `agent-browser` once and return its exit status/stdout/stderr,
+* retrying internally up to ~30s while the daemon's state file is in the
+* "Resource temporarily unavailable" race window. Used by both the test
+* runtime (`test-helpers.ts`) and the post-trace replay validation
+* (`replay-validate.ts`). Kept out of `test-helpers.ts` because that
+* module is also the public surface for generated test scripts — exposing
+* the raw spawner there would widen the contract for end users.
+*/
+function spawnAB(args, opts) {
+	const timeoutMs = opts?.timeoutMs ?? PROCESS_HARD_TIMEOUT_MS;
+	let result = spawnABOnce(args, timeoutMs);
+	let elapsed = 0;
+	let attempt = 0;
+	while (result.status !== 0 && elapsed < EAGAIN_TOTAL_BUDGET_MS) {
+		const combined = `${result.stdout}\n${result.stderr}`;
+		if (!EAGAIN_PATTERN.test(combined)) return result;
+		const wait = EAGAIN_BACKOFF_MS[attempt] ?? 3e3;
+		sleepSync(wait);
+		elapsed += wait;
+		attempt++;
+		result = spawnABOnce(args, timeoutMs);
+	}
+	return result;
+}
+//#endregion
+//#region src/runtime/test-helpers.ts
+const POST_OPEN_SETTLE_MS = 600;
+function logStep(action, args) {
+	const pretty = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join("  ");
+	process.stdout.write(`  ▶ ${action.padEnd(14)} ${pretty}\n`);
+}
+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 = require_evidence_constants.sanitizeStepId(currentStep.stepId);
+		captureEvidence({
+			stepId: currentStep.stepId,
+			source: currentStep.source,
+			pngFile: `${safe}.png`,
+			failureSummary: summary,
+			silent: true
+		});
+		return;
+	}
+	captureEvidence({
+		stepId: require_evidence_constants.FAILURE_STEP_ID,
+		source: require_evidence_constants.FAILURE_SOURCE,
+		pngFile: "failure.png",
+		failureSummary: summary,
+		silent: true
+	});
+}
+function ab(...args) {
+	const [command = "", ...rest] = args;
+	logStep(command, rest);
+	const result = spawnAB(args);
+	if (result.status !== 0) fail(`agent-browser ${command} failed (exit ${result.status})`, result);
+	if (command === "open") sleepSync(POST_OPEN_SETTLE_MS);
+}
+const SELECTOR_POLL_INTERVAL_MS = 500;
+function selectorCount(selector) {
+	const r = spawnAB([
+		"get",
+		"count",
+		selector
+	]);
+	if (r.status !== 0) return 0;
+	const n = Number.parseInt(r.stdout.trim(), 10);
+	return Number.isNaN(n) ? 0 : n;
+}
+/**
+* Poll until `get count <selector>` reaches the desired presence state or the
+* timeout elapses. `want: "present"` waits for >=1 match; `"absent"` waits for
+* 0 matches. Returns true on success, false on timeout.
+*/
+function pollSelector(selector, want, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		const count = selectorCount(selector);
+		if (want === "present" ? count > 0 : count === 0) return true;
+		if (Date.now() >= deadline) return false;
+		sleepSync(SELECTOR_POLL_INTERVAL_MS);
+	}
+}
+/** Wait for element/text with an explicit timeout so long-running async ops don't hang. */
+function abWait(selector, timeoutMs = 3e4) {
+	logStep("wait", [selector]);
+	if (selector.startsWith("text=")) {
+		const result = spawnAB([
+			"wait",
+			"--text",
+			selector.slice(5),
+			"--timeout",
+			String(timeoutMs)
+		]);
+		if (result.status !== 0) fail(`wait failed: ${selector}`, result);
+		return;
+	}
+	if (!pollSelector(selector, "present", timeoutMs)) fail(`wait failed: ${selector} not present within ${timeoutMs}ms`, {
+		status: 1,
+		stdout: "",
+		stderr: ""
+	});
+}
+/**
+* Upload one or more files to a file input via `agent-browser upload`.
+* Relative paths resolve against the test's cwd. We pre-check existence
+* locally so a typo in a fixture path surfaces as a clear error before
+* agent-browser exits with an opaque non-zero status.
+*/
+function abUpload(selector, ...files) {
+	logStep("upload", [selector, ...files]);
+	const resolved = [];
+	for (const file of files) {
+		const abs = (0, node_path.isAbsolute)(file) ? file : (0, node_path.resolve)(process.cwd(), file);
+		if (!(0, node_fs.existsSync)(abs)) fail(`abUpload: file not found (${file} → ${abs})`, {
+			status: 1,
+			stdout: "",
+			stderr: ""
+		});
+		resolved.push(abs);
+	}
+	const result = spawnAB([
+		"upload",
+		selector,
+		...resolved
+	]);
+	if (result.status !== 0) fail(`agent-browser upload failed (exit ${result.status})`, result);
+}
+/** Assert stable text is visible on page (via wait --text). */
+function abAssertTextVisible(text, timeoutMs = 3e4) {
+	logStep("assert.text", [text]);
+	const result = spawnAB([
+		"wait",
+		"--text",
+		text,
+		"--timeout",
+		String(timeoutMs)
+	]);
+	if (result.status !== 0) fail(`Assertion failed: text ${JSON.stringify(text)} not found within ${timeoutMs}ms`, result);
+}
+/** Assert element is visible (polls `get count`; never uses the blocking `wait <selector>`). */
+function abAssertVisible(selector, timeoutMs = 3e4) {
+	logStep("assert.visible", [selector]);
+	if (selector.startsWith("text=")) {
+		const result = spawnAB([
+			"wait",
+			"--text",
+			selector.slice(5),
+			"--timeout",
+			String(timeoutMs)
+		]);
+		if (result.status !== 0) fail(`Assertion failed: ${JSON.stringify(selector)} not visible within ${timeoutMs}ms`, result);
+		return;
+	}
+	if (!pollSelector(selector, "present", timeoutMs)) fail(`Assertion failed: ${JSON.stringify(selector)} not visible within ${timeoutMs}ms`, {
+		status: 1,
+		stdout: "",
+		stderr: ""
+	});
+}
+/** Assert element is NOT visible (polls `get count` for absence; --fn for text). */
+function abAssertNotVisible(selector, timeoutMs = 3e4) {
+	logStep("assert.hidden", [selector]);
+	if (selector.startsWith("text=")) {
+		const result = spawnAB([
+			"wait",
+			"--fn",
+			`!document.body.innerText.includes(${JSON.stringify(selector.slice(5))})`,
+			"--timeout",
+			String(timeoutMs)
+		]);
+		if (result.status !== 0) fail(`Assertion failed: ${JSON.stringify(selector)} still visible after ${timeoutMs}ms`, result);
+		return;
+	}
+	if (!pollSelector(selector, "absent", timeoutMs)) fail(`Assertion failed: ${JSON.stringify(selector)} still visible after ${timeoutMs}ms`, {
+		status: 1,
+		stdout: "",
+		stderr: ""
+	});
+}
+/** Assert URL contains a pattern (via get url). */
+function abAssertUrl(pattern) {
+	logStep("assert.url", [pattern]);
+	const result = spawnAB(["get", "url"]);
+	const url = result.stdout.trim();
+	if (!url.includes(pattern)) fail(`Assertion failed: URL ${JSON.stringify(url)} does not contain ${JSON.stringify(pattern)}`, result);
+}
+/** Assert element is enabled (via is enabled). */
+function abAssertEnabled(selector) {
+	logStep("assert.enabled", [selector]);
+	const result = spawnAB([
+		"is",
+		"enabled",
+		selector
+	]);
+	if (result.status !== 0) fail(`Assertion failed: element ${JSON.stringify(selector)} not found`, result);
+	const value = result.stdout.trim();
+	if (value !== "true") fail(`Assertion failed: ${JSON.stringify(selector)} is not enabled (got: ${value})`, result);
+}
+/** Assert element is disabled (via is enabled). */
+function abAssertDisabled(selector) {
+	logStep("assert.disabled", [selector]);
+	const result = spawnAB([
+		"is",
+		"enabled",
+		selector
+	]);
+	if (result.status !== 0) fail(`Assertion failed: element ${JSON.stringify(selector)} not found`, result);
+	const value = result.stdout.trim();
+	if (value !== "false") fail(`Assertion failed: ${JSON.stringify(selector)} is not disabled (got: ${value})`, result);
+}
+/** Assert checkbox is checked (via is checked). */
+function abAssertChecked(selector) {
+	logStep("assert.checked", [selector]);
+	const result = spawnAB([
+		"is",
+		"checked",
+		selector
+	]);
+	if (result.status !== 0) fail(`Assertion failed: element ${JSON.stringify(selector)} not found`, result);
+	const value = result.stdout.trim();
+	if (value !== "true") fail(`Assertion failed: ${JSON.stringify(selector)} is not checked (got: ${value})`, result);
+}
+/** Assert checkbox is unchecked (via is checked). */
+function abAssertUnchecked(selector) {
+	logStep("assert.unchecked", [selector]);
+	const result = spawnAB([
+		"is",
+		"checked",
+		selector
+	]);
+	if (result.status !== 0) fail(`Assertion failed: element ${JSON.stringify(selector)} not found`, result);
+	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: `${require_evidence_constants.sanitizeStepId(stepId)}.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[require_evidence_constants.EVIDENCE_DIR_ENV];
+	if (!dir) return;
+	const { stepId, source, pngFile, failureSummary, silent } = opts;
+	const pngPath = (0, node_path.join)(dir, pngFile);
+	const metaPath = (0, node_path.join)(dir, pngFile.replace(/\.png$/, ".json"));
+	try {
+		(0, node_fs.mkdirSync)((0, node_path.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 {
+		(0, node_fs.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
+exports.__setCurrentStep = __setCurrentStep;
+exports.ab = ab;
+exports.abAssertChecked = abAssertChecked;
+exports.abAssertDisabled = abAssertDisabled;
+exports.abAssertEnabled = abAssertEnabled;
+exports.abAssertNotVisible = abAssertNotVisible;
+exports.abAssertTextVisible = abAssertTextVisible;
+exports.abAssertUnchecked = abAssertUnchecked;
+exports.abAssertUrl = abAssertUrl;
+exports.abAssertVisible = abAssertVisible;
+exports.abStepEvidence = abStepEvidence;
+exports.abUpload = abUpload;
+exports.abWait = abWait;

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

@@ -0,0 +1,39 @@
+//#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;
+/**
+ * Upload one or more files to a file input via `agent-browser upload`.
+ * Relative paths resolve against the test's cwd. We pre-check existence
+ * locally so a typo in a fixture path surfaces as a clear error before
+ * agent-browser exits with an opaque non-zero status.
+ */
+declare function abUpload(selector: string, ...files: string[]): void;
+/** Assert stable text is visible on page (via wait --text). */
+declare function abAssertTextVisible(text: string, timeoutMs?: number): void;
+/** Assert element is visible (polls `get count`; never uses the blocking `wait <selector>`). */
+declare function abAssertVisible(selector: string, timeoutMs?: number): void;
+/** Assert element is NOT visible (polls `get count` for absence; --fn for text). */
+declare function abAssertNotVisible(selector: string, timeoutMs?: number): void;
+/** Assert URL contains a pattern (via get url). */
+declare function abAssertUrl(pattern: string): void;
+/** Assert element is enabled (via is enabled). */
+declare function abAssertEnabled(selector: string): void;
+/** Assert element is disabled (via is enabled). */
+declare function abAssertDisabled(selector: string): void;
+/** Assert checkbox is checked (via is checked). */
+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 { __setCurrentStep, ab, abAssertChecked, abAssertDisabled, abAssertEnabled, abAssertNotVisible, abAssertTextVisible, abAssertUnchecked, abAssertUrl, abAssertVisible, abStepEvidence, abUpload, abWait };