DEV Community

The Wise
The Wise

Posted on

Understanding page.locator().click() in Playwright

#javascript #automation #testing #tutorial

What is locator.click()?

In Playwright, locator.click() is a high-level API used to simulate a mouse click on a web element. It’s part of the Locator API, which provides a robust way to interact with elements on the page.

await page.getByRole('button').click();
Enter fullscreen mode Exit fullscreen mode

This command does the following:

Finds the element matching the selector.
Auto-Waiting Mechanism
Playwright automatically waits for the element to be:

  • Attached to the DOM
  • Visible (not hidden via CSS or layout)
  • Enabled (not disabled)
  • Stable (not animating or moving) This avoids flaky tests caused by premature clicks. Scrolls it into view if needed.
  • If the element is outside the viewport, Playwright scrolls it into view using element.scrollIntoViewIfNeeded(). This mimics how a real user would interact with off-screen elements. Performs a click action.

When you use the click() method , it does the following actions in sequence to mimic a real user clicking experience.

  • mousedown —> Like when the mouse is pressed, the button goes down
  • mouseup —> Like when the mouse is stopped pressing, the button comes up
  • click —> click is needed though the down and up is triggered otherwise the click won’t be triggered

Options You Can Pass to the click function 

await page.locator('button').click({
  position: { x: 10, y: 5 }, // click at specific offset
  button: 'right', // 'left' | 'middle' | 'right'
  clickCount: 2,   // for double-click
  delay: 100,      // ms between mousedown and mouseup
  force: true,     // bypass checks
  modifiers: ['Alt', 'Shift'], // keyboard modifiers
  noWaitAfter: true// doesnt wait for navigation if click opens new page/elements
  timeout: 5000,   // override default timeout
  trial: true
});
Enter fullscreen mode Exit fullscreen mode

2.1 position

  • Playwright calculates the clickable point:

  • It finds the center of the visible bounding box.

  • If position is specified, it uses that offset.

  • It ensures the point is not obscured by another element.

await locator.click({ position: { x: 10, y: 5 } });
Enter fullscreen mode Exit fullscreen mode

2.2 Right click/Left click / Middle click

  • When right click is needed on a element, this will do the trick. 
await page.locator('canvas').click({ button: 'right' }); // Right-click

await page.locator('canvas').click({ button: 'middle' }); // Middle-click
Enter fullscreen mode Exit fullscreen mode

2.3 Double click or more

  • Sometimes double click will trigger an event, this option can be used in that scenario. 
await page.locator('text="Open File"').click({ clickCount: 2 });
Enter fullscreen mode Exit fullscreen mode

2.4 Delay

  • it's used to introduce a pause between the mousedown and mouseup events discussed in 1.4 
await page.locator('button').click({ delay: 500 }); // 500ms delay
Enter fullscreen mode Exit fullscreen mode

2.5 force

  • this option is used to bypass all actionability checks and force the click, even if the element is:

  • Not visible

  • Not attached to the DOM

  • Covered by another element

  • Disabled

  • Outside the viewport

await page.locator('#hidden-button').click({ force: true });
Enter fullscreen mode Exit fullscreen mode

Sometimes, elements are technically present but:

  • Hidden by overlays or modals

  • Slightly off-screen

  • Temporarily disabled due to animations or transitions

  • Using force: true allows you to click them anyway.

Be cautious about this - it skips safety checks.

2.6 Shift+click

lets you simulate keyboard modifier keys being held down during the click — like Shift, Ctrl, Alt, or Meta (Cmd on Mac). 

await page.locator('.item').click({ modifiers: ['Shift'] }); 
//"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift”
Enter fullscreen mode Exit fullscreen mode

2.7 NowaitAfter
This is used to prevent Playwright from waiting for potential page navigations or asynchronous events that might be triggered by the click.

# and defaults to false
await page.locator('a#delayed-link').click({ noWaitAfter: true });
# will default to true in future releases
Enter fullscreen mode Exit fullscreen mode

2.8 timeout

  • it controls How Long Playwright Waits for actionability checks

  • If you don’t specify timeout, Playwright uses the default timeout (usually 30 seconds).

  • When a element takes time to load and you want to extend or limit the timeout different from gloabl timeout then this can be used.

await locator.click({ timeout: 5000 }); // custom timeout
Enter fullscreen mode Exit fullscreen mode

2.9 Trial Click
You can simulate a click without actually clicking using trial: true. This is useful for checking if an element is clickable.

await locator.click({ trial: true });
Enter fullscreen mode Exit fullscreen mode

Common Pitfalls

Some common failures and the causes
Playwright throws a detailed error with suggestions and a trace.

Conclusion

page.locator().click() is one of the most powerful and reliable ways to simulate user interaction in Playwright. By understanding its behavior, options, and best practices, you can write stable, maintainable, and robust automation scripts.

Top comments (0)