ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Make an AI Agent Wait for a Specific Element Before Taking a Webpage Screenshot

Wait for the exact page element your agent needs, then capture only when it is ready. Includes Playwright and Puppeteer examples, timeouts, and troubleshooting.

By the ScreenshotNeo team4 October 20268 min read

Make the screenshot conditional on the page element your AI agent needs. In Playwright, wait for a locator to become visible, then capture the page or the element itself:

const target = page.locator('#results');
await target.waitFor({ state: 'visible', timeout: 10_000 });
await page.screenshot({ path: 'page.png' });

Use target.screenshot() instead of page.screenshot() to capture only the target. In Puppeteer, the equivalent is page.waitForSelector() with visible: true. A visible element is a useful rendering condition, but it does not prove that an application has finished loading its data. For that, wait for an application-specific readiness signal as well.

1. Choose the right readiness condition

First decide what “ready” means for this screenshot. The DOM can contain an element before it is displayed, and a displayed element can still contain a loading state or incomplete data.

Condition Use it when What it tells you
Attached You only need the node to exist in the DOM. The element is present; it may not be visible.
Visible The target should be rendered before capture. Playwright defines visible as a non-empty bounding box with no visibility:hidden.
Application ready The screenshot must show complete results or a finished state. A page-specific signal says the relevant content is ready; visibility alone does not establish this.

Playwright locator waits support attached, detached, visible, and hidden; visible is the default. Use hidden or detached when you need to wait for a loading overlay or placeholder to go away. Use a finite timeout and handle expiration as a normal outcome. Avoid replacing a condition you can observe with an arbitrary sleep. Playwright locator wait documentation

2. Playwright: wait for a selector, then capture

This runnable Node.js example opens a URL, waits for a target to render, and captures the full page. Install Playwright and its browser with npm install playwright and npx playwright install chromium, then save this as capture.mjs.

import { chromium } from 'playwright';

const url = process.argv[2] ?? 'https://example.com';
const selector = process.argv[3] ?? 'h1';
const browser = await chromium.launch({ headless: true });

try {
  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });

  const target = page.locator(selector);
  await target.waitFor({ state: 'visible', timeout: 10_000 });
  await page.screenshot({ path: 'page.png', fullPage: true });
} catch (error) {
  console.error(`Screenshot capture failed: ${error.message}`);
  process.exitCode = 1;
} finally {
  await browser.close();
}

Run it with node capture.mjs https://example.com "main h1". The selector is passed as a CSS selector. Choose a stable ID, semantic container, or other selector tied to the content instead of a positional selector that can change when the page layout changes.

Wait for application-specific readiness

If the target appears before its data is complete, wait for a separate signal that represents completion. For example, if the application adds data-state="ready" to the results panel only after fetching its data:

const results = page.locator('#results');
await results.waitFor({ state: 'visible', timeout: 10_000 });
await page.locator('#results[data-state="ready"]').waitFor({
  state: 'visible',
  timeout: 10_000,
});
await page.screenshot({ path: 'results.png', fullPage: true });

Replace that selector with a real signal from the site, such as a completion status or disappearance of a known loading indicator. Do not assume a generic network-idle condition means every application has finished its work.

Capture only the element

To frame the screenshot to the target’s bounds, wait for it and call the locator’s screenshot method:

const target = page.locator('#results');
await target.waitFor({ state: 'visible', timeout: 10_000 });
await target.screenshot({ path: 'results.png' });

Playwright’s locator screenshot performs actionability checks and scrolls the target into view. It captures the element’s bounds, not the whole page. Covered portions may not be visible, and a scrollable target may show only the content in its current scroll position. Playwright screenshot documentation

3. Puppeteer: equivalent wait and screenshot

Puppeteer’s waitForSelector accepts visibility and timeout options. Install Puppeteer with npm install puppeteer; save this as capture-puppeteer.mjs.

import puppeteer from 'puppeteer';

const url = process.argv[2] ?? 'https://example.com';
const selector = process.argv[3] ?? 'h1';
const browser = await puppeteer.launch({ headless: true });

try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1440, height: 900 });
  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });

  await page.waitForSelector(selector, { visible: true, timeout: 10_000 });
  await page.screenshot({ path: 'page.png', fullPage: true });
} catch (error) {
  console.error(`Screenshot capture failed: ${error.message}`);
  process.exitCode = 1;
} finally {
  await browser.close();
}

Run with node capture-puppeteer.mjs https://example.com "main h1". To capture the element rather than the page, wait for the selector and pass it to Puppeteer’s element screenshot flow:

const element = await page.waitForSelector('#results', {
  visible: true,
  timeout: 10_000,
});
await element.screenshot({ path: 'results.png' });

Puppeteer documents both page and element screenshots; element capture attempts to scroll the element into view. Puppeteer screenshot guide and Puppeteer waitForSelector API.

4. Full-page capture or element capture?

Method Framing Best for Things to check
Playwright page.screenshot() Viewport by default; full document with fullPage: true. Giving an agent page context or preserving surrounding layout. Full-page capture can produce a tall image. Confirm the target is ready before capture.
Playwright locator.screenshot() Target element bounds. Sending a focused chart, card, or result region to an agent. It scrolls into view. Check overlays, clipping, and the element’s own scrolling.
Puppeteer page.screenshot() Viewport by default; supports full-page capture. Capturing the whole page. Wait for the intended state before invoking the screenshot.
Puppeteer element screenshot Target element bounds. A focused component capture. It attempts to scroll the element into view.

5. Make an agent’s capture reliable

  1. Use a meaningful selector. Prefer a stable ID, role, or accessible text grounded in the page structure. Avoid brittle selectors based on an element’s current position.
  2. Wait for the intended state. Use DOM attachment only if presence is enough; use visibility when it must render; use a page-specific signal when data completion matters.
  3. Set a finite timeout. A page can be slow or the target can be absent. Choose a limit appropriate to the workflow, not a universal value.
  4. Make timeout explicit. Report that the target did not become ready. Do not silently label a fallback screenshot as successful.
  5. Capture diagnostics when useful. On failure, save a screenshot or log the page URL and error so an agent can distinguish a selector issue from a page-load problem.
  6. Consider state changes between wait and capture. If the page is dynamic, recheck the target or readiness signal just before relying on the image. A successful wait cannot guarantee that the page remains unchanged.

6. Troubleshooting

Symptom Likely cause Fix
Wait times out; selector is never found. Wrong selector, navigation did not reach the expected page, or content is behind authentication or another flow. Inspect the final URL and DOM; confirm the selector on the loaded page; handle redirects or sign-in deliberately.
Element is attached but screenshot is blank or incomplete. DOM presence was treated as visual or application readiness. Wait for visible and, if needed, a page-specific ready state or completed data indicator.
Element is visible but still shows a spinner or partial results. Visibility does not mean application work is complete. Wait for the spinner to disappear or for a completion marker that belongs to the application.
Element screenshot is cropped unexpectedly. The screenshot is clipped to element bounds, an overlay covers part of it, or the element has internal scrolling. Use a page screenshot for context; inspect the element’s size, overlays, and scroll position; capture after bringing the desired content into view.
Page screenshot misses content below the fold. Only the viewport was captured. Enable full-page capture where appropriate. For lazy-loaded content, the page may need to scroll through content and wait for it to render before taking the full-page image.
Capture occasionally shows a different state than the wait observed. The application changed between the wait and screenshot. Recheck the target or readiness condition immediately before capture, and make the ready state stable if the page is under your control.
Browser closes before capture finishes. The browser lifecycle was not awaited or cleanup occurred too early. Await the screenshot and close the browser in a finally block after capture completes.

7. Performance, reliability, and cost

A selector-based wait avoids spending a fixed sleep on pages that become ready sooner, while still allowing slow pages up to the timeout. Keep the condition specific: waiting for a broad or unrelated selector can delay every capture or produce a misleading success. Full-page images and element images have different dimensions and downstream processing needs; choose the smallest framing that gives the agent enough context.

For repeated captures, reuse a browser process where your architecture permits, but isolate page state between jobs and always close resources when a job ends or fails. Treat navigation failures and selector timeouts as separate failure classes in logs. A timeout should not silently become a successful screenshot unless your workflow explicitly labels that image as a diagnostic artifact.

Browser automation has operational costs: browser runtime, memory, infrastructure, and maintenance of browser versions and selectors. The research dossier provides no benchmark or universal cost comparison, so measure your own page mix and concurrency. If this is a production screenshot workflow, track successful captures, target timeouts, navigation failures, and output size to identify where time and compute go.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. For example, this cURL request captures a URL as WebP; see the ScreenshotNeo API documentation for options and the response behavior:

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}`);

ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers say which page verdict applied and whether it was billed. Its MCP server gives AI agents tools for screenshots, page info, and PDF capture. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

9. FAQ

How do I wait for an element to load before taking a screenshot in Playwright?

Use a locator and await waitFor({ state: 'visible', timeout: ... }) before calling the page or locator screenshot method. If the element appears before its content is complete, also wait for the application’s completion signal.

What is the difference between attached and visible?

attached means the node exists in the DOM. visible means it has a non-empty bounding box and is not hidden with visibility:hidden. Neither state confirms that application data is complete.

How can I take a screenshot only after a specific selector appears?

Wait for that selector in the state you need, then call page.screenshot() for the page or the element’s screenshot method for a focused image.

Should an agent take a screenshot after a timeout?

Only if it labels the image as a diagnostic or fallback. If the target is required for a valid result, report that it did not become ready instead of presenting the capture as complete.

Keep reading