@dev-blinq/bvt-playwright-js 1.0.0-dev.4.staging.135.1 → 1.0.0-dev.4.staging.155.1

package/index.mjs

@@ -6,8 +6,8 @@ import path, { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { chromium, firefox, webkit } from "playwright";
 import { expect } from "playwright/test";
-import { mkdirSync, readFileSync as readFileSync$1, statSync } from "fs";
-import { dirname as dirname$1 } from "path";
+import { mkdirSync, readFileSync as readFileSync$1, rmSync, statSync } from "fs";
+import { dirname as dirname$1, join } from "path";
 import { createContext, runInContext } from "node:vm";
 import { test } from "@playwright/test";
 
@@ -5162,6 +5162,17 @@ const primitiveOrRegex = discriminatedUnion("type", [
 	}).strict()
 ]);
 
+//#endregion
+//#region ../../core/schemas/src/assertions/assertion-operators.ts
+const ASSERTION_OPERATORS = [
+	"equals",
+	"notEquals",
+	"contains",
+	"lessThan",
+	"greaterThan",
+	"exists"
+];
+
 //#endregion
 //#region ../../core/schemas/src/api/api.schema.ts
 const numberAssertion = object({
@@ -5393,6 +5404,7 @@ const elementAssertionSchema = discriminatedUnion("type", [
 	object({
 		type: literal$1("toHaveProperty"),
 		name: string(),
+		operator: _enum(ASSERTION_OPERATORS).optional(),
 		value: primitiveOrRegex.optional(),
 		options: object({ timeout: number().optional() }).optional()
 	}),
@@ -6550,6 +6562,7 @@ const RichElementTargetDetailsSchema = object({
 }).passthrough();
 const elementTargetSchema = object({
 	name: string(),
+	isElementHidden: boolean().optional(),
 	uniqueSelectors: array(UniqueSelectorSchema),
 	frames: array(object({
 		name: string(),
@@ -6918,6 +6931,23 @@ const ProjectBrowserLaunchConfigurationSchema = object({
 }).strict();
 const ProjectGitCodegenFormats = ["playwright", "gherkin"];
 const ProjectGitCodegenFormatSchema = _enum(ProjectGitCodegenFormats).default("playwright");
+/**
+* Personalisation inputs for the analytics dashboard.
+*
+* These values drive the "Budget Saved", "Time Saved", and
+* "AI Work Time Distribution" widgets. All hours are in human-hours
+* (the unit the modal collects). The defaults match the legacy
+* Metabase queries' `$ifNull` fallbacks — projects that never
+* customise these still get sensible numbers on day one.
+*/
+const DashboardPersonalizationSchema = object({
+	hourlyRateForTestEngineer: number().nonnegative().default(50),
+	avgTimeToAutomateScenario: number().nonnegative().default(4),
+	avgTimeToAutomateScenarioUsingBlinqIO: number().nonnegative().default(.25),
+	avgTimeToMaintainScenario: number().nonnegative().default(2),
+	avgTimeToAnalyzeFailedScenario: number().nonnegative().default(2)
+}).strict();
+const DEFAULT_DASHBOARD_PERSONALIZATION = DashboardPersonalizationSchema.parse({});
 const ProjectSettingsSchema = object({
 	_id: EntityIdSchema,
 	projectId: EntityIdSchema,
@@ -6928,11 +6958,13 @@ const ProjectSettingsSchema = object({
 			width: 1280,
 			height: 900
 		} }
-	})
+	}),
+	dashboardPersonalization: DashboardPersonalizationSchema.default(DEFAULT_DASHBOARD_PERSONALIZATION)
 }).strict();
 const ProjectSettingsUpdatableFieldsSchema = ProjectSettingsSchema.omit({
 	_id: true,
-	projectId: true
+	projectId: true,
+	dashboardPersonalization: true
 });
 const DEFAULT_PROJECT_SETTINGS = ProjectSettingsUpdatableFieldsSchema.parse({});
 const GetProjectSettingsInputSchema = object({ projectId: EntityIdSchema }).strict();
@@ -7036,12 +7068,24 @@ const ExecResultSchema = discriminatedUnion("type", [
 	}).strict(),
 	object({ type: literal$1("skipped") }).strict()
 ]);
+/**
+* S3 keys for the before/after viewport screenshots captured around a single
+* command. Keys are deterministic (see the screenshot key convention in the
+* presigned-urls router) and are populated even before the batched upload runs;
+* the testcase-level {@link TestCaseSchema.shape.screenshotsAvailable} flag
+* indicates whether the objects were actually uploaded to S3.
+*/
+const CommandScreenshotsSchema = object({
+	before: string().min(1).max(1024).optional(),
+	after: string().min(1).max(1024).optional()
+}).strict();
 const CommandResultSchema = object({
 	commandId: string().min(1).max(255),
 	startedAt: date().optional(),
 	completedAt: date().optional(),
 	result: ExecResultSchema,
-	recovery: RecoveryMetadataSchema.optional()
+	recovery: RecoveryMetadataSchema.optional(),
+	screenshots: CommandScreenshotsSchema.optional()
 }).strict();
 const StepResultSchema = object({
 	stepId: string().min(1).max(255),
@@ -7069,6 +7113,7 @@ const TestCaseAiRecoverySchema = object({
 }).strict();
 const TestCaseWarningReasonSchema = _enum([
 	"TraceUploadFailed",
+	"ScreenshotUploadFailed",
 	"ScenarioEmpty",
 	"AIRecoveryPendingApproval",
 	"AIRecoveryArtifactFailed",
@@ -7089,6 +7134,7 @@ const TestCaseSchema = object({
 	error: TestCaseErrorSchema.optional(),
 	aiRecovery: TestCaseAiRecoverySchema.optional(),
 	warnings: array(TestCaseWarningSchema).optional(),
+	screenshotsAvailable: boolean().optional(),
 	startedAt: date(),
 	completedAt: date().nullable(),
 	stepResults: array(StepResultSchema),
@@ -26243,11 +26289,37 @@ function getResolvedChosenSelectorIndex(result) {
 	const candidate = result.resolvedChosenSelectorIndex;
 	return Number.isInteger(candidate) ? candidate : void 0;
 }
+async function delayNewTourMaintenanceRecovery(signal) {
+	if (signal?.aborted) throw new Error("Execution aborted");
+	await new Promise((resolve, reject) => {
+		let timeout;
+		function cleanup() {
+			signal?.removeEventListener("abort", handleAbort);
+		}
+		function handleAbort() {
+			clearTimeout(timeout);
+			cleanup();
+			reject(/* @__PURE__ */ new Error("Execution aborted"));
+		}
+		timeout = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, NEW_TOUR_MAINTENANCE_RECOVERY_DELAY_MS);
+		signal?.addEventListener("abort", handleAbort, { once: true });
+	});
+}
 const browserTypesMap = {
 	chromium,
 	firefox,
 	webkit
 };
+const NEW_TOUR_MAINTENANCE_RECOVERY_MODE = "new-tour-maintenance";
+const NEW_TOUR_MAINTENANCE_RECOVERY_DELAY_MS = 600;
+const NEW_TOUR_MAINTENANCE_RECOVERY_ARTIFACT = {
+	rootCauseAnalysis: "The application changed the Gender field from a dropdown in \"Old Version\" to radio buttons in \"New Version\".",
+	aiLog: "BlinqIO matched the original gender-selection intent to the new radio button UI and rewrote the stale command.",
+	description: "The repaired step selects the gender radio option, then continues the registration flow successfully."
+};
 const unconfiguredGetAPIClient = () => {
 	throw new Error("Tester was created without an API client.");
 };
@@ -26281,6 +26353,19 @@ var Tester = class {
 	sessionToken = "";
 	activeBrowserContext = null;
 	reportId = ulid();
+	tempPathForAssets = "";
+	/**
+	* Per-testcase log of before/after command screenshots captured on disk,
+	* pending batch upload to S3 at the end of the run. Reset in onTestCaseStart.
+	*/
+	capturedScreenshots = [];
+	/**
+	* Per-testcase screenshot counters (reset in onTestCaseStart) used purely for
+	* observability — how many commands were eligible for capture and how many
+	* capture attempts failed. Upload counters are derived at upload time.
+	*/
+	screenshotCommandsConsidered = 0;
+	screenshotCaptureFailures = 0;
 	constructor(getAPIClient = unconfiguredGetAPIClient, observabilityOrOptions, optionsArg = {}) {
 		this.getAPIClient = getAPIClient;
 		const isTesterOptions = observabilityOrOptions !== null && typeof observabilityOrOptions === "object" && ("commandPreprocessors" in observabilityOrOptions || "recoveryController" in observabilityOrOptions || "restoreStepStartForRepair" in observabilityOrOptions || "provider" in observabilityOrOptions || "getApiFetchImpl" in observabilityOrOptions || "stepTraceChunkCallbacks" in observabilityOrOptions || "context" in observabilityOrOptions || "onTestDataChange" in observabilityOrOptions || "customCodeRuntime" in observabilityOrOptions);
@@ -26357,6 +26442,87 @@ var Tester = class {
 			default: return `Unknown Command`;
 		}
 	}
+	screenshotsEnabled(session) {
+		return this.isRunSession(session) && session.screenshots?.enabled === true;
+	}
+	/**
+	* Deterministic S3 key for a command screenshot. Must match the convention
+	* used by the server's `getPresignedUrlsForScreenshotUpload` route so the
+	* keys recorded on the command report point at the uploaded objects.
+	*/
+	buildScreenshotKey(session, stepId, commandId, phase) {
+		return `${this.dataContext?.projectId ?? ""}/${session.reportId}/testcases/${session.testCaseId}/resources/screenshots/${stepId}-${commandId}-${phase}.jpg`;
+	}
+	getScreenshotTempDir(session) {
+		if (!this.tempPathForAssets) this.tempPathForAssets = join("/tmp", `blinq-screenshots-${session.reportId}-${session.testCaseId}`);
+		return this.tempPathForAssets;
+	}
+	/**
+	* Captures a viewport JPEG of the active page for the given command/phase,
+	* writes it to the per-testcase temp dir, and records it for later upload.
+	* Best-effort: any failure (no page, screenshot error) is logged and yields
+	* `undefined` so command execution is never affected.
+	*/
+	async captureCommandScreenshot(session, phase, stepId, commandId) {
+		if (!this.screenshotsEnabled(session) || !this.isRunSession(session)) return;
+		const page = this.lastActivePage;
+		if (!page) {
+			this.obs.metrics.count("bvt_agent.screenshots.capture.skipped.total", 1, {
+				phase,
+				reason: "no-active-page"
+			});
+			this.obs.logger.warn("Skipping command screenshot capture: no active page", {
+				stepId,
+				commandId,
+				phase
+			});
+			return;
+		}
+		const startMs = Date.now();
+		try {
+			const key = this.buildScreenshotKey(session, stepId, commandId, phase);
+			const dir = this.getScreenshotTempDir(session);
+			mkdirSync(dir, { recursive: true });
+			const localPath = join(dir, `${stepId}-${commandId}-${phase}.jpg`);
+			await page.screenshot({
+				path: localPath,
+				type: "jpeg",
+				quality: 70
+			});
+			this.capturedScreenshots.push({
+				stepId,
+				commandId,
+				phase,
+				localPath
+			});
+			this.obs.metrics.count("bvt_agent.screenshots.capture.succeeded.total", 1, { phase });
+			this.obs.metrics.latency("bvt_agent.screenshots.capture.duration", startMs, { phase });
+			this.obs.logger.log("Captured command screenshot", {
+				stepId,
+				commandId,
+				phase,
+				key
+			});
+			return key;
+		} catch (error) {
+			this.screenshotCaptureFailures += 1;
+			this.obs.metrics.count("bvt_agent.screenshots.capture.failed.total", 1, { phase });
+			this.obs.logger.warn("Command screenshot capture failed", {
+				stepId,
+				commandId,
+				phase,
+				error: this.summarizeErrorForExecutionLog(error)
+			});
+			return;
+		}
+	}
+	toScreenshotRefs(before, after) {
+		if (!before && !after) return;
+		return {
+			...before ? { before } : {},
+			...after ? { after } : {}
+		};
+	}
 	async onCommandStart(command, stepDefinitionId, session) {
 		this.obs.logger.log("Starting execution of command", {
 			commandId: command._id,
@@ -26423,10 +26589,11 @@ var Tester = class {
 			completedAt,
 			result: { type: "success" },
 			...typeof metadata?.resolvedChosenSelectorIndex === "number" ? { resolvedChosenSelectorIndex: metadata.resolvedChosenSelectorIndex } : {},
-			...metadata?.recovery ? { recovery: metadata.recovery } : {}
+			...metadata?.recovery ? { recovery: metadata.recovery } : {},
+			...metadata?.screenshots ? { screenshots: metadata.screenshots } : {}
 		};
 	}
-	async onCommandFail(command, stepDefinitionId, error, session, recovery) {
+	async onCommandFail(command, stepDefinitionId, error, session, recovery, screenshots) {
 		this.obs.logger.error(`Error executing command ${command._id}:`, { error: this.summarizeErrorForExecutionLog(error) });
 		if (session?.type === "run") {
 			this.obs.logger.log(`Ending Playwright tracing group for command: ${command._id}`);
@@ -26443,7 +26610,8 @@ var Tester = class {
 			stepDefinitionId,
 			completedAt,
 			result: this.toFailureResult(error),
-			recovery
+			recovery,
+			...screenshots ? { screenshots } : {}
 		};
 	}
 	async onStepStart(step, session) {
@@ -26496,6 +26664,10 @@ var Tester = class {
 	}
 	async onTestCaseStart(session) {
 		this.obs.logger.log(`Starting test case execution with session: ${JSON.stringify(session)}`);
+		this.capturedScreenshots = [];
+		this.tempPathForAssets = "";
+		this.screenshotCommandsConsidered = 0;
+		this.screenshotCaptureFailures = 0;
 		if (this.isRunSession(session)) {
 			if (session.token) this.sessionToken = session.token;
 			this.obs.logger.log(`Starting Playwright tracing for test case report (reportId: ${session.reportId}, testCaseId: ${session.testCaseId})...`);
@@ -26520,6 +26692,178 @@ var Tester = class {
 	shouldAttemptAiRecovery(session) {
 		return !session || this.isRecordingReplaySession(session) || session.type === "run" && session.runWithAiRecovery === true;
 	}
+	isNewTourMaintenanceRecoverySession(session) {
+		return session?.type === "run" && session.runWithAiRecovery === true && session.deterministicRecoveryMode === NEW_TOUR_MAINTENANCE_RECOVERY_MODE;
+	}
+	shouldUseNewTourMaintenanceRecovery(input) {
+		if (!this.isNewTourMaintenanceRecoverySession(input.session)) return false;
+		if (input.command.type !== "element.action" || input.commandIndex !== 0) return false;
+		const stepText = `${input.recorderStep.step.text} ${input.recorderStep.definition.displayName ?? ""}`;
+		return /gender/i.test(stepText) || /gender/i.test(input.command.target.name ?? "") || input.command.target.uniqueSelectors.some((selector) => selector.type === "pw.selectorString" ? /gender/i.test(selector.selectorString) : false);
+	}
+	inferNewTourGenderOption(recorderStep, failedCommandIndex) {
+		const nextCommand = recorderStep.definition.commands[failedCommandIndex + 1];
+		if (nextCommand?.type === "element.action" && (nextCommand.target.name === "Male" || nextCommand.target.name === "Female")) return nextCommand.target.name;
+		return "Male";
+	}
+	buildNewTourGenderRadioCommand(input) {
+		const optionSlug = input.option.toLowerCase();
+		return {
+			...input.originalCommand,
+			_id: ulid(),
+			data: {
+				type: "click",
+				options: {
+					force: true,
+					timeout: 15e3
+				}
+			},
+			target: {
+				...input.originalCommand.target,
+				name: input.option,
+				chosenSelectorIndex: 0,
+				uniqueSelectors: [
+					{
+						type: "pw.selectorString",
+						selectorString: `internal:label="${input.option}"s`,
+						strategy: "text",
+						description: `The ${input.option} radio option`
+					},
+					{
+						type: "pw.selectorString",
+						selectorString: `internal:role=radio[name="${input.option}"s]`,
+						strategy: "label",
+						description: `The radio button labeled "${input.option}"`
+					},
+					{
+						type: "pw.selectorString",
+						selectorString: `internal:testid=[data-testid="register-gender-${optionSlug}"s]`,
+						strategy: "css",
+						description: `The ${input.option} gender option`
+					},
+					{
+						type: "pw.selectorString",
+						selectorString: `input[type="radio"][value="${optionSlug}"]`,
+						strategy: "css",
+						description: `The ${input.option} gender radio input`
+					}
+				]
+			}
+		};
+	}
+	buildNewTourGenderRepairPlan(input) {
+		const nextCommand = input.recorderStep.definition.commands[input.failedCommandIndex + 1];
+		if (!(nextCommand?.type === "element.action" && (nextCommand.target.name === "Male" || nextCommand.target.name === "Female"))) return {
+			type: "single-command",
+			commandIndex: input.failedCommandIndex,
+			replacementCommand: input.replacementCommand,
+			preserveSuffix: true
+		};
+		return {
+			type: "command-operations",
+			operations: [{
+				type: "update",
+				commandIndex: input.failedCommandIndex,
+				replacementCommand: input.replacementCommand
+			}, {
+				type: "delete",
+				commandIndex: input.failedCommandIndex + 1
+			}],
+			preserveSuffix: true
+		};
+	}
+	async *recoverNewTourMaintenanceGenderCommand(input) {
+		const recoveryAttemptId = crypto.randomUUID();
+		const { recorderStep, command, commandIndex, commandContext, executionError, options } = input;
+		const option = this.inferNewTourGenderOption(recorderStep, commandIndex);
+		const replacementCommand = this.buildNewTourGenderRadioCommand({
+			originalCommand: command,
+			option
+		});
+		yield {
+			type: "recovery_status",
+			recoveryAttemptId,
+			stepId: recorderStep.step._id,
+			commandId: command._id,
+			phase: "analyzing",
+			message: "Analyzing failure",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await delayNewTourMaintenanceRecovery(options.abortController?.signal);
+		yield {
+			type: "recovery_status",
+			recoveryAttemptId,
+			stepId: recorderStep.step._id,
+			commandId: command._id,
+			phase: "trying_fix",
+			message: "AI Test Engineer is rewriting the gender selection step",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await delayNewTourMaintenanceRecovery(options.abortController?.signal);
+		yield {
+			type: "recovery_status",
+			recoveryAttemptId,
+			stepId: recorderStep.step._id,
+			commandId: command._id,
+			phase: "checking_fix",
+			message: "AI Test Engineer is checking the fix",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await this.executeCommand({
+			page: this.lastActivePage,
+			command: replacementCommand,
+			context: commandContext
+		});
+		const persistResult = persistStepRepair({
+			stepDefinition: recorderStep.definition,
+			plan: this.buildNewTourGenderRepairPlan({
+				recorderStep,
+				failedCommandIndex: commandIndex,
+				replacementCommand
+			})
+		});
+		if (!persistResult.success) throw new Error(persistResult.error);
+		const recoveryMeta = {
+			recoveryAttemptId,
+			originalCommandId: command._id,
+			stepId: recorderStep.step._id,
+			originalErrorMessage: executionError.message,
+			originalErrorStack: executionError.stack,
+			rcaLabel: "demo-gender-control-changed",
+			rcaConfidence: 1,
+			rootCauseAnalysis: NEW_TOUR_MAINTENANCE_RECOVERY_ARTIFACT.rootCauseAnalysis,
+			evidenceSignalNames: ["new_tour_maintenance_gender_radio_demo"],
+			targetElementSnapshot: {
+				accessibleName: option,
+				role: "radio",
+				text: option,
+				labelText: option
+			},
+			actionVerb: "click",
+			commandPatchSummary: "Updated the gender selection step from the old dropdown to the new radio button UI",
+			retryOutcome: "passed",
+			recoveredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			healedLocatorPersistedAt: persistResult.persistedAt,
+			stepDefinitionPatch: {
+				stepDefinitionId: recorderStep.definition._id,
+				commands: persistResult.commands,
+				changedCommandIds: persistResult.changedCommandIds,
+				preservedCommandIds: persistResult.preservedCommandIds,
+				persistedAt: persistResult.persistedAt
+			}
+		};
+		yield {
+			type: "recovery_status",
+			recoveryAttemptId,
+			stepId: recorderStep.step._id,
+			commandId: command._id,
+			phase: "fixed",
+			message: "AI recovered the gender selection step",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			artifact: NEW_TOUR_MAINTENANCE_RECOVERY_ARTIFACT
+		};
+		return recoveryMeta;
+	}
 	isSupportedRepairContext(decision, session) {
 		if (decision.kind !== "step-repair") return false;
 		if (this.isRecordingReplaySession(session) || !session) return decision.repairContext === "recorder-replay";
@@ -26602,12 +26946,12 @@ var Tester = class {
 			setTimeout(resolve, ms);
 		});
 	}
-	async uploadFile(presignedUrl, filePath) {
+	async uploadFile(presignedUrl, filePath, contentType = "application/zip") {
 		const fileData = readFileSync$1(filePath);
 		this.obs.logger.log(`Uploading file from ${filePath} (size=${fileData.byteLength} bytes) via PUT`);
 		const response = await fetch(presignedUrl, {
 			method: "PUT",
-			headers: { "Content-Type": "application/zip" },
+			headers: { "Content-Type": contentType },
 			body: fileData
 		});
 		if (!response.ok) throw new Error(`Failed to upload file. Status: ${response.status}:  ${await response.text()}`);
@@ -26637,6 +26981,146 @@ var Tester = class {
 		}
 		return false;
 	}
+	async putFileWithRetries(input) {
+		const maxAttempts = 3;
+		const baseDelayMs = 250;
+		for (let attempt = 1; attempt <= maxAttempts; attempt += 1) try {
+			await this.uploadFile(input.presignedUrl, input.filePath, input.contentType);
+			return true;
+		} catch (error) {
+			if (attempt === maxAttempts) {
+				this.obs.logger.error(`${input.label} upload failed after ${maxAttempts} attempts`, error);
+				return false;
+			}
+			const delayMs = baseDelayMs * 2 ** (attempt - 1);
+			this.obs.logger.warn(`${input.label} upload failed, retrying`, {
+				attempt,
+				maxAttempts,
+				delayMs,
+				error: this.summarizeErrorForExecutionLog(error)
+			});
+			await this.wait(delayMs);
+		}
+		return false;
+	}
+	cleanupScreenshotTempDir() {
+		if (!this.tempPathForAssets) return;
+		try {
+			rmSync(this.tempPathForAssets, {
+				recursive: true,
+				force: true
+			});
+		} catch (error) {
+			this.obs.logger.warn("Failed to clean up screenshot temp dir", {
+				dir: this.tempPathForAssets,
+				error: this.summarizeErrorForExecutionLog(error)
+			});
+		} finally {
+			this.tempPathForAssets = "";
+		}
+	}
+	/**
+	* Batch-uploads all command screenshots captured during the run to S3.
+	* Fetches a presigned PUT URL per file in a single round-trip, then uploads
+	* each with retries. Best-effort: returns true when at least one screenshot
+	* was uploaded, false otherwise (or when there is nothing/no token). Always
+	* cleans up the on-disk temp files. Never throws.
+	*/
+	async uploadScreenshots(session) {
+		const screenshots = this.capturedScreenshots;
+		const capturedCount = screenshots.length;
+		const distinctCommandsCaptured = new Set(screenshots.map((shot) => shot.commandId)).size;
+		const commandsConsidered = this.screenshotCommandsConsidered;
+		const captureFailures = this.screenshotCaptureFailures;
+		this.obs.metrics.gauge("bvt_agent.screenshots.commands_considered", commandsConsidered);
+		this.obs.metrics.gauge("bvt_agent.screenshots.captured", capturedCount);
+		this.obs.metrics.gauge("bvt_agent.screenshots.distinct_commands_captured", distinctCommandsCaptured);
+		if (capturedCount === 0) {
+			this.obs.logger.log("No command screenshots captured; skipping upload", {
+				reportId: session.reportId,
+				testCaseId: session.testCaseId,
+				commandsConsidered,
+				captureFailures
+			});
+			return false;
+		}
+		if (!session.token) {
+			this.obs.metrics.count("bvt_agent.screenshots.upload.skipped.total", 1, { reason: "no-session-token" });
+			this.obs.logger.warn(`Screenshot upload skipped because no session token was provided for reportId: ${session.reportId}, testCaseId: ${session.testCaseId}.`);
+			this.cleanupScreenshotTempDir();
+			this.capturedScreenshots = [];
+			return false;
+		}
+		const uploadStartMs = Date.now();
+		try {
+			this.obs.logger.log(`Requesting ${screenshots.length} presigned URL(s) for screenshot upload`, {
+				reportId: session.reportId,
+				testCaseId: session.testCaseId
+			});
+			const targets = await this.getAPIClient(this.sessionToken).presignedUrls.getPresignedUrlsForScreenshotUpload.query({
+				reportId: session.reportId,
+				testCaseId: session.testCaseId,
+				projectId: this.dataContext?.projectId ?? "",
+				files: screenshots.map(({ stepId, commandId, phase }) => ({
+					stepId,
+					commandId,
+					phase
+				}))
+			});
+			const urlByTargetKey = new Map(targets.map((target) => [`${target.stepId}-${target.commandId}-${target.phase}`, target.url]));
+			let uploadedCount = 0;
+			let failedCount = 0;
+			for (const shot of screenshots) {
+				const presignedUrl = urlByTargetKey.get(`${shot.stepId}-${shot.commandId}-${shot.phase}`);
+				if (!presignedUrl) {
+					failedCount += 1;
+					this.obs.metrics.count("bvt_agent.screenshots.upload.failed.total", 1, { reason: "no-presigned-url" });
+					this.obs.logger.warn("No presigned URL returned for screenshot", {
+						stepId: shot.stepId,
+						commandId: shot.commandId,
+						phase: shot.phase
+					});
+					continue;
+				}
+				if (await this.putFileWithRetries({
+					presignedUrl,
+					filePath: shot.localPath,
+					contentType: "image/jpeg",
+					label: "Screenshot"
+				})) {
+					uploadedCount += 1;
+					this.obs.metrics.count("bvt_agent.screenshots.upload.succeeded.total", 1, { phase: shot.phase });
+				} else {
+					failedCount += 1;
+					this.obs.metrics.count("bvt_agent.screenshots.upload.failed.total", 1, { reason: "put-failed" });
+				}
+			}
+			this.obs.metrics.latency("bvt_agent.screenshots.upload.duration", uploadStartMs, { outcome: uploadedCount > 0 ? "success" : "failure" });
+			this.obs.logger.log(`Screenshot upload finished: ${uploadedCount}/${capturedCount} uploaded, ${failedCount} failed`, {
+				reportId: session.reportId,
+				testCaseId: session.testCaseId,
+				commandsConsidered,
+				distinctCommandsCaptured,
+				capturedCount,
+				uploadedCount,
+				failedCount,
+				captureFailures
+			});
+			return uploadedCount > 0;
+		} catch (error) {
+			this.obs.metrics.count("bvt_agent.screenshots.upload.failed.total", capturedCount, { reason: "batch-error" });
+			this.obs.metrics.latency("bvt_agent.screenshots.upload.duration", uploadStartMs, { outcome: "error" });
+			this.obs.logger.warn(`Screenshot upload failed for reportId: ${session.reportId}, testCaseId: ${session.testCaseId}. Continuing without failing execution result.`, {
+				error: this.summarizeErrorForExecutionLog(error),
+				capturedCount,
+				commandsConsidered
+			});
+			return false;
+		} finally {
+			this.cleanupScreenshotTempDir();
+			this.capturedScreenshots = [];
+		}
+	}
 	async onTestCaseFail(error, session) {
 		this.obs.logger.error("Test case execution failed", {
 			session: this.summarizeSessionForExecutionLog(session),
@@ -26741,8 +27225,11 @@ var Tester = class {
 				commandId: command._id,
 				commandType: command.type
 			});
+			let beforeScreenshotKey;
+			if (this.screenshotsEnabled(session)) this.screenshotCommandsConsidered += 1;
 			try {
 				yield await this.onCommandStart(command, stepDefinitionId, session);
+				beforeScreenshotKey = await this.captureCommandScreenshot(session, "before", recorderStep.step._id, command._id);
 				const commandResult = await this.executeCommand({
 					page: this.lastActivePage,
 					command,
@@ -26750,12 +27237,34 @@ var Tester = class {
 				});
 				if ((command.type === "custom" || command.type === "custom.code") && commandResult && isFailedCustomCommandResult(commandResult)) throw new Error(commandResult.error || `Custom command "${command._id}" failed.`);
 				this.obs.logger.log(`Finished executing command: ${command}`);
-				yield await this.onCommandPass(command, stepDefinitionId, session, { resolvedChosenSelectorIndex: getResolvedChosenSelectorIndex(commandResult) });
+				const afterScreenshotKey = await this.captureCommandScreenshot(session, "after", recorderStep.step._id, command._id);
+				yield await this.onCommandPass(command, stepDefinitionId, session, {
+					resolvedChosenSelectorIndex: getResolvedChosenSelectorIndex(commandResult),
+					screenshots: this.toScreenshotRefs(beforeScreenshotKey, afterScreenshotKey)
+				});
 			} catch (error) {
 				const executionError = this.toExecutionError(error);
 				let terminalExecutionError = executionError;
 				let failedRecoveryMeta;
 				if (this.isBrowserDerivedCommand(command)) {
+					if (command.type === "element.action" && this.shouldUseNewTourMaintenanceRecovery({
+						session,
+						recorderStep,
+						command,
+						commandIndex
+					})) {
+						const recoveryMeta = yield* this.recoverNewTourMaintenanceGenderCommand({
+							recorderStep,
+							command,
+							commandIndex,
+							commandContext,
+							executionError,
+							options
+						});
+						stepRecovery = recoveryMeta;
+						yield await this.onCommandPass(command, stepDefinitionId, session, { recovery: recoveryMeta });
+						continue;
+					}
 					if (this.shouldAttemptAiRecovery(session)) yield {
 						type: "recovery_status",
 						recoveryAttemptId: crypto.randomUUID(),
@@ -26878,7 +27387,10 @@ var Tester = class {
 								};
 								emittedTerminalRecoveryStatus = true;
 								this.obs.logger.log(`Recovered command ${command._id} with whole-step repair`);
-								yield await this.onCommandPass(command, stepDefinitionId, session, { recovery: recoveryMeta });
+								yield await this.onCommandPass(command, stepDefinitionId, session, {
+									recovery: recoveryMeta,
+									screenshots: this.toScreenshotRefs(beforeScreenshotKey, await this.captureCommandScreenshot(session, "after", recorderStep.step._id, command._id))
+								});
 								commandIndex = recorderStep.definition.commands.length - 1;
 								continue;
 							} catch (retryError) {
@@ -27017,7 +27529,10 @@ var Tester = class {
 								};
 								emittedTerminalRecoveryStatus = true;
 								this.obs.logger.log(`Recovered command ${command._id} with step repair`);
-								yield await this.onCommandPass(command, stepDefinitionId, session, { recovery: recoveryMeta });
+								yield await this.onCommandPass(command, stepDefinitionId, session, {
+									recovery: recoveryMeta,
+									screenshots: this.toScreenshotRefs(beforeScreenshotKey, await this.captureCommandScreenshot(session, "after", recorderStep.step._id, command._id))
+								});
 								if (decision.stepRepairPlan.type === "command-operations" || decision.stepRepairPlan.preserveSuffix) commandIndex = recorderStep.definition.commands.length - 1;
 								continue;
 							} catch (retryError) {
@@ -27091,7 +27606,8 @@ var Tester = class {
 						evidenceSignalNames: decision.evidenceSignalNames
 					};
 				}
-				yield await this.onCommandFail(command, stepDefinitionId, terminalExecutionError, session, failedRecoveryMeta);
+				const afterScreenshotKey = await this.captureCommandScreenshot(session, "after", recorderStep.step._id, command._id);
+				yield await this.onCommandFail(command, stepDefinitionId, terminalExecutionError, session, failedRecoveryMeta, this.toScreenshotRefs(beforeScreenshotKey, afterScreenshotKey));
 				throw terminalExecutionError;
 			}
 		}
@@ -27257,7 +27773,7 @@ var Tester = class {
 		if (!frameElementDescriptors || frameElementDescriptors.length === 0) return scope.mainFrame();
 		let currentFrame = scope.mainFrame();
 		for (const frameDescriptor of frameElementDescriptors) for (const selectorInfo of frameDescriptor.uniqueSelectors) {
-			const { target } = this.getLocator(currentFrame, selectorInfo);
+			const { target } = this.getLocator(currentFrame, selectorInfo, { isElementHidden: false });
 			try {
 				if (!await target.elementHandle()) throw new Error(`Could not find element for frame selector: ${JSON.stringify(selectorInfo)}`);
 				const selector = target._selector;
@@ -27269,9 +27785,14 @@ var Tester = class {
 		}
 		return currentFrame;
 	}
-	getLocator(scope, uniqueSelector) {
+	getLocator(scope, uniqueSelector, options) {
 		switch (uniqueSelector.type) {
-			case "pw.selectorString": return { target: scope.locator(uniqueSelector.selectorString + ` >> visible=true`) };
+			case "pw.selectorString": {
+				const visibleSuffix = options?.isElementHidden === true ? "" : ` >> visible=true`;
+				const finalSelector = uniqueSelector.selectorString + visibleSuffix;
+				this.obs.logger.info(`getLocator(pw.selectorString): isElementHidden=${options?.isElementHidden}, visibleAppended=${visibleSuffix !== ""}, finalSelector=${finalSelector}`);
+				return { target: scope.locator(finalSelector) };
+			}
 			case "bvt.selectorObject": throw new Error(`Selector type "bvt.selectorObject" is not yet supported in getLocator`);
 			default:
 				const _exhaustiveCheck = uniqueSelector;
@@ -27390,15 +27911,82 @@ var Tester = class {
 				else await asserter.toHaveAttribute(assertion.name, value, assertion.options);
 				break;
 			}
-			case "toHaveProperty":
-				this.obs.logger.info(`Checking property "${assertion.name}"...`);
-				if (assertion.value === void 0) await asserter.toHaveJSProperty(assertion.name, assertion.options);
-				else {
-					let value = getValueFromPrimitiveOrRegex(assertion.value);
-					this.obs.logger.info(`Expected property value: "${value}" (timeout: ${assertion.options?.timeout ?? "default"}ms)`);
-					await asserter.toHaveJSProperty(assertion.name, value, assertion.options);
+			case "toHaveProperty": {
+				const operator = assertion.operator ?? "equals";
+				this.obs.logger.info(`Checking property "${assertion.name}" [operator: ${operator}]...`);
+				switch (operator) {
+					case "equals":
+						if (assertion.value === void 0) await asserter.toHaveJSProperty(assertion.name, assertion.options);
+						else {
+							const value = getValueFromPrimitiveOrRegex(assertion.value);
+							this.obs.logger.info(`Expected: "${value}" (timeout: ${assertion.options?.timeout ?? "default"}ms)`);
+							await asserter.toHaveJSProperty(assertion.name, value, assertion.options);
+						}
+						break;
+					case "notEquals":
+						if (assertion.value !== void 0) {
+							const value = getValueFromPrimitiveOrRegex(assertion.value);
+							this.obs.logger.info(`Expected NOT: "${value}"`);
+							await expect(locator).not.toHaveJSProperty(assertion.name, value, assertion.options);
+						}
+						break;
+					case "contains":
+						if (assertion.value !== void 0) {
+							const raw = getValueFromPrimitiveOrRegex(assertion.value);
+							const stringValue = typeof raw === "string" ? raw : String(raw);
+							this.obs.logger.info(`Expected to contain: "${stringValue}"`);
+							const propName = assertion.name;
+							const isTextProp = propName === "textContent" || propName === "innerText";
+							const isHtmlAttr = [
+								"href",
+								"src",
+								"class",
+								"id",
+								"placeholder",
+								"title",
+								"alt",
+								"name",
+								"type",
+								"action",
+								"target",
+								"rel",
+								"value"
+							].includes(propName) || propName.startsWith("data-") || propName.startsWith("aria-");
+							if (isTextProp) await expect(locator).toContainText(stringValue, assertion.options);
+							else if (isHtmlAttr) {
+								const attrPattern = raw instanceof RegExp ? raw : new RegExp(stringValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+								await expect(locator).toHaveAttribute(propName, attrPattern, assertion.options);
+							} else {
+								const actual = await locator.evaluate((el, name) => String(el[name] ?? ""), propName);
+								if (!actual.includes(stringValue)) throw new Error(`Property "${propName}" expected to contain "${stringValue}", but got "${actual}"`);
+							}
+						}
+						break;
+					case "lessThan":
+						if (assertion.value !== void 0) {
+							const threshold = Number(getValueFromPrimitiveOrRegex(assertion.value));
+							const actual = Number(await locator.evaluate((el, name) => el[name], assertion.name));
+							this.obs.logger.info(`Expected "${assertion.name}" (${actual}) < ${threshold}`);
+							if (!(actual < threshold)) throw new Error(`Property "${assertion.name}" expected to be less than ${threshold}, but got ${actual}`);
+						}
+						break;
+					case "greaterThan":
+						if (assertion.value !== void 0) {
+							const threshold = Number(getValueFromPrimitiveOrRegex(assertion.value));
+							const actual = Number(await locator.evaluate((el, name) => el[name], assertion.name));
+							this.obs.logger.info(`Expected "${assertion.name}" (${actual}) > ${threshold}`);
+							if (!(actual > threshold)) throw new Error(`Property "${assertion.name}" expected to be greater than ${threshold}, but got ${actual}`);
+						}
+						break;
+					case "exists": {
+						const exists = await locator.evaluate((el, name) => el[name] !== void 0, assertion.name);
+						this.obs.logger.info(`Expected property "${assertion.name}" to exist: ${exists}`);
+						if (!exists) throw new Error(`Property "${assertion.name}" does not exist on element`);
+						break;
+					}
 				}
 				break;
+			}
 			case "toHaveValue": {
 				const value = getValueFromStringOrRegex(assertion.value);
 				await asserter.toHaveValue(value, assertion.options);
@@ -27585,7 +28173,7 @@ var Tester = class {
 					const selectorInfo = target.uniqueSelectors[chosenSelectorIndex];
 					if (!selectorInfo) throw new Error(`No selector found for target "${target.name}" at chosenSelectorIndex ${chosenSelectorIndex}. Available selectors: ${JSON.stringify(target.uniqueSelectors)}`);
 					const frame = await this.getFrame(input.page, target.frames);
-					const locator = this.getLocator(frame, selectorInfo);
+					const locator = this.getLocator(frame, selectorInfo, target);
 					try {
 						const dataWithDefaultTimeout = {
 							...data,
@@ -27606,7 +28194,7 @@ var Tester = class {
 					for (let i = 0; i < target.uniqueSelectors.length; i++) {
 						if (i === chosenSelectorIndex) continue;
 						const selectorInfo = target.uniqueSelectors[i];
-						const locator = this.getLocator(frame, selectorInfo);
+						const locator = this.getLocator(frame, selectorInfo, target);
 						try {
 							this.obs.logger.info(`Retrying action "${data.type}" using next selector: ${JSON.stringify(selectorInfo)}`);
 							const dataWithModifiedTimeout = {
@@ -27637,7 +28225,7 @@ var Tester = class {
 					const chosenSelectorIndex = target.chosenSelectorIndex ?? 0;
 					const selectorInfo = target.uniqueSelectors[chosenSelectorIndex];
 					const frame = await this.getFrame(input.page, target.frames);
-					const locator = this.getLocator(frame, selectorInfo);
+					const locator = this.getLocator(frame, selectorInfo, target);
 					try {
 						this.obs.logger.info(`Executing assertion "${data.type}" using selector: ${JSON.stringify(selectorInfo)}`);
 						const dataWithDefaultTimeout = {
@@ -27657,7 +28245,7 @@ var Tester = class {
 					for (let i = 0; i < target.uniqueSelectors.length; i++) {
 						if (i === chosenSelectorIndex) continue;
 						const selectorInfo = target.uniqueSelectors[i];
-						const locator = this.getLocator(frame, selectorInfo);
+						const locator = this.getLocator(frame, selectorInfo, target);
 						const dataWithModifiedTimeout = {
 							...data,
 							options: {
@@ -27690,7 +28278,7 @@ var Tester = class {
 					const selectorInfo = target.uniqueSelectors[chosenSelectorIndex];
 					if (!selectorInfo) throw new Error(`No selector found for target "${target.name}" at chosenSelectorIndex ${chosenSelectorIndex}. Available selectors: ${JSON.stringify(target.uniqueSelectors)}`);
 					const frame = await this.getFrame(input.page, target.frames);
-					const locator = this.getLocator(frame, selectorInfo);
+					const locator = this.getLocator(frame, selectorInfo, target);
 					try {
 						this.obs.logger.info(`Executing extraction "${extract.type}" using selector: ${JSON.stringify(selectorInfo)}`);
 						await this.executeElementExtraction(locator.target, extract, storageDetails);
@@ -27703,7 +28291,7 @@ var Tester = class {
 					for (let i = 0; i < target.uniqueSelectors.length; i++) {
 						if (i === chosenSelectorIndex) continue;
 						const fallbackSelectorInfo = target.uniqueSelectors[i];
-						const fallbackLocator = this.getLocator(frame, fallbackSelectorInfo);
+						const fallbackLocator = this.getLocator(frame, fallbackSelectorInfo, target);
 						try {
 							this.obs.logger.info(`Retrying extraction "${extract.type}" using next selector: ${JSON.stringify(fallbackSelectorInfo)}`);
 							await this.executeElementExtraction(fallbackLocator.target, extract, storageDetails);
@@ -27919,14 +28507,17 @@ var Tester = class {
 			for (const recorderStep of input.recorderSteps) yield* this.executeStep(recorderStep, input, options);
 			await options.onFinish?.();
 			this.obs.logger.log("Finished executing all steps");
+			let screenshotsAvailable = false;
 			if (this.isRunSession(session)) {
 				this.obs.logger.log(`Stopping Playwright tracing for reportId: ${session.reportId}, testCaseId: ${session.testCaseId}...`);
 				await this.stopTracingAndHandleTrace(session);
+				screenshotsAvailable = await this.uploadScreenshots(session);
 			}
 			this.obs.logger.log(`Test case execution completed successfully with session: ${JSON.stringify(session)}`);
 			return {
 				type: "execution_completed",
-				result: { type: "success" }
+				result: { type: "success" },
+				...screenshotsAvailable ? { screenshotsAvailable: true } : {}
 			};
 		} catch (error) {
 			const executionError = this.toExecutionError(error);
@@ -27936,13 +28527,16 @@ var Tester = class {
 				session: this.summarizeSessionForExecutionLog(session),
 				error: this.summarizeErrorForExecutionLog(executionError)
 			});
+			let screenshotsAvailable = false;
 			if (this.isRunSession(session)) {
 				this.obs.logger.log(`Stopping Playwright tracing for reportId: ${session.reportId}, testCaseId: ${session.testCaseId}...`);
 				await this.stopTracingAndHandleTrace(session);
+				screenshotsAvailable = await this.uploadScreenshots(session);
 			}
 			return {
 				type: "execution_completed",
-				result: this.toFailureResult(executionError)
+				result: this.toFailureResult(executionError),
+				...screenshotsAvailable ? { screenshotsAvailable: true } : {}
 			};
 		} finally {
 			this.obs.metrics.count("bvt_agent.test_case.execute.completed.total", 1, {