ScreenshotNeo

BlogHow-to

How to Test Multiple Selectors in Puppeteer

Learn how to try selector fallbacks, inspect every match, wait for late-rendered elements, and avoid confusing selectors with multi-select forms.

By the ScreenshotNeo team30 September 202610 min read

How to Test Multiple Selectors in Puppeteer

In Puppeteer, “test multiple selectors” usually means one of two things: try several candidate selector strings until one identifies the intended element, or inspect every element matched by one selector. These are different tests and need different APIs.

Use page.$() when you need one match, page.$$() when you need all matches, and page.$eval()/page.$$eval() when you want to extract or assert data in the page context. For content that appears later, use a locator for an interaction or page.waitForSelector() when you specifically need to wait for DOM presence or visibility. Puppeteer’s documentation says, “Locators is the recommended way to select an element and interact with it.”

1. Decide what “multiple selectors” means

Goal Use What to assert
Try fallback selectors Loop over selector strings with page.$() or page.$$() The chosen selector identifies the intended element, with the expected count or content
Inspect all matches page.$$() or page.$$eval() Count, text, attributes, or another property for every match
Wait for late-rendered content Locator or page.waitForSelector() Presence, visibility, and action readiness within a defined timeout
Select several form values page.select(selector, ...values) The matching <select multiple> contains the requested values

A non-empty query is not proof that you found the right control. A broad class selector may match a hidden template, a duplicate card, or an unrelated element. Your test must define what “correct” means.

2. Set up a reproducible Puppeteer test

Install Puppeteer and launch a browser. The examples below use the current documented API shape from Puppeteer 25.x; check the version installed in your project before relying on defaults.

npm install puppeteer
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({headless: true});
  const page = await browser.newPage();
  await page.goto('https://example.com', {waitUntil: 'domcontentloaded'});
  // selector tests go here
  await browser.close();
})();

Keep the page state controlled: navigate to a known URL, set authentication or cookies before the query when required, and avoid asserting against a page that is still changing.

3. Try several candidate selectors

Represent fallback selectors as data, then test each candidate against the requirement for your target. This example accepts the first candidate that finds exactly one visible-looking DOM match and verifies its text. It does not assume that the first match is automatically correct.

Candidate selectors should be validated against count and meaning before one is chosen.
Candidate selectors should be validated against count and meaning before one is chosen.
const candidates = [
  '[data-testid="checkout-submit"]',
  'button[name="checkout"]',
  'form#checkout button[type="submit"]'
];

let chosen = null;
for (const selector of candidates) {
  const matches = await page.$$(selector);
  if (matches.length !== 1) {
    continue;
  }

  const summary = await page.$eval(selector, el => ({
    text: (el.textContent || '').trim(),
    disabled: el.hasAttribute('disabled'),
    tag: el.tagName.toLowerCase()
  }));

  if (summary.tag === 'button' && /checkout|pay|continue/i.test(summary.text)) {
    chosen = {selector, summary};
    break;
  }
}

if (!chosen) {
  throw new Error('No candidate selector identified the checkout button');
}
console.log(chosen);

Use page.$() instead when existence is enough:

for (const selector of candidates) {
  const handle = await page.$(selector);
  if (handle) {
    console.log(`Found a candidate: ${selector}`);
    await handle.dispose();
    break;
  }
}

Dispose of an ElementHandle when you are finished with it. If the test needs to click the element, a locator is usually safer because it can wait for the element to reach an actionable state.

Candidate testing checklist

  • Keep selectors ordered from the most specific contract to the most general fallback.
  • Assert the expected count: exactly one for a unique control, a known range for repeated content, or at least one only when duplicates are valid.
  • Check stable attributes, role, text, or surrounding structure to reject unrelated matches.
  • Log the selector that won so a failure can be diagnosed from CI output.
  • Fail clearly when all candidates miss; do not silently continue with a null handle.

4. Inspect every match from one selector

When the question is “what does this selector match?”, use page.$$() for handles or page.$$eval() to return serializable data. The callback receives the matching elements as its first argument and runs in the page context.

const cards = await page.$$eval('.product-card', elements =>
  elements.map((element, index) => ({
    index,
    title: element.querySelector('h2,h3')?.textContent?.trim() || '',
    href: element.querySelector('a')?.href || '',
    hidden: element.getAttribute('aria-hidden') === 'true' ||
      getComputedStyle(element).display === 'none'
  }))
);

if (cards.length !== 12) {
  throw new Error(`Expected 12 product cards, found ${cards.length}`);
}

const visibleCards = cards.filter(card => !card.hidden);
if (visibleCards.some(card => !card.title || !card.href)) {
  throw new Error('A visible product card is missing title or link');
}

Use page.$$() when you need to interact with each element:

const rows = await page.$$('table#orders tbody tr');
try {
  for (const row of rows) {
    console.log(await row.$eval('td.status', el => el.textContent.trim()));
  }
} finally {
  await Promise.all(rows.map(row => row.dispose()));
}

5. Use CSS and Puppeteer’s extended selector syntax

CSS selectors work by default. Puppeteer also documents syntax for text, accessibility attributes, XPath, and Shadow DOM. Choose the syntax that reflects the page contract and keep the query understandable.

// CSS
await page.$('button[data-action="save"]');

// Text selector
await page.$('::-p-text(Save changes)');

// Accessibility selector
await page.$('::-p-aria(Save changes)');

// XPath
await page.$('::-p-xpath(//button[contains(., "Save")])');

Syntax support and escaping rules can change with Puppeteer releases. Prefer stable attributes such as data-testid when you control the markup. Do not claim that one selector type is universally more reliable; the right choice depends on the DOM and the behavior under test.

6. Handle asynchronous rendering

A query made immediately and a wait are different operations. A selector can be valid while returning no matches because a framework has not rendered the component yet.

A query checks the current DOM; a locator or explicit wait handles content that appears later.
A query checks the current DOM; a locator or explicit wait handles content that appears later.

Use a locator for an interaction

const submit = page.locator('button[data-testid="checkout-submit"]');
await submit.click();

Locators are intended for selection and interaction and wait for the element to be present and suitable for the action. If several candidate selectors are possible, create a small helper that checks them and returns a locator after validating the DOM:

async function findUniqueSelector(page, selectors) {
  for (const selector of selectors) {
    if (await page.$$eval(selector, els => els.length === 1)) {
      return selector;
    }
  }
  throw new Error(`None of these selectors matched uniquely: ${selectors.join(', ')}`);
}

const selector = await findUniqueSelector(page, candidates);
await page.locator(selector).click();

Use waitForSelector for a lower-level wait

page.waitForSelector(selector, options) waits for a selector to appear. The documented options include visible, hidden, timeout, and signal. The default timeout is 30 seconds; timeout: 0 disables the timeout. It throws when the selector does not appear before the timeout. Waiting for hidden: true can return null when the selector is absent.

try {
  const handle = await page.waitForSelector(
    '[data-testid="results"]',
    {visible: true, timeout: 10000}
  );
  if (!handle) throw new Error('Results handle was null');
  try {
    console.log(await handle.evaluate(el => el.textContent.trim()));
  } finally {
    await handle.dispose();
  }
} catch (error) {
  throw new Error(`Results did not become visible: ${error.message}`);
}

Use a finite timeout that matches the test’s contract. An unlimited wait can hide a broken page and leave a worker stuck.

7. Do not confuse selectors with selecting multiple form values

Testing alternative selector strings is unrelated to choosing several options in an HTML form. For a multiple select control, use page.select():

await page.select('select#colors', 'red', 'green');

const selected = await page.$$eval(
  'select#colors option:checked',
  options => options.map(option => option.value)
);

if (selected.sort().join(',') !== 'green,red') {
  throw new Error(`Unexpected selected values: ${selected.join(',')}`);
}

The method throws if no matching <select> exists. It triggers change and input events, and all supplied values are considered when the select has the multiple attribute.

8. A reusable selector-test helper

Centralize candidate logic so every test reports the same diagnostics.

async function assertCandidate(page, selectors, check) {
  const attempts = [];
  for (const selector of selectors) {
    const count = await page.$$eval(selector, els => els.length);
    attempts.push({selector, count});
    if (count === 0) continue;

    const passed = await page.$eval(selector, check).catch(() => false);
    if (passed) return selector;
  }
  throw new Error(`No selector passed: ${JSON.stringify(attempts)}`);
}

const target = await assertCandidate(
  page,
  candidates,
  element => element.matches('button') && !element.disabled
);
console.log(`Using ${target}`);

Keep the callback self-contained: variables from Node.js are not available inside the browser context unless passed as arguments.

9. Troubleshooting common failures

Symptom Likely cause Fix
Every candidate returns zero The page has not rendered, the selector is scoped to the wrong frame, or the element is inside Shadow DOM Wait for the relevant state, inspect frames, or use documented Shadow DOM syntax
Several candidates match unrelated nodes The selector is too broad or a hidden template is included Assert count and inspect role, text, attributes, and visibility
waitForSelector times out Wrong URL, blocked navigation, delayed API response, or incorrect visibility expectation Capture the URL, response status, and a diagnostic screenshot; increase a finite timeout only when the page contract justifies it
Click fails after a successful query The node exists but is covered, disabled, detached, or outside the viewport Use a locator, wait for action readiness, and verify the element is still attached
Text selector finds nothing Whitespace, localization, nested text, or changed Puppeteer syntax Prefer stable attributes or use a predicate that normalizes text
Data is empty in $$eval The callback reads a property that is not present or runs before hydration Return explicit defaults and wait for the page state that creates the data
Cross-origin iframe is missing The query ran on the top-level page Find the correct Frame and run the selector there

10. Performance, reliability, and cost

  • Performance: One $$eval that extracts all required fields avoids repeated round trips between Node.js and the page. Query only the subtree you need and avoid expensive broad selectors in tight polling loops.
  • Reliability: Assert semantic properties, not only existence. Record the candidate list and counts on failure. Use finite timeouts, deterministic test data, and a fresh page when state can leak between cases.
  • Frames and shadow roots: A selector is evaluated in a particular document. Explicitly select the frame or shadow-root context instead of changing the selector until it accidentally works.
  • Retries: Retrying a missing selector can help with known asynchronous rendering, but it should not mask a navigation or application error. Capture diagnostics before retrying.
  • Cost: Running Chromium yourself means maintaining browser binaries, CPU and memory capacity, concurrency limits, and failed-run handling. If you only need an image or PDF from a URL, an API can remove that setup.

11. Or skip the browser setup

For a screenshot rather than an interaction test, ScreenshotNeo provides a single GET request that returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API docs for the complete option list.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = require('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, newsletter popups, and chat widgets are removed before the shot, with each cleanup step configurable. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and whether the request was billed. ScreenshotNeo also offers custom CSS and JavaScript, selector-based element capture, full-page lazy-image loading, device presets, arbitrary viewports, dark mode, retina scale, PDF controls, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month at no cost.

12. FAQ

Can I pass an array of selectors directly to page.$()?

No. Pass one selector string at a time, or write a loop over your candidate array. A CSS selector list such as button, a.cta is one query with combined matching semantics, not an ordered fallback test.

Should I use $eval or $$eval?

Use $eval when exactly one match is expected and $$eval when the page function should receive every match. Assert the expected count before treating the result as valid.

Does waitForSelector guarantee that a click will work?

No. It waits for selector presence, or visibility when requested. A locator is designed to wait for a suitable interaction state; your test still needs to account for overlays, disabled controls, and navigation.

How do I test a selector inside an iframe?

Find the frame from page.frames() or its URL, then call frame.$(), frame.$$(), or the corresponding evaluation method on that frame.

What should a selector contract contain?

Document the expected count, the semantic property that identifies the element, the rendering state required before querying, and the timeout. This makes a selector failure actionable instead of leaving a vague “not found” error.

For the official API details, see Puppeteer’s Page interactions guide, the waitForSelector reference, and the select reference.