Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs(aria-snapshot): clarify coordinate system for boxes option (#40611)

Pavel Feldman0539bf31e905
diff --git a/docs/src/api/class-locator.md b/docs/src/api/class-locator.md
index 40c0276261..d3a90c0844 100644
--- a/docs/src/api/class-locator.md
+++ b/docs/src/api/class-locator.md
@@ -233,7 +233,9 @@ When specified, limits the depth of the snapshot.
* since: v1.60
- `boxes` <[boolean]>
-When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+Defaults to `false`.
## async method: Locator.blur
* since: v1.28
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index b20c766651..6f9a43f19a 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -4257,7 +4257,9 @@ When specified, limits the depth of the snapshot.
* since: v1.60
- `boxes` <[boolean]>
-When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+relative to the viewport, in CSS pixels, as returned by [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+Defaults to `false`.
## async method: Page.tap
* since: v1.8
diff --git a/packages/playwright-client/types/types.d.ts b/packages/playwright-client/types/types.d.ts
index d75122d29d..604fea6d4f 100644
--- a/packages/playwright-client/types/types.d.ts
+++ b/packages/playwright-client/types/types.d.ts
@@ -2052,7 +2052,10 @@ export interface Page {
*/
ariaSnapshot(options?: {
/**
- * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+ * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+ * relative to the viewport, in CSS pixels, as returned by
+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+ * Defaults to `false`.
*/
boxes?: boolean;
@@ -13032,7 +13035,10 @@ export interface Locator {
*/
ariaSnapshot(options?: {
/**
- * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+ * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+ * relative to the viewport, in CSS pixels, as returned by
+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+ * Defaults to `false`.
*/
boxes?: boolean;
diff --git a/packages/playwright-core/src/tools/backend/snapshot.ts b/packages/playwright-core/src/tools/backend/snapshot.ts
index 516b17da43..aa2d8db27b 100644
--- a/packages/playwright-core/src/tools/backend/snapshot.ts
+++ b/packages/playwright-core/src/tools/backend/snapshot.ts
@@ -42,7 +42,7 @@ const snapshot = defineTabTool({
target: z.string().optional().describe(elementTargetDescription),
filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
depth: z.number().optional().describe('Limit the depth of the snapshot tree'),
- boxes: z.boolean().optional().describe('Include each element\'s bounding box as [box=x,y,width,height] in the snapshot'),
+ boxes: z.boolean().optional().describe('Include each element\'s bounding box as [box=x,y,width,height] in the snapshot. Coordinates are viewport-relative, in CSS pixels (Element.getBoundingClientRect)'),
}),
type: 'readOnly',
},
diff --git a/packages/playwright-core/src/tools/cli-daemon/commands.ts b/packages/playwright-core/src/tools/cli-daemon/commands.ts
index b3dff96875..1f2a067b06 100644
--- a/packages/playwright-core/src/tools/cli-daemon/commands.ts
+++ b/packages/playwright-core/src/tools/cli-daemon/commands.ts
@@ -376,7 +376,7 @@ const snapshot = declareCommand({
options: z.object({
filename: z.string().optional().describe('Save snapshot to markdown file instead of returning it in the response.'),
depth: numberArg.optional().describe('Limit snapshot depth, unlimited by default.'),
- boxes: z.boolean().optional().describe('Include each element\'s bounding box as [box=x,y,width,height] in the snapshot.'),
+ boxes: z.boolean().optional().describe('Include each element\'s bounding box as [box=x,y,width,height] in the snapshot. Coordinates are viewport-relative, in CSS pixels (Element.getBoundingClientRect).'),
}),
toolName: 'browser_snapshot',
toolParams: ({ filename, target, depth, boxes }) => ({ filename, target, depth, boxes }),
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index d75122d29d..604fea6d4f 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -2052,7 +2052,10 @@ export interface Page {
*/
ariaSnapshot(options?: {
/**
- * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+ * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+ * relative to the viewport, in CSS pixels, as returned by
+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+ * Defaults to `false`.
*/
boxes?: boolean;
@@ -13032,7 +13035,10 @@ export interface Locator {
*/
ariaSnapshot(options?: {
/**
- * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Defaults to `false`.
+ * When `true`, appends each element's bounding box as `[box=x,y,width,height]` to the snapshot. Coordinates are
+ * relative to the viewport, in CSS pixels, as returned by
+ * [`Element.getBoundingClientRect()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect).
+ * Defaults to `false`.
*/
boxes?: boolean;