Puppeteer ActionOptions: Configure Locator Actions

Puppeteer’s ActionOptions interface documents one option: signal, an optional AbortSignal used to abort a locator action. It is a cancellation control; the locator’s setTimeout() method is a separate control for limiting how long locator actions can take. Neither replaces locator readiness checks.

The examples below use the Puppeteer API documented in the supplied research: the ActionOptions reference is version 25.9.0, while the locator guide and Page.locator() reference are version 25.12.0. Check the documentation for the version installed in your project before relying on version-specific behavior.

What ActionOptions configures

The official ActionOptions API reference lists an optional signal property, typed as AbortSignal, and describes it as a signal to abort the locator action. The interface does not document a broad collection of action settings. In particular, its signal should not be confused with a timeout.

Locators are Puppeteer’s recommended route for interacting with page elements. They automatically wait for an element to be present and in an appropriate state for an action. For a click, the locator guide describes checks that include being in the viewport, visible, enabled, and having a stable bounding box. Read the guidance for the specific action: do not assume every locator action uses precisely the same checks.

Cancel an action with AbortSignal

Create an AbortController, pass its signal in the action options, and call abort() when your program decides the action should be canceled. This runnable example starts a click and aborts it after a delay. The application should handle the rejection according to its own cancellation policy.

import puppeteer from 'puppeteer';

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

  const controller = new AbortController();
  const clickPromise = page.locator('a').click({ signal: controller.signal });

  // Example cancellation trigger. Replace with your own shutdown or user action.
  const cancelTimer = setTimeout(() => controller.abort(), 1000);
  try {
    await clickPromise;
    console.log('Click completed');
  } catch (error) {
    console.error('Locator action did not complete:', error);
  } finally {
    clearTimeout(cancelTimer);
  }
} finally {
  await browser.close();
}

The abort signal expresses cancellation. The reviewed API reference does not specify detailed cancellation timing, rollback behavior, or whether page-side effects can be undone. Do not treat aborting an action as a transaction rollback; design your application to tolerate an action that may already have affected the page.

Set a locator action timeout

Use Locator.setTimeout(timeout) when you want a locator-specific total time limit for its actions. It returns a cloned locator with the configured timeout. The default is the page’s Page.getDefaultTimeout(); passing 0 disables the timeout. The locator guide shows this pattern:

import puppeteer from 'puppeteer';

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

  const link = page.locator('a').setTimeout(3000);
  await link.click();
} finally {
  await browser.close();
}

The 3000 millisecond value is an example, not a universal recommendation. Choose a limit that fits the page and action, and handle timeout failures where your workflow needs recovery.

Cancellation, timeout, and readiness compared

Control	Purpose	Scope
`ActionOptions.signal`	Request cancellation of a locator action	The action receiving the signal
`Locator.setTimeout(timeout)`	Set the total time limit for locator actions	The cloned locator and its actions
Locator preconditions	Wait until the element is in a state suitable for an action	Depends on the action and its documented checks

Use an abort signal when an external event—such as application shutdown—means the action should stop. Use a timeout when the action must not keep waiting beyond a defined duration. Use locator readiness behavior to coordinate with the page. These controls address different concerns and can be useful together.

Choose and tune a locator

Page.locator() accepts a selector or a function. The API reference documents CSS selectors and Puppeteer-specific selector syntax. For example, this selects a link using CSS:

const link = page.locator('a[href="/next"]');
await link.click();

For a click, the locator guide shows how to configure certain preconditions. For example, you can change whether viewport or visibility checks are required:

await page
  .locator('button.submit')
  .setVisibility(null)
  .click();

Use such configuration only when it matches the page and action you intend. Bypassing a readiness check may let an action proceed in a state that would otherwise have caused Puppeteer to wait. Consult the guide for the particular action and the available locator methods.

If you need lower-level waiting, Puppeteer also documents waitForSelector. The guide describes it as a lower-level alternative and notes that it does not automatically retry the action if that action fails. Prefer a locator when its waiting and interaction behavior fits your task.

Troubleshooting

Symptom	Likely cause	What to do
The action is canceled or rejects after cancellation	The signal was aborted, or application cancellation handling received a rejection.	Check who owns the controller and when `abort()` is called. Handle cancellation at the call site; do not assume the page was rolled back.
The action exceeds its time limit	The locator’s configured timeout or page default was reached while the action waited or ran.	Check that the selector matches the intended element and that the page reaches the expected state. Adjust the locator timeout or page default only if the workflow needs more time.
The element exists but the click does not proceed	The locator may still be waiting for action-specific readiness checks, such as visibility or stable geometry for a click.	Inspect the element and the action’s documented preconditions. Change a check only when bypassing it is appropriate.
A manual wait succeeds but the following action fails	A lower-level wait such as `waitForSelector` does not automatically retry the action that follows.	Use a locator for interaction where possible, or implement explicit recovery around the lower-level action.
A selector never finds the intended element	The selector may not match the page structure or may use syntax that is not valid for the chosen selector form.	Verify the selector against the loaded page and consult the `Page.locator()` reference for supported selector forms.

Performance, reliability, and cost

Locator readiness checks can prevent acting on an element before it is suitable for the operation, but a timeout does not make a slow or unstable page faster. Keep selectors specific, set time limits that reflect the workflow, and make cancellation and error handling explicit. The reviewed Puppeteer references provide no benchmark or cost figures for these controls, so performance and runtime cost depend on the page, browser workload, and application.

For reliability, avoid disabling a readiness check just to make a flaky action pass. First determine whether the selector is correct and whether the page state is expected. If using a signal, ensure its controller is not aborted prematurely and handle rejection in the surrounding workflow.

Or skip the browser setup

If your goal is to capture a page rather than automate an interaction, ScreenshotNeo provides a website screenshot API. One GET request returns an image or PDF; this example saves the response body as a WebP file. See the ScreenshotNeo API documentation for request options.

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

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)

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}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for the free plan and get 1,000 screenshots a month with no card.

FAQ

Does ActionOptions include a timeout property?

The reviewed ActionOptions reference lists only the optional signal property. Locator time limits are configured separately with setTimeout().

Does aborting a locator action undo its page effects?

The reviewed reference does not promise rollback or specify the state of page-side effects after cancellation. Treat cancellation as a request to abort the action and handle the resulting state in your application.

Can I disable the locator timeout?

Yes. The documented setTimeout(0) setting disables the locator timeout. Use it only when an unbounded wait is acceptable for your workflow.

Should I use waitForSelector or a locator?

Use a locator for interaction when its built-in waiting suits the action. The guide presents waitForSelector as a lower-level option that does not automatically retry a failed action.