@dev-blinq/bvt-playwright-js 1.0.0-dev.3 → 1.0.0-dev.4

package/index.d.mts

@@ -13,6 +13,85 @@ declare const apiResponseSnapshotSchema: z.ZodObject<{
 	bodyJson: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 type ApiResponseSnapshot = z.infer<typeof apiResponseSnapshotSchema>;
+declare const apiRequestSchema: z.ZodObject<{
+	method: z.ZodEnum<{
+		GET: "GET";
+		POST: "POST";
+		PUT: "PUT";
+		PATCH: "PATCH";
+		DELETE: "DELETE";
+	}>;
+	url: z.ZodString;
+	headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+	body: z.ZodOptional<z.ZodString>;
+	saveAs: z.ZodOptional<z.ZodString>;
+	capturedResponse: z.ZodOptional<z.ZodObject<{
+		status: z.ZodNumber;
+		statusText: z.ZodString;
+		timeMs: z.ZodNumber;
+		sizeBytes: z.ZodNumber;
+		headers: z.ZodRecord<z.ZodString, z.ZodString>;
+		bodyText: z.ZodString;
+		bodyJson: z.ZodOptional<z.ZodUnknown>;
+	}, z.core.$strict>>;
+	options: z.ZodOptional<z.ZodObject<{
+		timeout: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+	}, z.core.$strict>>;
+}, z.core.$strict>;
+type ApiRequest = z.infer<typeof apiRequestSchema>;
+declare const apiResponseAssertionCommandData: z.ZodDiscriminatedUnion<[
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		target: z.ZodLiteral<"status">;
+		expected: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		target: z.ZodLiteral<"responseTime">;
+		expected: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		expected: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+		target: z.ZodLiteral<"header">;
+		path: z.ZodString;
+	}, z.core.$strict>,
+	z.ZodObject<{
+		operator: z.ZodEnum<{
+			equals: "equals";
+			notEquals: "notEquals";
+			contains: "contains";
+			lessThan: "lessThan";
+			greaterThan: "greaterThan";
+			exists: "exists";
+		}>;
+		expected: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+		target: z.ZodLiteral<"bodyField">;
+		path: z.ZodString;
+	}, z.core.$strict>
+], "target">;
+type ApiResponseAssertionCommandData = z.infer<typeof apiResponseAssertionCommandData>;
 declare const elementActionSchema: z.ZodDiscriminatedUnion<[
 	z.ZodObject<{
 		type: z.ZodLiteral<"click">;
@@ -1797,9 +1876,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -2557,9 +2636,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -3201,9 +3280,9 @@ declare const CommandSchema: z.ZodDiscriminatedUnion<[
 				], "type">;
 				score: z.ZodNumber;
 				source: z.ZodEnum<{
+					role: "role";
 					xpath: "xpath";
 					testId: "testId";
-					role: "role";
 					accessibleName: "accessibleName";
 					visibleText: "visibleText";
 					stableAttribute: "stableAttribute";
@@ -4796,9 +4875,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -5556,9 +5635,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -6200,9 +6279,9 @@ declare const StepDefinitionSchema: z.ZodObject<{
 					], "type">;
 					score: z.ZodNumber;
 					source: z.ZodEnum<{
+						role: "role";
 						xpath: "xpath";
 						testId: "testId";
-						role: "role";
 						accessibleName: "accessibleName";
 						visibleText: "visibleText";
 						stableAttribute: "stableAttribute";
@@ -6799,9 +6878,9 @@ declare const ReplayLocatorCandidateSchema: z.ZodObject<{
 	], "type">;
 	score: z.ZodNumber;
 	source: z.ZodEnum<{
+		role: "role";
 		xpath: "xpath";
 		testId: "testId";
-		role: "role";
 		accessibleName: "accessibleName";
 		visibleText: "visibleText";
 		stableAttribute: "stableAttribute";
@@ -7081,9 +7160,9 @@ declare const StepReplayTelemetrySchema: z.ZodObject<{
 		], "type">;
 		score: z.ZodNumber;
 		source: z.ZodEnum<{
+			role: "role";
 			xpath: "xpath";
 			testId: "testId";
-			role: "role";
 			accessibleName: "accessibleName";
 			visibleText: "visibleText";
 			stableAttribute: "stableAttribute";
@@ -7285,8 +7364,8 @@ declare const RecoveryDecisionSchema: z.ZodDiscriminatedUnion<[
 			}, z.core.$strip>
 		], "type">;
 		repairContext: z.ZodEnum<{
-			"local-run": "local-run";
 			"recorder-replay": "recorder-replay";
+			"local-run": "local-run";
 			"execution-planner": "execution-planner";
 		}>;
 		rcaLabel: z.ZodOptional<z.ZodString>;
@@ -7341,8 +7420,8 @@ type ExecutionStartedEventData = {
 	type: "execution_started";
 };
 declare const ScopeTypeSchema: z.ZodEnum<{
-	runtime: "runtime";
 	environment: "environment";
+	runtime: "runtime";
 	global: "global";
 	feature: "feature";
 	scenario: "scenario";
@@ -7376,8 +7455,8 @@ declare const TestDataEntrySchema: z.ZodObject<{
 	}>;
 	scope: z.ZodObject<{
 		type: z.ZodEnum<{
-			runtime: "runtime";
 			environment: "environment";
+			runtime: "runtime";
 			global: "global";
 			feature: "feature";
 			scenario: "scenario";
@@ -7410,8 +7489,8 @@ declare const BrowserObserverStateKSchema: z.ZodUnion<readonly [
 		input: "input";
 		text: "text";
 		context: "context";
-		hover: "hover";
 		ai: "ai";
+		hover: "hover";
 		none: "none";
 		snapshot: "snapshot";
 		element: "element";
@@ -7766,9 +7845,9 @@ declare const PickedElementSchema: z.ZodObject<{
 		], "type">;
 		score: z.ZodNumber;
 		source: z.ZodEnum<{
+			role: "role";
 			xpath: "xpath";
 			testId: "testId";
-			role: "role";
 			accessibleName: "accessibleName";
 			visibleText: "visibleText";
 			stableAttribute: "stableAttribute";
@@ -7942,7 +8021,7 @@ declare class DownloadStore {
 	cancelAll(): void;
 }
 type CustomCodeAllowedHost = {
-	readonly protocol: "http:" | "https:";
+	readonly protocol: "http:" | "https:" | "pg:";
 	readonly hostname: string;
 };
 type CustomCodePolicy = {
@@ -7957,6 +8036,7 @@ type CustomCodePolicy = {
 	readonly network: {
 		readonly allowedHosts: readonly CustomCodeAllowedHost[];
 		readonly blockPrivateIpRanges: boolean;
+		readonly requirePgTls: boolean;
 	};
 	readonly filesystem: {
 		readonly root: string;
@@ -9361,6 +9441,67 @@ export declare function toMatcherValue(value: MatcherValueInput): string | numbe
 export declare function toMatcherValue(value: undefined): undefined;
 export declare function toMatcherValue(value: MatcherValueInput | undefined): string | number | boolean | RegExp | undefined;
 type GeneratedCommand = Command;
+/**
+ * Stateful API helper for generated `api.action` / `api.assertion` steps.
+ * Mirrors the Tester's runtime: a request stores its response as `lastResponse`
+ * (and writes `saveAs` to runtime test data), and an assertion runs against
+ * that stored response. The shared state lives here because the request and
+ * assertion are emitted as separate `test.step` blocks with no shared scope.
+ */
+export type BlinqApi = {
+	/** Run the request, store it as `lastResponse`, and persist `saveAs` if set. */
+	request(request: ApiRequest): Promise<ApiResponseSnapshot>;
+	/** Assert against `lastResponse`; throws if no request has run yet. */
+	assert(assertion: ApiResponseAssertionCommandData): Promise<void>;
+	readonly lastResponse: ApiResponseSnapshot | undefined;
+};
+/**
+ * The `context` object AI-chat (`custom`) command code receives. Mirrors the
+ * recorder sandbox's `context`: the resolution-scope fields plus a `testData`
+ * accessor (which is the runner's `TestDataApi`, exposing
+ * `set`/`get`/`setRuntime`/`getRuntime`).
+ */
+export type AiChatContext = {
+	readonly testData: TestDataApi;
+	readonly projectId?: string;
+	readonly environmentId?: string;
+	readonly featureId?: string;
+	readonly scenarioId?: string;
+	readonly executionId?: string;
+};
+/**
+ * The globals AI-chat custom code expects beyond `page` / `expect` / `console`.
+ * Generated specs declare `context`, `checkpoint`, `onCommandStart`, and
+ * `onCommandPass` above the inlined code, sourced from the bvt fixture.
+ *
+ * Recovery helpers (`helpers.getPreferredInteractiveTarget`, etc.) are
+ * intentionally NOT provided — they depend on bvt-agent's runtime recovery and
+ * have no standalone equivalent.
+ */
+export type AiChatGlobals = {
+	readonly context: AiChatContext;
+	checkpoint(label: string, data?: unknown): void;
+	onCommandStart(label: string): Promise<void>;
+	onCommandPass(opts?: {
+		delayMs?: number;
+	}): Promise<void>;
+};
+/**
+ * Build the AI-chat command globals. Mirrors the recorder sandbox:
+ * `onCommandStart` waits the watch-delay then records the command boundary,
+ * `onCommandPass` waits the (overridable) watch-delay, and `checkpoint`
+ * records a labelled marker. In a standalone Playwright run the sandbox's
+ * live-timeline bridge is replaced by Playwright test annotations (via the
+ * injected `annotate` callback).
+ */
+export declare function createAiChatGlobals(input: {
+	testDataApi: TestDataApi;
+	parameters: PlaywrightRunnerParameters;
+	annotate: (annotation: {
+		type: string;
+		description: string;
+	}) => void;
+}): AiChatGlobals;
 export declare class TempFileTestDataProvider implements ITestDataProvider {
 	readonly filePath: string;
 	readonly seedFilePath?: string | undefined;
@@ -9392,6 +9533,7 @@ export declare class PlaywrightRunner {
 	private readonly scopeManager?;
 	private readonly preprocessors;
 	private resolutionContext;
+	private apiRuntime?;
 	constructor(options?: PlaywrightRunnerOptions, dependencies?: PlaywrightRunnerDependencies);
 	private applyResolutionContext;
 	/**
@@ -9400,6 +9542,13 @@ export declare class PlaywrightRunner {
 	 */
 	attach(page: Page): void;
 	detach(): void;
+	/**
+	 * Stateful API helper for `api.action` / `api.assertion` steps. Lazily built
+	 * and held for the runner's lifetime so a request and its following assertion
+	 * share `lastResponse`. Throws if no test-data provider/context is available
+	 * (the `saveAs` path needs it).
+	 */
+	get api(): BlinqApi;
 	executeCommand(command: GeneratedCommand, parameters?: Record<string, string>): Promise<unknown>;
 	/**
 	 * Run the preprocessor pipeline (step parameters, data-resolver tokens,
@@ -9472,6 +9621,25 @@ export type BlinqTestRuntime = {
 	 * `{{key}}` in later steps.
 	 */
 	readonly testDataApi: TestDataApi;
+	/**
+	 * Stateful API helper. `api.action` steps call `bvt.api.request(...)` and
+	 * `api.assertion` steps call `bvt.api.assert(...)`; the request's response is
+	 * shared with the following assertion via `bvt.api.lastResponse`.
+	 */
+	readonly api: BlinqApi;
+	/**
+	 * The `context` object AI-chat (`custom`) command code receives; generated
+	 * specs declare `const context = bvt.aiChatContext` above the inlined code.
+	 */
+	readonly aiChatContext: AiChatContext;
+	/** AI-chat `checkpoint(label, data?)` global — records a Playwright annotation. */
+	checkpoint(label: string, data?: unknown): void;
+	/** AI-chat `onCommandStart(label)` global — watch-delay then a boundary annotation. */
+	onCommandStart(label: string): Promise<void>;
+	/** AI-chat `onCommandPass(opts?)` global — watch-delay (overridable via `delayMs`). */
+	onCommandPass(opts?: {
+		delayMs?: number;
+	}): Promise<void>;
 	executeCommand(command: GeneratedCommand, parameters?: Record<string, string>): Promise<unknown>;
 	resolveCommand(command: unknown, parameters?: Record<string, string>): Promise<Command>;
 	find(command: Command): Promise<Locator | Page | FrameLocator | null>;