Use browser.targets() or browserContext.targets() to filter targets that already exist; use browser.waitForTarget(predicate) when you need to wait for one to appear. In either case, combine target.type() with a URL check to avoid selecting the wrong page or worker.
Choose between a snapshot and waiting for a target
Puppeteer exposes active targets as arrays, so JavaScript’s filter() and find() are the direct tools for selecting among them. The right API depends on whether the target exists already and which browser contexts you want included.
As an Amazon Associate I earn from qualifying purchases.
| Need | Use | What it covers |
|---|---|---|
| Inspect existing targets across the browser | browser.targets() |
Active targets in all browser contexts |
| Inspect existing targets in one context | context.targets() |
Active targets in that browser context |
| Wait for a target that may appear after an action | browser.waitForTarget(predicate) |
Resolves when a target matches the predicate |
These APIs and target conversion behavior are documented in the Puppeteer Browser API, BrowserContext API, and waitForTarget API. Puppeteer documentation has version labels ranging from 25.9.0 to 25.12.0 as well as a next-version reference; check the signatures for the version installed in your project.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsFilter targets that already exist
Match a page by type and URL
Use filter() to retain every match, or find() when you want the first matching target. Match the type as well as the URL: a URL check alone does not establish that the target is a page.
#1 Best Overall
const matchingPages = browser.targets().filter(target =>
target.type() === 'page' && target.url().includes('/dashboard')
);
const appTarget = browser.targets().find(target =>
target.type() === 'page' && target.url().startsWith('https://app.example/')
);filter() returns an array, including an empty array if no target matches. find() returns the first match or undefined. Use a URL condition specific enough for your application, but do not assume URLs are unique.
Limit the search to one browser context
When context isolation matters, enumerate that context rather than the entire browser:
Rank #2
const targets = context.targets();
const workers = targets.filter(target => target.type() === 'service_worker');This avoids selecting an otherwise matching target from another context.
Wait for a future page, popup, or worker
If a click or other action is expected to create the target, use waitForTarget() with a predicate that checks both target kind and URL. Puppeteer’s Chrome Extensions guide uses this pattern for service workers and extension popups.
Rank #3
const target = await browser.waitForTarget(target =>
target.type() === 'page' && target.url().endsWith('/dashboard')
);
const page = await target.page();For an extension popup, the same pattern can match its page URL:
const popup = await browser.waitForTarget(target =>
target.type() === 'page' && target.url().endsWith('popup.html')
);
const popupPage = await popup.asPage();Use a sufficiently precise predicate when several pages or workers may share the same type. A matching suffix is a condition, not proof that only one target can have that URL. The official examples are in the Puppeteer Chrome Extensions guide.
Know which target types you are filtering
target.type() identifies the target kind. The documented values are page, service_worker, shared_worker, background_page, browser, other, and webview. Filter to the type you intend to handle rather than treating every target as a page.
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 & 11const pages = browser.targets().filter(target => target.type() === 'page');
const serviceWorkers = browser.targets().filter(target => target.type() === 'service_worker');Convert a target only after checking its kind
Target conversion methods do not all apply to every target. According to Puppeteer’s Target API, page() returns a page for page, webview, or background_page targets and can return null otherwise. worker() returns a worker only for service_worker or shared_worker targets and can also return null.
Best Value
if (target.type() === 'service_worker') {
const worker = await target.worker();
if (worker) {
// Use the service worker here.
}
}asPage() forcefully creates a page representation for a target of any type, including other. Use it only when that behavior is intentional; it is not a replacement for checking whether the target is naturally page-like.
Track target creation, URL changes, and destruction
A one-time call to targets() is a snapshot. If your program must react as targets appear, change URL, or close, subscribe to the browser context’s lifecycle events: targetcreated, targetchanged, and targetdestroyed. The targetchanged event fires when a target’s URL changes, as described in the BrowserContextEvent reference.
context.on('targetcreated', target => {
if (target.type() === 'page' && target.url().includes('/dashboard')) {
// Handle a newly created matching page target.
}
});
context.on('targetchanged', target => {
if (target.type() === 'page' && target.url().includes('/dashboard')) {
// The target URL changed to a matching URL.
}
});
context.on('targetdestroyed', target => {
if (target.type() === 'page') {
// Handle a page target closing.
}
});Keep event handlers narrow: test the target kind and URL before doing work, and account for URL changes rather than assuming a target’s initial URL is its final one.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Troubleshoot common selection problems
- No match from
find(): it returnsundefinedwhen no current target meets the predicate. Check the URL condition and target type, or usewaitForTarget()if the target is expected to appear later. - Unexpected target from
browser.targets(): it includes active targets from all browser contexts. Usecontext.targets()if the search must stay within one context. page()returnsnull: the target may not be page-like. Checktype(); useworker()for a service or shared worker, orasPage()only if force-converting is intended.- A wait matches the wrong target: a type-only predicate may match several targets. Add a URL condition that distinguishes the page or worker you need.
- A target’s URL no longer matches: a target can change URL. For ongoing monitoring, handle
targetchangedas well as creation and destruction. - API behavior differs from an example: verify the API against the installed Puppeteer version; the official documentation includes multiple version labels.
Or skip the browser setup
If your goal is to get a website screenshot rather than inspect Puppeteer targets, ScreenshotNeo offers a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF, without setting up Puppeteer in your app. See the ScreenshotNeo documentation for parameters.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers identifying the verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
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.
