From 230f86240f04a79e96c1ac64ea3d4cbd5db76af9 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 06:20:26 +0800 Subject: [PATCH] docs(browser): describe exact role locator names (#12099) * docs(browser): describe exact role locator names * style(browser): format role locator schema metadata --- docs/guides/web/browser-scenario-contract.md | 4 ++++ src/contracts/browserScenarioToolContracts.ts | 2 +- src/domain/browserScenarioValues.ts | 7 ++++++- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/guides/web/browser-scenario-contract.md b/docs/guides/web/browser-scenario-contract.md index 183402cb50..5e1eb39ec0 100644 --- a/docs/guides/web/browser-scenario-contract.md +++ b/docs/guides/web/browser-scenario-contract.md @@ -78,6 +78,10 @@ scenario whose declared variables are unset still validates; the missing-value failure belongs to capture. A schema-valid scenario does not prove that the executable or target is available on the host. +For a locator with `kind: "role"`, set `name` to the element's exact full +accessible name. Use the name shown in accessibility evidence, which can include +text beyond the visible label. A partial name does not match. + ## Minimal launch example Save this as `browser-scenario.json`, replacing the executable path with an diff --git a/src/contracts/browserScenarioToolContracts.ts b/src/contracts/browserScenarioToolContracts.ts index f7c56cbdd9..9cf945d9a2 100644 --- a/src/contracts/browserScenarioToolContracts.ts +++ b/src/contracts/browserScenarioToolContracts.ts @@ -44,7 +44,7 @@ export const BROWSER_SCENARIO_TOOL_CONTRACTS = [ }), ), description: - 'Drive a browser scenario when passive observation cannot exercise the app. Launch the selected executable or connect to a loopback CDP target; actions can change application state and make network requests. Supply browser, start_url and actions, e.g. {browser:{mode:"launch",executable_path:"/opt/chromium/chrome"},start_url:{url:"https://app.example.test/"},actions:[{step_id:"settle",action:"wait_for_timeout",duration_ms:250}]}. Empty storage and a URL-only final capture are defaults. Request actions use page fetch on the start origin; capture.network independently opts into request_body, response_body and header_values. Credentials and declared secrets are redacted. capture.limits controls retained event/content budgets; omissions identify affected events/transactions. Actions wait for completion or cancellation; per-action timeout_ms bounds a step. Default complete delivery returns Evidence inline. detail summary retains it and returns step outcomes, final/first-unsuccessful accessibility, and counts; inspect_analysis_view kind browser-scenario pages steps, events, transactions and UTF-16 text. Use inspect_web_page for observation without actions.', + 'Drive a browser scenario when passive observation cannot exercise the app. Launch the selected executable or connect to a loopback CDP target; actions can change application state and make network requests. Supply browser, start_url and actions, e.g. {browser:{mode:"launch",executable_path:"/opt/chromium/chrome"},start_url:{url:"https://app.example.test/"},actions:[{step_id:"settle",action:"wait_for_timeout",duration_ms:250}]}. Empty storage and a URL-only final capture are defaults. Request actions use page fetch on the start origin; capture.network independently opts into request_body, response_body and header_values. Credentials and declared secrets are redacted. capture.limits controls retained event/content budgets; omissions identify affected events/transactions. Role locators match the exact full accessible name. Actions wait for completion or cancellation; per-action timeout_ms bounds a step. Default complete delivery returns Evidence inline. detail summary retains it and returns step outcomes, final/first-unsuccessful accessibility, and counts; inspect_analysis_view kind browser-scenario pages steps, events, transactions and UTF-16 text. Use inspect_web_page for observation without actions.', kind: "browser-provider", inputSchema: browserScenarioInputSchema.extend({ detail: analysisDetailSchema, diff --git a/src/domain/browserScenarioValues.ts b/src/domain/browserScenarioValues.ts index e60745c4e4..83b823db77 100644 --- a/src/domain/browserScenarioValues.ts +++ b/src/domain/browserScenarioValues.ts @@ -342,7 +342,12 @@ const locatorSchema = z.discriminatedUnion("kind", [ "tab", "textbox", ]), - name: z.string().min(1), + name: z + .string() + .min(1) + .describe( + "The exact full accessible name of the element with this role.", + ), }), z.strictObject({ kind: z.literal("css"),