Domotion

captureElementTree()

Walk a Playwright page's DOM into a serialisable tree.

Captures the DOM under a CSS selector inside a Playwright Page and returns a CapturedElement[] tree. This is half of the core API — the other half is elementTreeToSvg().

Signature

function captureElementTree(
  page: Page,
  selector?: string,
  viewport: { x: number; y: number; width: number; height: number },
): Promise<CapturedElement[]>

Parameters

page
Page
A Playwright page returned by browser.newPage(). The page must already have its content loaded — Domotion does not navigate for you.
selector
string (default "body")
CSS selector identifying the root of the subtree to capture. Anything outside the matched element is ignored.
viewport
{ x, y, width, height }
Pixel rectangle (in page coordinates) that defines what counts as "in view". Elements with no overlap with this rect are skipped. The captured tree's coordinates are relative to this rectangle.

Returns

A promise resolving to an array of CapturedElement nodes. The array is the children of the matched selector — pass it directly to elementTreeToSvg(tree, vp.width, vp.height).

Examples

Capture a full page region

const tree = await captureElementTree(page, "body", {
  x: 0, y: 0, width: 1200, height: 800,
});

Capture a specific component

const rect = await page.locator(".product-card").boundingBox();
if (rect == null) throw new Error("product-card not found");
const tree = await captureElementTree(page, ".product-card", rect);

Capture a long, scrollable page

const pageHeight = await page.evaluate(() => document.body.scrollHeight);
const tree = await captureElementTree(page, "body", {
  x: 0, y: 0, width: 1200, height: pageHeight,
});

Capture warnings

If the page uses CSS features that fall back to a raster region, Domotion records warnings on the call. getLastCaptureWarnings() and logCaptureWarnings() are exported from the package root:

import { getLastCaptureWarnings } from "domotion";

const tree = await captureElementTree(page, "body", vp);
for (const w of getLastCaptureWarnings()) {
  console.warn(`${w.feature} on ${w.selector}: ${w.detail}`);
}

Warnings are stored on a module-level singleton that resets at the start of each captureElementTree call. For multi-frame captures, read them between calls if you care which frame produced which warning.

Common pitfalls

  • Selector matches multiple elements: only the first match is captured. Use a more specific selector or call page.locator(...).first() beforehand.
  • Calling before content is ready: if you call right after page.goto, you may capture an unstyled or unrendered version of the page. Wait on document.fonts.ready, an explicit selector, or a short timeout.
  • Viewport doesn't match SVG dimensions: Domotion captures in viewport-relative coordinates. If you pass { width: 1200, height: 600 } to capture but elementTreeToSvg(tree, 800, 400) to render, content beyond the SVG's dimensions is clipped (not scaled).

See also