Skip to content
TypeScript

fix(preview): explain invalid URLs and locators (#23396)

Julius Marminge6e58094f740e
diff --git a/packages/contracts/src/preview.test.ts b/packages/contracts/src/preview.test.ts
index 6618646f1f4..7defee76aac 100644
--- a/packages/contracts/src/preview.test.ts
+++ b/packages/contracts/src/preview.test.ts
@@ -1,7 +1,13 @@
import { Schema } from "effect";
import { describe, expect, it } from "vite-plus/test";
-import { PreviewAutomationHost, PreviewAutomationStatus } from "./previewAutomation.ts";
+import { EnvironmentId, ThreadId } from "./baseSchemas.ts";
+import {
+ PreviewAutomationHost,
+ PreviewAutomationInvalidSelectorError,
+ PreviewAutomationStatus,
+} from "./previewAutomation.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
const decodeAutomationHost = Schema.decodeUnknownSync(PreviewAutomationHost);
const decodeAutomationStatus = Schema.decodeUnknownSync(PreviewAutomationStatus);
@@ -42,3 +48,38 @@ describe("PreviewAutomationStatus", () => {
).toEqual({ width: 412, height: 915 });
});
});
+
+describe("PreviewAutomationInvalidSelectorError", () => {
+ const invalidSelector = (selectorKind: "locator" | "selector") =>
+ new PreviewAutomationInvalidSelectorError({
+ operation: "click",
+ environmentId: EnvironmentId.make("environment-1"),
+ threadId: ThreadId.make("thread-1"),
+ providerSessionId: "session-1",
+ providerInstanceId: ProviderInstanceId.make("claude"),
+ clientId: "desktop",
+ connectionId: "connection-1",
+ requestId: "request-1",
+ timeoutMs: 15_000,
+ remoteTag: "Error",
+ remoteMessageLength: 0,
+ cause: null,
+ selectorKind,
+ selectorLength: 42,
+ });
+
+ it("tells agents which locator forms are accepted and where CSS goes", () => {
+ const { message } = invalidSelector("locator");
+ expect(message).toContain("aria-ref=");
+ expect(message).toMatch(/role/);
+ expect(message).toMatch(/text/);
+ expect(message).toMatch(/CSS[^.]*\bselector\b/);
+ });
+
+ it("points an invalid CSS selector at the locator alternative", () => {
+ const { message } = invalidSelector("selector");
+ expect(message).toMatch(/CSS/);
+ expect(message).toMatch(/\blocator\b/);
+ expect(message).toContain("aria-ref=");
+ });
+});
diff --git a/packages/contracts/src/preview.ts b/packages/contracts/src/preview.ts
index cbf8ac60b26..1790a4797db 100644
--- a/packages/contracts/src/preview.ts
+++ b/packages/contracts/src/preview.ts
@@ -376,7 +376,7 @@ export class PreviewInvalidUrlError extends Schema.TaggedError<PreviewInvalidUrl
) {
override get message() {
const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`;
- return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}).`;
+ return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`;
}
}
diff --git a/packages/contracts/src/previewAutomation.ts b/packages/contracts/src/previewAutomation.ts
index 5862b643e00..2ba62cd9ae2 100644
--- a/packages/contracts/src/previewAutomation.ts
+++ b/packages/contracts/src/previewAutomation.ts
@@ -840,7 +840,11 @@ export class PreviewAutomationInvalidSelectorError extends Schema.TaggedError<Pr
if (this.staleRef)
return "This element ref is stale. Navigation, dialogs, and new snapshots replace refs; take a fresh snapshot and use its refs.";
if (this.selectorKind !== undefined && this.selectorLength !== undefined) {
- return `Preview automation ${this.operation} received an invalid ${this.selectorKind} (${this.selectorLength} characters).`;
+ const guidance =
+ this.selectorKind === "locator"
+ ? "Use aria-ref=<ref> from the latest snapshot or a Playwright role/text selector; put CSS in selector."
+ : "selector takes CSS; use locator for aria-ref=<ref>, role, or text targets.";
+ return `Preview automation ${this.operation} received an invalid ${this.selectorKind} (${this.selectorLength} characters). ${guidance}`;
}
return `Preview automation ${this.operation} received an invalid selector.`;
}
diff --git a/packages/shared/src/preview.test.ts b/packages/shared/src/preview.test.ts
index 23f4b4390c7..231b141bf03 100644
--- a/packages/shared/src/preview.test.ts
+++ b/packages/shared/src/preview.test.ts
@@ -149,6 +149,14 @@ describe("resolveSearchUrlTemplate", () => {
});
describe("normalizePreviewUrl", () => {
+ it("tells agents how to open a blank tab and which URLs are accepted", () => {
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(
+ /preview_open, omit url when creating a new tab[^.]*blank tab/i,
+ );
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(/http\(s\)/i);
+ expect(() => normalizePreviewUrl("about:blank")).toThrow(/schemeless host/i);
+ });
+
it("rejects unparseable input without retaining credentials or tokens", () => {
const rawUrl = "https://user:[email protected]:bad/path?access_token=secret#fragment";
try {
diff --git a/packages/shared/src/preview.ts b/packages/shared/src/preview.ts
index 30a6bdc8b1c..f279c07f738 100644
--- a/packages/shared/src/preview.ts
+++ b/packages/shared/src/preview.ts
@@ -66,7 +66,7 @@ export class PreviewUrlNormalizationError extends Schema.TaggedError<PreviewUrlN
) {
override get message(): string {
const protocol = this.protocol === undefined ? "" : `: ${this.protocol}`;
- return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}).`;
+ return `Invalid preview URL (${this.reason}${protocol}; input length ${this.inputLength}). Use an http(s) URL or a schemeless host such as localhost:5173. With preview_open, omit url when creating a new tab to open a blank tab.`;
}
}