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.tsindex 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.tsindex 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.tsindex 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<Prif (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.tsindex 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.tsindex 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.`;}}