Recommended Free Tools
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
You can run Puppeteer from a Chrome extension by bundling its browser-compatible entry point and connecting to a tab with ExtensionTransport. That connection is limited to one tab and uses Chrome’s restricted chrome.debugger API; Puppeteer documents this extension support as experimental. If you mean running Puppeteer in Node.js to control Chrome, use the standard launch or connect workflow instead. The distinction matters: an extension-side Puppeteer session is not a full-browser session.
Choose the architecture that matches your goal
| Approach | Where Puppeteer runs | Browser connection | Scope | Best fit |
|---|---|---|---|---|
| Extension-side Puppeteer | Extension-compatible JavaScript | chrome.debugger via ExtensionTransport |
One tab per connection | Automation initiated within an extension |
| Node.js Puppeteer | Node.js process | Launches Chrome or connects to a separately managed browser | Normal browser-level workflow | Scripts, test runners, and remote browser automation |
| Node.js testing a Chrome extension | Node.js process | Launches Chrome with the extension enabled | Browser and extension targets | End-to-end tests of extension behavior |
For extension-side automation, Puppeteer connects through the extension transport; the official guide describes the feature as experimental. For general automation or multiple pages, Node.js Puppeteer is usually the more direct fit. Puppeteer’s extension guide and its Chrome Extensions guide document the separate workflows.
Run Puppeteer inside a Chrome extension
Prerequisites and limitations
- Build the extension-compatible Puppeteer entry point with a bundler such as Rollup or webpack. The browser-specific entry point is not a Node.js import recipe.
- Declare the
debuggerpermission in the extension manifest. Chrome warns users about this permission. - The connection represents one tab. Open additional tabs with
chrome.tabsand establish a separate Puppeteer connection for each. chrome.debuggeris a restricted Chrome DevTools Protocol transport and does not expose every protocol domain.
These constraints make the design appropriate when extension code needs Puppeteer’s page, frame, or worker automation API for its attached tab—not when it needs ordinary full-browser control. Verify behavior against the Chrome versions and extension lifecycle you support, because the extension environment differs from Node.js.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Minimal extension-side example
import {
connect,
ExtensionTransport,
} from 'puppeteer-core/lib/puppeteer/puppeteer-core-browser.js';
const tab = await chrome.tabs.create({url: 'https://example.com'});
const browser = await connect({
transport: await ExtensionTransport.connectTab(tab.id),
});
const [page] = await browser.pages();
await page.locator('body').wait();Bundle this code for the extension. It creates a tab, attaches Puppeteer to that tab, gets the page associated with the connection, and waits for the body locator. To automate another tab, create it with Chrome’s tabs API and connect to it separately.
#1 Best Overall
- SOOVOW 1pcs Chrome Extension Tube
Manifest permission
Add debugger to the extension’s manifest permissions before calling chrome.debugger. Without it, Chrome will not grant the extension access to this transport. The permission warning is a consequence of the API’s privileged debugging access, so make sure it is appropriate for your extension’s purpose.
Use Node.js to launch or connect to Chrome
Use the normal Puppeteer APIs if the controller should run outside Chrome. The puppeteer package downloads a compatible Chrome for Testing browser by default; puppeteer-core does not download Chrome and is intended for a browser you manage yourself or a remote browser.
Rank #2
Runnable Node.js example
Install the full package and create a script such as capture.mjs:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →npm install puppeteerimport puppeteer from 'puppeteer';
const browser = await puppeteer.launch({headless: true});
try {
const page = await browser.newPage();
await page.goto('https://example.com', {waitUntil: 'domcontentloaded'});
console.log(await page.title());
} finally {
await browser.close();
}Run it with node capture.mjs. The script launches Chrome, opens a page, navigates, prints the title, and closes the browser even if an operation fails. For a separately managed browser, install puppeteer-core and use Puppeteer’s documented connect workflow with that browser’s endpoint instead of launching a bundled browser.
Match Puppeteer to its browser and runtime
Current Puppeteer documentation says that since v20 it downloads and works with Chrome for Testing. Headless and headful modes share the same browser code path; chrome-headless-shell is the older headless implementation. Supported browser mappings are release-specific, so check the supported browsers table for the Puppeteer version you install rather than assuming any local Chrome version is compatible.
The current system requirements list Node 22.12 or later and document supported Chrome for Testing platforms. Both requirements and version mappings can change, so confirm them when upgrading or setting up a new environment.
Test a Chrome extension from Node.js
Testing an extension is different from running Puppeteer inside the extension. In this workflow, Node.js launches Chrome with the extension enabled and then inspects extension targets—such as a Manifest V3 service worker, a Manifest V2 background page, a popup, or a content-script realm. The Puppeteer Chrome Extensions guide documents enableExtensions and these target workflows. Use this approach for end-to-end tests of extension behavior; use ExtensionTransport when the extension itself must execute Puppeteer against its attached tab.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common setup failures
| Symptom | Likely cause | What to check or do |
|---|---|---|
| Cannot resolve the browser-specific Puppeteer import | The extension bundle is using the Node entry point or is not bundling the browser entry point. | Import puppeteer-core/lib/puppeteer/puppeteer-core-browser.js and build it with an extension-compatible bundler. |
| Chrome denies the debugger operation | The extension has not declared the debugger permission, or the API is unavailable in the current context. |
Check the manifest permissions and the Chrome extension context in which the call runs. |
| A second page cannot be created from the attached Puppeteer browser | The extension transport connection is scoped to one tab. | Create another tab with chrome.tabs, then call ExtensionTransport.connectTab for its tab ID. |
| Node.js Puppeteer fails to launch or connect | The selected package, browser installation, or browser version does not match the intended workflow. | Use puppeteer for its downloaded compatible Chrome for Testing build, or puppeteer-core when managing the browser separately; check the supported-browser mapping. |
| An extension test cannot find its service worker, popup, or background target | The test is using the extension-side transport workflow rather than launching Chrome with the extension enabled. | Follow Puppeteer’s Node.js Chrome Extensions workflow and inspect the appropriate extension target. |
Performance, reliability, and cost considerations
- Scope: Extension transport is intentionally narrower than normal browser control. For multiple pages, manage tabs through Chrome and create a separate connection per tab, or move the controller to Node.js.
- Compatibility: Experimental extension support and Chrome’s restricted protocol access mean you should validate the actual target Chrome versions and lifecycle. Do not assume Node.js package behavior transfers unchanged.
- Browser ownership: The full
puppeteerpackage simplifies local setup by downloading a compatible browser.puppeteer-coreavoids that download but leaves installation and compatibility management to you. - Cost: The documented setup uses JavaScript packages and Chrome binaries; the sources do not establish a fixed hosting cost or performance benchmark. A remote browser may add provider charges, so check the provider’s current terms separately.
Or skip the browser setup
If your actual goal is getting a screenshot rather than controlling a browser session, ScreenshotNeo provides a website screenshot API. One GET request returns a PNG, JPEG, WebP, or PDF. For example, this cURL request captures a page as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Frequently Asked Questions
Can an extension-side Puppeteer connection control multiple tabs?
No. Each ExtensionTransport connection is for one tab; create other tabs through Chrome’s tabs API and connect separately.
Does using Puppeteer to test a Chrome extension mean Puppeteer runs inside the extension?
No. In extension testing, Puppeteer runs in Node.js and launches Chrome with the extension enabled.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
