iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
There are two different ways to use Puppeteer with a Chrome extension page: run Puppeteer inside the extension using its experimental ExtensionTransport, or run Puppeteer in Node.js and automate an extension loaded in Chrome. The first approach connects through chrome.debugger; the second finds the extension page as a browser target and uses the standard Page.screenshot() method. Choose based on where your code runs.
Choose the Puppeteer setup that matches your runtime
| Workflow | Where Puppeteer runs | How it reaches the page | Main constraint |
|---|---|---|---|
| Extension-internal | In the extension’s browser-compatible JavaScript bundle | Connects to a tab using experimental ExtensionTransport, backed by chrome.debugger |
One page per transport connection; use Chrome’s tabs API and another connection for another page |
| Node-driven extension test | In Node.js, controlling a Puppeteer-launched Chrome instance | Loads the extension at launch, finds the popup target, and converts it to a Puppeteer Page |
Your target match must identify the intended extension page |
Puppeteer’s official guide describes Chrome extensions as allowing access to the Chrome DevTools Protocol through chrome.debugger. It also cautions that the extension environment differs significantly from Node.js and that this support is experimental. Check the Chrome Extensions guide and current API documentation; the documentation version referenced here is 25.12.0.
Run Puppeteer inside the extension
This is the relevant path when the extension itself needs to control a tab and take its screenshot. The browser build must be bundled for use in the extension; Puppeteer’s guide describes using a bundler such as Rollup or webpack.
Connect to a tab and capture it
import {
connect,
ExtensionTransport,
} from 'puppeteer-core/lib/puppeteer/puppeteer-core-browser.js';
const url = 'https://example.com';
const tab = await chrome.tabs.create({ url });
const browser = await connect({
transport: await ExtensionTransport.connectTab(tab.id),
});
const [page] = await browser.pages();
const imageBytes = await page.screenshot();The example creates a tab first because the transport connects to an existing tab. page.screenshot() returns image bytes as a Uint8Array by default. For a second tab, create or locate it with chrome.tabs and establish another transport connection; this transport does not provide ordinary multi-page browser control.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Return base64 instead of bytes
If the next step needs a base64 data string rather than image bytes, request that encoding explicitly:
const base64Image = await page.screenshot({ encoding: 'base64' });Use Node.js to screenshot an extension popup
For automated tests or scripts running outside the extension, launch Chrome with the unpacked extension enabled. Trigger the extension action as appropriate for your setup, wait for its popup page target, convert that target to a page, then use the regular screenshot API.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
const browser = await puppeteer.launch({
enableExtensions: [pathToExtension],
});
// Trigger or open the extension popup before waiting for its target.
const popupTarget = await browser.waitForTarget(
target => target.type() === 'page' && target.url().endsWith('popup.html'),
);
const popupPage = await popupTarget.asPage();
await popupPage.screenshot({ path: 'popup.png' });pathToExtension should identify the unpacked extension directory. Replace the popup.html suffix check with a condition that uniquely matches your extension’s actual popup URL. A suffix match is suitable only if it cannot also match another page in the browser. The official guide also covers accessing extension service workers and background pages; those targets are not interchangeable with the visible popup you want to capture.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsThe relative output path popup.png is written relative to the Node process’s working directory. If you omit path, the method returns image data instead of saving a file.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Choose screenshot options for the result you need
The popup use case usually calls for its visible viewport, while a long extension page may need a full-page capture. Puppeteer’s screenshot options also allow a clipped region, output type, encoding, transparent background, and other controls.
fullPage: defaults tofalse. Set{ fullPage: true }when you intend to capture the full document rather than just the viewport.clip: capture a specified region. The documented default forcaptureBeyondViewportisfalsewhen there is no clip andtruewhen a clip is supplied.path: save the image to a file. Without it, consume the returned screenshot data.type: select the image format using a supported screenshot type for your Puppeteer version.encoding: use the default byte output or request a base64 string.omitBackground: omit the default background when a transparent capture is appropriate.
For example, to save a full-page popup image in Node:
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
await popupPage.screenshot({
path: 'popup-full.png',
fullPage: true,
});Troubleshoot common failures
The extension cannot import Puppeteer
The extension-internal workflow needs a browser-compatible bundle and the browser-specific puppeteer-core entry point shown above. A Node-oriented import or unbundled dependency may not work in an extension environment. Follow the bundling guidance in the official Chrome Extensions guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
The extension transport cannot connect
Confirm that you created or found a tab and are passing its valid tab ID to ExtensionTransport.connectTab(). The transport relies on restricted chrome.debugger access; if the extension lacks the access required by that API, the connection cannot be established.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
The popup target never appears
Make sure the extension is loaded and the popup has actually been opened or triggered before waiting for its target. Check the target’s real URL and adjust the matching condition: a hard-coded popup.html suffix is only an example, not a universal extension URL.
The screenshot is blank, cropped, or missing page content
Verify that you selected the intended popup or tab and that it has finished rendering before capture. For a document taller than the visible area, set fullPage: true; for a specific region, use clip and account for the documented captureBeyondViewport default.
No image file was created
When saving from Node, pass a path and check the Node process’s working directory if the path is relative. Without a path, use the returned bytes or base64 string instead of expecting a file to appear.
Or skip the browser setup
If you need a screenshot of a public website rather than an extension’s own popup or page, ScreenshotNeo provides a one-request screenshot API. It removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. It also provides an MCP server for AI agents, and its free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for parameters and response details. Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
