How to Take Full Page Snapshots and Screenshots with ego-lite

To capture full page screenshots with ego-lite, use await page.screenshot({ fullPage: true }) for complete page images or await page.snapshot() for semantic HTML snapshots that always include the entire DOM.

The citrolabs/ego-lite browser automation library provides two distinct methods to take full page snapshots or screenshots with ego-lite, depending on whether you need visual renders or semantic markup. Understanding the difference between page.snapshot() and page.screenshot() ensures you capture the right data format for your testing or monitoring workflows.

Understanding ego-lite's Page Capture Methods

ego-lite exposes two high-level helpers on the page object that serve different capture purposes. The page.snapshot() method returns a semantic representation of the page's HTML structure with stable locators, while page.screenshot() generates visual PNG images of the rendered content.

Capturing Full Page Screenshots (Images)

When you need visual documentation of an entire scrollable page, ego-lite's screenshot functionality supports full-page rendering through a specific configuration option.

The screenshot() Method and fullPage Option

By default, page.screenshot() captures only the visible viewport. To take full page screenshots with ego-lite, pass fullPage: true in the options object. According to the source code in src/driver/observe.ts, this flag maps directly to Chrome DevTools Protocol's captureBeyondViewport parameter.

When fullPage is enabled, the driver constructs a clip rectangle using the full page dimensions (info.w/info.h or info.pw/info.ph) and forwards this to Page.captureScreenshot. If omitted or set to false, the capture limits itself to the current viewport dimensions.

Code Examples for Full Page Screenshots

The following examples demonstrate various screenshot scenarios using the public API exposed in src/helpers.ts:

// Capture viewport-only screenshot (default behavior)
const thumbPath = await page.screenshot({ path: '/tmp/thumb.png' });
console.log('Saved viewport screenshot to', thumbPath);

// Capture full page screenshot by setting fullPage: true
const fullPath = await page.screenshot({
  path: '/tmp/full.png',
  fullPage: true,  // Triggers complete scrollable page capture
});
console.log('Saved full-page screenshot to', fullPath);

// Retrieve raw base64 PNG data without saving to disk
const rawData = await page.screenshot({ fullPage: true, raw: true });
console.log('Base64 PNG data length:', rawData.length);

Creating Semantic Page Snapshots

For programmatic access to the complete page structure rather than pixel data, ego-lite provides semantic snapshot capabilities.

The snapshot() Method

The page.snapshot() method, documented in src/format.ts and implemented through snapshotRaw() in src/driver/observe.ts, returns a string containing the full HTML content with injected refs and stable locators. Unlike screenshots, snapshots always capture the entire DOM regardless of viewport constraints, requiring no additional flags.

// Capture semantic snapshot of the whole page (always full DOM)
const snapshot = await page.snapshot();
console.log(snapshot);  // Returns HTML string with references

This approach is particularly useful for accessibility testing, DOM diffing, and extracting structured content without rendering overhead.

Key Implementation Details

The full-page screenshot logic resides in src/driver/observe.ts, where the fullPage boolean is translated to CDP's captureBeyondViewport capability. The implementation calculates clip dimensions using the page's total scrollable width and height, ensuring the resulting image encompasses all content areas.

For snapshots, the snapshotRaw() function in the same file traverses the complete document tree, generating stable references for interactive elements while preserving the full markup structure.

Summary

• Use page.screenshot({ fullPage: true }) to capture visual images of the entire scrollable page, implemented in src/driver/observe.ts using Chrome DevTools Protocol's captureBeyondViewport.
• Use page.snapshot() to extract complete semantic HTML snapshots without configuration flags; this always returns the full DOM via snapshotRaw().
• Reference src/helpers.ts for the public API surface exposing both methods to browser automation scripts.
• Pass raw: true to page.screenshot() to receive base64-encoded image data instead of file system paths.

Frequently Asked Questions

How do I capture a full page screenshot in ego-lite?

Call await page.screenshot({ fullPage: true }) to capture the entire scrollable page as a PNG image. This option triggers the browser to render all content beyond the current viewport before taking the screenshot, as implemented in src/driver/observe.ts.

What is the difference between page.snapshot() and page.screenshot() in ego-lite?

page.snapshot() returns a semantic HTML string representing the complete DOM structure with stable element references, while page.screenshot() generates a visual PNG image of the rendered page. Snapshots always include the full document via snapshotRaw(), whereas screenshots require fullPage: true to capture beyond the viewport.

Where does ego-lite handle the fullPage screenshot logic?

The fullPage option is processed in src/driver/observe.ts, where it maps to Chrome DevTools Protocol's captureBeyondViewport parameter. This file constructs the full-page clip dimensions and invokes Page.captureScreenshot with the appropriate bounding box coordinates.

Can I get raw base64 data instead of saving to a file?

Yes. Pass raw: true to page.screenshot() along with your other options (such as fullPage: true). The method will return a base64-encoded string containing the PNG image data rather than a file path, allowing you to process the image in memory or transmit it to external services.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}