Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/l-xiaoshen/handstage/llms.txt

Use this file to discover all available pages before exploring further.

page.screenshot() captures the current state of a browser tab and returns a Buffer containing the encoded image. You can write that buffer to disk, pass it to an image-processing library, or attach it to a test report. All rendering happens inside Chrome via the CDP Page.captureScreenshot command.

​
Basic usage

import { V3 } from "@handstage/core"
import fs from "fs/promises"

const handstage = await V3.connectLocal()
const page = handstage.context.activePage()

await page.goto("https://example.com")

const buffer = await page.screenshot()
await fs.writeFile("screenshot.png", buffer)

await handstage.close()

​
ScreenshotOptions reference

All fields are optional. Pass them as a single object to page.screenshot(options).
OptionTypeDefaultDescription
type"png" | "jpeg""png"Output image format.
qualitynumber—JPEG compression quality (0–100). Only valid when type is "jpeg".
fullPagebooleanfalseCapture the full scrollable page, not just the viewport. Cannot be used together with clip.
clip{ x, y, width, height }—Capture a sub-region in CSS pixels. Cannot be used together with fullPage.
omitBackgroundbooleanfalseReplace the white background with transparency. Only meaningful for PNG.
animations"allow" | "disabled""allow"Set to "disabled" to freeze CSS animations and Web Animations before capture.
caret"hide" | "initial""hide"Set to "hide" to make text cursors invisible during capture.
scale"device" | "css""device""css" renders one pixel per CSS pixel; "device" uses the current device pixel ratio.
maskLocator[]—Locators whose matched elements are covered with a solid color before capture.
maskColorstring"#FF00FF"Fill color used for masked elements (any valid CSS color string).
stylestring—Additional CSS text injected into every frame before capture and removed afterwards.
pathstring—If provided, Handstage writes the buffer to this file path automatically.
timeoutnumber—Maximum capture duration in milliseconds.

​
Examples

​
Save to a file

The simplest way to persist a screenshot is to pass path: 
await page.screenshot({ path: "output/home.png" })
Handstage writes the file and still returns the Buffer in case you need it for further processing.

​
Capture beyond the viewport

Use fullPage: true to scroll through the entire page content: 
const buffer = await page.screenshot({ fullPage: true, path: "full.png" })

​
Crop to a specific region

Use clip to capture a rectangular sub-region in CSS pixels: 
const buffer = await page.screenshot({
  clip: { x: 100, y: 200, width: 800, height: 400 },
  path: "cropped.png",
})
clip and fullPage are mutually exclusive. Passing both throws an error.

​
Transparent PNG

Set omitBackground: true to remove the white background fill. The resulting PNG will have an alpha channel where no page content is rendered: 
const buffer = await page.screenshot({
  omitBackground: true,
  path: "transparent.png",
})
omitBackground only works with the "png" format. For JPEG, the background is always opaque.

​
JPEG with quality control

const buffer = await page.screenshot({
  type: "jpeg",
  quality: 80,
  path: "compressed.jpg",
})

​
Freeze animations before capture

Set animations: "disabled" to finish or cancel all running CSS animations and Web Animations API animations before the screenshot is taken: 
const buffer = await page.screenshot({
  animations: "disabled",
  path: "static.png",
})

​
Mask sensitive elements

Pass locators to mask to cover matched elements with a solid color. This is useful for redacting personal data in test artifacts: 
const emailField = page.locator("#user-email")
const creditCard = page.locator(".card-number")

const buffer = await page.screenshot({
  mask: [emailField, creditCard],
  maskColor: "#000000",
  path: "redacted.png",
})

​
CSS pixel scale

Use scale: "css" to render one output pixel per CSS pixel, regardless of the device pixel ratio. This keeps screenshot dimensions predictable across machines: 
const buffer = await page.screenshot({
  scale: "css",
  path: "1x.png",
})

Build docs developers (and LLMs) love

Get started for freeTalk to us