From 2865a250db6bfc8bbacc49b05a15d861c6b20ee4 Mon Sep 17 00:00:00 2001 From: Chromie Date: Wed, 21 Jan 2026 15:13:27 -0800 Subject: [PATCH 1/3] [docs]: add docs for `page.snapshot()` (#1579) # why New public method `page.snapshot()` # what changed Add documentation for the new page.snapshot() method in the v3 reference docs: - Method signature and description - Example output showing the formatted accessibility tree - Usage example with formattedTree, xpathMap, and urlMap - SnapshotResult type definition with field descriptions - Code example in the tabs section # test plan --- ## Summary by cubic Documented the new page.snapshot() API in the v3 reference. Shows how to capture the accessibility tree and get XPath/URL mappings for debugging and automation. - **New Features** - Added method signature and return type. - Included example output and usage with formattedTree, xpathMap, and urlMap. - Defined SnapshotResult and added a tabbed code sample. Written for commit 39e0d292c871f4cfc580ef567b11487158856558. Summary will update on new commits. Co-authored-by: Chromie Bot Co-authored-by: Claude Opus 4.5 --- packages/docs/v3/references/page.mdx | 83 ++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index 856360728..1d24f3e78 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -514,6 +514,50 @@ await page.screenshot(options?: ScreenshotOptions): Promise **Returns:** A `Promise` containing the screenshot image data. +## Page Snapshot + +### snapshot() + +Capture a structured accessibility tree snapshot of the page. Returns a formatted text representation of the page's accessibility tree along with XPath and URL mappings for each element. + +```typescript +await page.snapshot(): Promise +``` + +**Returns:** A `Promise` containing the page snapshot data. + +The snapshot provides a hierarchical view of the page's accessibility tree, where each element is represented with: +- A unique encoded ID in brackets (e.g., `[0-1]`) +- The element's accessibility role (e.g., `RootWebArea`, `heading`, `link`, `button`) +- The element's accessible name, if available + +**Example output:** + +```txt +[0-1] RootWebArea: Example Domain + [0-3] heading: Example Domain + [0-5] paragraph: This domain is for use in illustrative examples in documents. + [0-8] link: More information... +``` + +**Example usage:** + +```typescript +const page = stagehand.context.pages()[0]; +await page.goto("https://example.com"); + +const { formattedTree, xpathMap, urlMap } = await page.snapshot(); + +// Print the accessibility tree +console.log(formattedTree); + +// Look up an element's XPath by its encoded ID +console.log(xpathMap["0-8"]); // e.g., "/html/body/div/p[2]/a" + +// Look up a link's URL by its encoded ID +console.log(urlMap["0-8"]); // e.g., "https://www.iana.org/domains/example" +``` + ## Viewport ### setViewportSize() @@ -759,6 +803,31 @@ await page.setViewportSize(375, 667, { const screenshot = await page.screenshot(); ``` + + + +```typescript +// Capture the page's accessibility tree snapshot +const { formattedTree, xpathMap, urlMap } = await page.snapshot(); + +// The formattedTree shows the page structure: +// [0-1] RootWebArea: Example Domain +// [0-3] heading: Example Domain +// [0-8] link: More information... + +console.log(formattedTree); + +// Use xpathMap to get the XPath selector for any element by ID +const linkXpath = xpathMap["0-8"]; +console.log("Link XPath:", linkXpath); // "/html/body/div/p[2]/a" + +// Use urlMap to get URLs associated with link elements +const linkUrl = urlMap["0-8"]; +console.log("Link URL:", linkUrl); // "https://www.iana.org/domains/example" + +// Useful for debugging, logging page state, or building custom automation +``` + @@ -818,6 +887,20 @@ interface ScreenshotOptions { Matches Playwright's screenshot signature with sensible defaults to control how a capture is produced. +### SnapshotResult + +```typescript +type SnapshotResult = { + formattedTree: string; + xpathMap: Record; + urlMap: Record; +}; +``` + +- **`formattedTree`** - A formatted string representation of the page's accessibility tree with encoded IDs, roles, and names +- **`xpathMap`** - A mapping from encoded element IDs to their absolute XPath selectors +- **`urlMap`** - A mapping from encoded element IDs to their associated URLs (for links and other navigable elements) + ## Error Handling Page methods may throw the following errors: From d159ce9e8d952cd6dcafe9e1cb6528a269cc4dd5 Mon Sep 17 00:00:00 2001 From: Chromie Date: Fri, 23 Jan 2026 09:01:47 -0800 Subject: [PATCH 2/3] docs: add PageSnapshotOptions to page.snapshot() reference (#1591) Update snapshot() method documentation to include the new optional PageSnapshotOptions parameter with includeIframes option. Changes: - Update method signature to show optional options parameter - Add ParamField for includeIframes option (defaults to true) - Add PageSnapshotOptions type definition in Types section - Add example showing iframe exclusion in code examples # why # what changed # test plan --- ## Summary by cubic Update page.snapshot() docs to show the new optional PageSnapshotOptions, including the includeIframes flag (default true) to control iframe content. Adds the options parameter in the signature, documents includeIframes, defines PageSnapshotOptions in Types, and includes an example excluding iframe content. Written for commit 3bffc938ccada9b809ea90e1fdc641e177140dff. Summary will update on new commits. --------- Co-authored-by: Chromie Bot Co-authored-by: Claude Opus 4.5 --- packages/docs/v3/references/page.mdx | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index 1d24f3e78..5b49ddb22 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -521,9 +521,21 @@ await page.screenshot(options?: ScreenshotOptions): Promise Capture a structured accessibility tree snapshot of the page. Returns a formatted text representation of the page's accessibility tree along with XPath and URL mappings for each element. ```typescript -await page.snapshot(): Promise +await page.snapshot(options?: PageSnapshotOptions): Promise ``` + + Optional configuration for the snapshot. + + + + Whether to include iframe content in the snapshot. + + **Default:** `true` + + + + **Returns:** A `Promise` containing the page snapshot data. The snapshot provides a hierarchical view of the page's accessibility tree, where each element is represented with: @@ -825,7 +837,8 @@ console.log("Link XPath:", linkXpath); // "/html/body/div/p[2]/a" const linkUrl = urlMap["0-8"]; console.log("Link URL:", linkUrl); // "https://www.iana.org/domains/example" -// Useful for debugging, logging page state, or building custom automation +// Exclude iframe content from the snapshot +const mainPageOnly = await page.snapshot({ includeIframes: false }); ``` @@ -887,6 +900,16 @@ interface ScreenshotOptions { Matches Playwright's screenshot signature with sensible defaults to control how a capture is produced. +### PageSnapshotOptions + +```typescript +type PageSnapshotOptions = { + includeIframes?: boolean; +}; +``` + +- **`includeIframes`** - Whether to include iframe content in the snapshot. Defaults to `true` + ### SnapshotResult ```typescript From 012e5ce296d8f1ccf9cca6c67cf6bf7a51965d71 Mon Sep 17 00:00:00 2001 From: Sean McGuire Date: Fri, 23 Jan 2026 17:26:56 -0800 Subject: [PATCH 3/3] add link to type def --- packages/docs/v3/references/page.mdx | 40 ++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index 5b49ddb22..f1f287bee 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -518,7 +518,7 @@ await page.screenshot(options?: ScreenshotOptions): Promise ### snapshot() -Capture a structured accessibility tree snapshot of the page. Returns a formatted text representation of the page's accessibility tree along with XPath and URL mappings for each element. +Capture a structured accessibility snapshot of the current page. The returned data combines a human-readable accessibility tree with lookup maps so you can relate each node to DOM selectors or URLs. ```typescript await page.snapshot(options?: PageSnapshotOptions): Promise @@ -536,14 +536,28 @@ await page.snapshot(options?: PageSnapshotOptions): Promise -**Returns:** A `Promise` containing the page snapshot data. +**Returns:** A `Promise` describing the captured accessibility tree. -The snapshot provides a hierarchical view of the page's accessibility tree, where each element is represented with: -- A unique encoded ID in brackets (e.g., `[0-1]`) -- The element's accessibility role (e.g., `RootWebArea`, `heading`, `link`, `button`) -- The element's accessible name, if available + + + Multiline text representing the accessibility tree hierarchy with encoded IDs. + + + Maps each encoded ID to the element's absolute XPath for quick DOM lookups. + + + Maps encoded IDs for link-like nodes to their resolved URLs. + + -**Example output:** +See [SnapshotResult](#snapshotresult) for the static type definition. + +The formatted tree represents every accessibility node with: +- A unique encoded ID in brackets (e.g., `[0-1]`) for cross-referencing with the maps +- The node's accessibility role (`RootWebArea`, `heading`, `link`, `button`, etc.) +- The node's accessible name, when available + +**Example formatted output:** ```txt [0-1] RootWebArea: Example Domain @@ -563,11 +577,15 @@ const { formattedTree, xpathMap, urlMap } = await page.snapshot(); // Print the accessibility tree console.log(formattedTree); -// Look up an element's XPath by its encoded ID -console.log(xpathMap["0-8"]); // e.g., "/html/body/div/p[2]/a" +// Look up a specific element's XPath by encoded ID +const linkId = "0-8"; +console.log(xpathMap[linkId]); // e.g., "/html/body/div/p[2]/a" + +// Resolve a link's URL via the urlMap +console.log(urlMap[linkId]); // e.g., "https://www.example.com" -// Look up a link's URL by its encoded ID -console.log(urlMap["0-8"]); // e.g., "https://www.iana.org/domains/example" +// Exclude iframe content when you only need the main document +const mainDocumentSnapshot = await page.snapshot({ includeIframes: false }); ``` ## Viewport