chore: better error message for bad apiEndpoint and non-json cache (#38845)

Author: dgozman

packages/playwright-core/src/server/agent/pageAgent.ts

@@ -92,6 +92,8 @@ async function runLoop(progress: Progress, context: Context, toolDefinitions: To
     throw new Error(`This action requires the API and API key to be set on the page agent. Did you mean to --run-agents=missing?`);
   if (!context.agentParams.apiKey)
     throw new Error(`This action requires API key to be set on the page agent.`);
+  if (context.agentParams.apiEndpoint && !URL.canParse(context.agentParams.apiEndpoint))
+    throw new Error(`Agent API endpoint "${context.agentParams.apiEndpoint}" is not a valid URL.`);
 
   const snapshot = await context.takeSnapshot(progress);
   const { tools, callTool, reportedResult, refusedToPerformReason } = toolsForLoop(progress, context, toolDefinitions, { resultSchema, refuseToPerform: 'allow' });
@@ -204,7 +206,13 @@ const allCaches = new Map<string, Cache>();
 async function cachedActions(cacheFile: string): Promise<Cache> {
   let cache = allCaches.get(cacheFile);
   if (!cache) {
-    const json = await fs.promises.readFile(cacheFile, 'utf-8').then(text => JSON.parse(text)).catch(() => ({}));
+    const content = await fs.promises.readFile(cacheFile, 'utf-8').catch(() => '');
+    let json: any;
+    try {
+      json = JSON.parse(content.trim() || '{}');
+    } catch (error) {
+      throw new Error(`Failed to parse cache file ${cacheFile}:\n${error.message}`);
+    }
     const parsed = actions.cachedActionsSchema.safeParse(json);
     if (parsed.error)
       throw new Error(`Failed to parse cache file ${cacheFile}:\n${zod.prettifyError(parsed.error)}`);

tests/library/__llm_cache__/library-agent-perform-empty-cache-file-works.json

@@ -0,0 +1,30 @@
+{
+  "29a2028099170f3ab333459d1f9c78de2767e7b3": {
+    "result": {
+      "role": "assistant",
+      "content": [
+        {
+          "type": "text",
+          "text": "I'll click the Test button for you."
+        },
+        {
+          "type": "tool_call",
+          "name": "browser_click",
+          "arguments": {
+            "element": "Test button",
+            "ref": "e2",
+            "_is_done": true
+          },
+          "id": "toolu_013jBJjsaeAjvjyjfWLYNFGb"
+        }
+      ],
+      "stopReason": {
+        "code": "ok"
+      }
+    },
+    "usage": {
+      "input": 3043,
+      "output": 101
+    }
+  }
+}

tests/library/agent-helpers.ts

@@ -42,7 +42,7 @@ export async function generateAgent(context: BrowserContext, options: AgentOptio
     provider: {
       api: 'anthropic' as const,
       apiKey: process.env.AZURE_SONNET_API_KEY ?? 'dummy',
-      apiEndpoint: process.env.AZURE_SONNET_ENDPOINT ?? 'dummy',
+      apiEndpoint: process.env.AZURE_SONNET_ENDPOINT,
       model: 'claude-sonnet-4-5',
       ...{ _apiCacheFile: apiCacheFile }
     },

tests/library/agent-perform.spec.ts

@@ -16,9 +16,10 @@
 
 import { z as zod3 } from 'zod/v3';
 import * as zod4 from 'zod';
+import fs from 'fs';
 
 import { browserTest as test, expect } from '../config/browserTest';
-import { run, generateAgent, cacheObject, runAgent, setCacheObject } from './agent-helpers';
+import { run, generateAgent, cacheObject, runAgent, setCacheObject, cacheFile } from './agent-helpers';
 
 // LOWIRE_NO_CACHE=1 to generate api caches
 // LOWIRE_FORCE_CACHE=1 to force api caches
@@ -191,6 +192,33 @@ Failed to parse cache file ${test.info().outputPath('agent-cache.json')}:
     `.trim());
 });
 
+test('non-json cache file throws a nice error', async ({ context }) => {
+  await fs.promises.writeFile(cacheFile(), 'bogus', 'utf8');
+  const { agent } = await runAgent(context);
+  const error = await agent.perform('click the Test button').catch(e => e);
+  expect(error.message).toContain(`Failed to parse cache file ${test.info().outputPath('agent-cache.json')}:`);
+  expect(error.message.toLowerCase()).toContain(`valid json`);
+});
+
+test('empty cache file works', async ({ context }) => {
+  await fs.promises.writeFile(cacheFile(), '', 'utf8');
+  const { page, agent } = await generateAgent(context);
+  await page.setContent(`<button>Test</button>`);
+  await agent.perform('click the Test button');
+});
+
+test('missing apiKey throws a nice error', async ({ page }) => {
+  const agent = await page.agent({ provider: { api: 'anthropic', model: 'some model' } as any });
+  const error = await agent.perform('click the Test button').catch(e => e);
+  expect(error.message).toContain(`This action requires API key to be set on the page agent`);
+});
+
+test('malformed apiEndpoint throws a nice error', async ({ page }) => {
+  const agent = await page.agent({ provider: { api: 'anthropic', model: 'some model', apiKey: 'some key', apiEndpoint: 'foobar' } });
+  const error = await agent.perform('click the Test button').catch(e => e);
+  expect(error.message).toContain(`Agent API endpoint "foobar" is not a valid URL`);
+});
+
 test('perform reports error', async ({ context }) => {
   const { page, agent } = await generateAgent(context);
   await page.setContent(`