docs(browser): describe exact role locator names (#12099)

* docs(browser): describe exact role locator names

* style(browser): format role locator schema metadata
This commit is contained in:
morluto authored and GitHub committed 2026-11-18 17:20:26 -05:00
1 parent caab34d0de
commit 230f86240f
3 files changed
+11 -2

No files matched your search

@@ -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
@@ -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,
+6 -1
View File
@@ -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"),