Puppeteer ActionResult: Understand Locator Action Results

What does Puppeteer’s ActionResult mean? It is a TypeScript union type with three string-literal members: 'continue', 'abort', and 'respond'. It is not the value returned by Locator.click() or another locator action. Those methods return Promise<void>. Puppeteer also has a separate LocatorEvent.Action event, emitted before a locator performs an action.

Keeping the type, action methods, and event distinct clears up the common confusion behind “Puppeteer locator action results.” This guide shows how to use locator actions, observe the event, handle retries and timeouts, and troubleshoot common failures.

1. The three meanings to keep separate

Name	What it is	What to expect
ActionResult	A documented TypeScript union type	'continue' | 'abort' | 'respond'. The reference lists the members but does not define their consumer-specific semantics.
Locator action methods	Methods such as click, fill, hover, and scroll	click, fill, and hover return Promise<void>; successful completion is not a status string.
LocatorEvent.Action	An event emitted before a locator performs an action	It can be used for logging or debugging. It may fire multiple times if the locator retries.

The official ActionResult API reference displays Puppeteer version 25.1.0. The interactions guide and locator event references display version 25.12.0, so consult the documentation for your installed version if behavior differs.

2. Use locator actions for page interactions

Puppeteer’s current page-interactions guide says: “Locators is the recommended way to select an element and interact with it.” A locator finds an element and performs an action while checking whether the target is ready. If the action fails because the target is not ready, Puppeteer retries the whole operation.

Here is a runnable Node.js example using Puppeteer. It opens a page, fills a form field, clicks a button, and waits for a resulting element.

const puppeteer = require('puppeteer');

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

    // Replace these selectors with elements on the page you automate.
    await page.locator('input[name="email"]').fill('dev@example.com');
    await page.locator('button[type="submit"]').click();
    await page.locator('[data-result="success"]').wait();

    console.log('The locator actions completed.');
  } finally {
    await browser.close();
  }
})().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

The example’s selectors are illustrative; example.com does not provide that form. For a real task, use a page and selectors that match your application. See the official page-interactions guide and Locator API reference.

3. What readiness checks do locator actions make?

Readiness checks vary by action. Do not assume every locator method applies the same checks.

Action	Documented checks	Details
click, fill	In viewport, visible, enabled, stable bounding box	Stability means the bounding box remains stable across two consecutive animation frames.
hover, scroll	In viewport, visible, stable bounding box	The guide does not list enabled status for these checks.

fill chooses a suitable method based on the target. Documented targets include contenteditable elements, selects, textareas, and inputs. Checkboxes, radio buttons, and switches use a boolean value.

When a target is missing or its required preconditions are not met before the timeout, Puppeteer throws a TimeoutError. A locator action is a promise: await it to ensure the action finishes before continuing.

4. Configure locator timeouts and checks

Locators inherit the page timeout by default. You can set a timeout for an individual locator and configure checks through the locator API. For example, where an application deliberately animates a target, the stable-bounding-box check may need adjustment. Change checks only when you understand why the target is safe to interact with under the altered conditions.

// Example configuration pattern; use options supported by your Puppeteer version.
const locator = page.locator('#save').setTimeout(10_000);
await locator.click();

The Locator API also documents configuration methods including setVisibility, viewport and enabled checks, and stable-bounding-box behavior. Consult the installed-version reference for the precise method signatures and defaults. Disabling a check can make an action run against an obscured, moving, or otherwise unsuitable element, so prefer fixing the page state or selector first.

Locator actions accept an optional AbortSignal through action options. This lets a caller cancel an action. It is a separate API feature: the documentation does not establish a direct mapping between aborting through a signal and the 'abort' member of the ActionResult union.

5. Observe the Locator Action event

LocatorEvent.Action signals that locator preconditions have been met and the locator is about to perform its action. This is useful for diagnostic logging. Because retries can cause the event to fire more than once, it is not a reliable one-event-per-request completion record.

const locator = page.locator('button[type="submit"]);

locator.on('action', () => {
  console.log('Puppeteer is about to perform the locator action.');
});

await locator.click();

The event reference names the event Action with value "action". Check the LocatorEvent reference for the version you use.

6. Locator actions compared with lower-level APIs

waitForSelector can wait until an element is available in the DOM, but it does not automatically retry a later action if that action fails. It also returns a handle that you must dispose of when finished. Page-level methods such as page.click, page.type, and page.hover remain available for backward compatibility and use waitForSelector.

Use a locator when its action and readiness behavior meet your needs. Reach for a lower-level API when a needed feature is not available through Locator, and explicitly manage waiting, retries, and handle cleanup.

7. Troubleshooting

Symptom	Likely cause	What to do
TimeoutError while locating or acting	The selector did not match, the element never became ready, or the timeout was too short.	Verify the selector against the loaded page, wait for the relevant navigation or state, and set an appropriate page or locator timeout.
Click or fill keeps retrying	The target is not meeting that action’s readiness checks, or page changes keep moving it.	Inspect visibility, enabled state, viewport placement, and layout stability. Prefer a stable selector and wait for the page state that stops the movement.
Action event logged more than once	The locator retried the operation.	Treat each event as an attempt about to act, not as a final result. Log completion or failure around the awaited method separately.
Code expects a click result string	Locator.click() was mistaken for the ActionResult type.	Await the click for completion; handle thrown errors for failure. The method is documented to return Promise<void>.
Confusion between abort signal and 'abort'	Two similarly named concepts were assumed to be connected.	Use the action option’s AbortSignal according to its API reference. Do not infer that it returns the union member.
Element handle remains allocated after a selector wait	A lower-level waitForSelector result was not disposed.	Dispose the handle when done, or use a locator if it covers the interaction you need.

8. Performance, reliability, and cost

• Retries improve resilience but take time. A locator can wait and retry while the element becomes ready. Choose timeouts that fit the application’s expected behavior; very long timeouts can hide a broken selector or stalled page.
• Prefer stable selectors and explicit page-state waits. This reduces repeated unsuccessful attempts and makes automation easier to diagnose.
• Instrument attempts and outcomes separately. The Action event may repeat. Record the awaited action’s completion or caught error if you need one final outcome per operation.
• Browser automation has runtime costs. Keep browser and page lifetimes scoped to the work, and close the browser in a finally block as in the example so failures do not leave it running.
• No published performance statistic is established here. Locator checks and retries trade waiting for reliability; measure your own workflow if latency is a requirement.

9. Or skip the browser setup

If your task is to capture a page rather than interact with it, ScreenshotNeo provides a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It handles cookie and consent banners, newsletter popups, and chat widgets before the capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

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(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await require('node:fs/promises').writeFile('shot.webp', bytes);

See the ScreenshotNeo API documentation for request options. Learn more about ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.

10. FAQ

Does ActionResult tell me whether a locator click succeeded?

No. The documented type is a three-member union, while locator click is an action method returning Promise<void>. Await it and handle errors.

Can the Action event fire after a retry?

Yes. The event may fire each time the locator is about to act, including on retries.

Are all locator actions gated by the same checks?

No. The documented check lists differ by action. In particular, enabled status is listed for click and fill, but not for hover and scroll.

Does 'abort' mean the same thing as an aborted locator action?

The references establish the union member and separately document an optional AbortSignal; they do not define a direct relationship between them.