Implementation:Getgauge Taiko Screenshot
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Testing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for capturing browser page screenshots provided by the Taiko library.
Description
The screenshot function captures visual snapshots of the current browser page in three modes: viewport-only, full-page, and element-specific. The public API is defined in lib/taiko.js (lines 1497-1515) and delegates the actual capture to captureScreenshot in lib/handlers/pageHandler.js (lines 228-256).
When called without a selector, screenshot() captures the current viewport. When the fullPage option is set to true, the function retrieves the page's layout metrics via Page.getLayoutMetrics() to determine the total scrollable content dimensions, then captures the entire page by setting a clip region spanning the full content width and height. When a selector is provided (either a Taiko selector object or an Element), the function locates the element, retrieves its bounding box via domHandler.boundBox(), and captures only the region occupied by that element. An optional padding parameter can expand the clip region around the element. Note that if both a selector and fullPage: true are provided, the full-page option is ignored with a console warning.
The captured screenshot data is returned as a base64-encoded string from the Chrome DevTools Protocol Page.captureScreenshot command. If the encoding option is set to 'base64', the raw data buffer is returned directly. Otherwise, the data is decoded from base64 and written to disk at the path specified by options.path (defaulting to Screenshot-{timestamp}.png).
Usage
Use screenshot() to capture visual evidence of page state during automated testing. Common scenarios include:
- Capturing screenshots on test failure for debugging purposes.
- Taking full-page screenshots for visual regression testing.
- Capturing specific elements for targeted visual comparison.
- Generating base64 screenshot data for embedding in test reports.
Code Reference
Source Location
- Repository: Taiko
- File (public API):
lib/taiko.js - Lines: L1497-1515
- File (capture logic):
lib/handlers/pageHandler.js - Lines: L228-256
Signature
async screenshot(
selector?: Selector | Element | string,
options?: {
fullPage?: boolean,
path?: string,
encoding?: string,
padding?: number,
}
) -> Promise<Buffer | void>
Import
const { screenshot } = require('taiko');
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| selector | Selector, Element, or string | No | Element to capture. When omitted, captures the viewport (or full page if fullPage is true). When a non-selector object is passed as the first argument, it is treated as the options object.
|
| options.fullPage | boolean | No (default: false) | Capture the full scrollable page rather than just the visible viewport. Ignored when a selector is provided. |
| options.path | string | No (default: 'Screenshot-{timestamp}.png') | File path for saving the screenshot to disk. Used when encoding is not 'base64'. |
| options.encoding | string | No (default: 'base64') | Image encoding format. When set to 'base64', the raw buffer is returned instead of writing to disk. |
| options.padding | number | No (default: 0) | Extra padding in pixels around the element bounding box when capturing an element screenshot. |
Outputs
| Name | Type | Description |
|---|---|---|
| return (base64 mode) | Promise<Buffer> | When encoding: 'base64', resolves with the screenshot data as a base64-encoded buffer.
|
| return (file mode) | Promise<void> | When encoding is not 'base64', writes the screenshot to disk at the specified path and resolves with undefined. |
| File on disk | PNG file | The captured screenshot saved to the path specified in options (when not using base64 encoding). |
Usage Examples
Capture Viewport Screenshot
const { screenshot } = require('taiko');
// Capture the current viewport and save to a file
await screenshot({ path: 'viewport.png' });
Full Page Screenshot
const { screenshot } = require('taiko');
// Capture the entire scrollable page
await screenshot({ fullPage: true, path: 'full-page.png' });
Element Screenshot
const { screenshot, text } = require('taiko');
// Capture a specific element identified by its text content
await screenshot(text('Welcome'), { path: 'welcome.png' });
Element Screenshot with Padding
const { screenshot, $ } = require('taiko');
// Capture an element with 10px padding around it
await screenshot($('#hero-banner'), { path: 'banner.png', padding: 10 });
Get Base64 Buffer
const { screenshot } = require('taiko');
// Get screenshot as base64 data (useful for test reports)
const buffer = await screenshot({ encoding: 'base64' });
console.log('Screenshot data length:', buffer.length);
Default File Naming
const { screenshot } = require('taiko');
// When no path is specified, saves as Screenshot-{timestamp}.png
await screenshot();
// Creates file like: Screenshot-1707696000000.png