skip to content

What does Playwright's locator.click({ trial: true }) actually do?

level: middleimportance: nice to knowfreq 28%

answer

  1. The checks run, the action does not
  2. Readiness without the side effect
  3. It still times out the same way
  4. Modifiers are pressed regardless
  5. A rehearsal, not a state assertion

basics

~20 s

A trial run performs the actionability checks and then stops. Playwright waits for the element to be visible, stable, hit-testable and enabled, and never dispatches the click, so it verifies readiness without changing the page.

solid answer

~40 s

`trial: true` performs the action's actionability checks and skips the action itself. For a click, Playwright waits for the element to be visible, stable, receiving events at the click point and enabled, then returns without dispatching anything -- and it still throws a timeout error, with the same call log, if a check never passes. It is the precise way to ask "could a user do this right now?" without the side effect: a trial click on Close issue proves the button is operable without closing the issue. One documented wrinkle is that keyboard modifiers passed alongside are still pressed during the trial, so elements that only appear while a key is held can be rehearsed. Reach for it when reachability, rather than text or state, is what you actually mean to assert.

code

typescript · 6 lines
typescript
import { test } from '@playwright/test';

test('a reviewer can reach Close issue without closing it', async ({ page }) => {
  const close = page.getByRole('button', { name: 'Close issue' });
  await close.click({ trial: true, timeout: 4_000 });
});

go deeper

for a junior

Remember that trial true asks Playwright whether the action could run, then stops before running it, so nothing on the page changes.

for a middle

Explain that the checks are identical to the real action's, that the timeout and call log behave the same, and that only the final dispatch is dropped.

for a senior

Use it where a test must prove a control is reachable without committing the side effect, and recognise it as a readiness probe rather than a substitute for asserting what the app shows.

for a principal

Judge whether a suite needs an explicit reachability probe at all, and keep it from hardening into a ritual line before actions that would have gated themselves anyway.

## What a trial run does `trial: true` is an option on Playwright's action calls that says: run this action's actionability checks, and then stop. For `locator.click()` that means the runner waits for the element to be visible, stable, receiving events at the computed point, and enabled, retrying exactly as it normally would -- and then returns without dispatching anything. The page is untouched. Two consequences follow immediately: - A trial call **can fail**. If a check never passes, it throws the same `TimeoutError`, with the same call log naming the same condition. It is a rehearsal, not a boolean probe. - A trial call costs the same time as a real one in the bad case, and almost nothing in the good case, because the checks pass on the first attempt when the page is ready. ## What it is for - Proving a control is reachable without triggering its effect: a trial click on Close issue confirms the button is operable without closing the issue. - Asserting that a destructive or expensive action is available at this point in a flow, in a test whose subject is something else. - Catching a covering layer that state assertions cannot see, because the hit test is part of the gate the trial runs. - Documenting an expectation at the exact place a reader looks for it -- immediately before the interaction it guards. ## How it differs from asserting visibility | | `locator.click({ trial: true })` | asserting the element is visible | |---|---|---| | Layout box | required | required | | Not moving | required | not considered | | Owns its click point | required | not considered | | Not disabled | required | not considered | | Side effect | none | none | | Failure message | the call log names the failed check | the matcher reports what it saw | The row that earns the option its place is the hit test. A banner painted over a button leaves it perfectly visible, and only something that hit-tests the point will notice. ## The modifier wrinkle Playwright documents one deliberate exception to "nothing happens": keyboard modifiers passed alongside a trial are still pressed for the duration of the checks. That exists so you can rehearse an interaction on an element that only appears while a key is held -- a multi-select on a board, for instance -- and it means a trial is not always completely free of observable effect on the page. ## What a trial does not tell you - It does not tell you the interaction would **work**: the checks say a user could start it, not that the handler behind it does the right thing. - It does not tell you the element is the **right** one. A trial against a stale issue card passes exactly as a real click against that card would. - It leaves no record that anything was verified, so if the expectation matters to a reader, put it in the test name or a comment beside the call. - It does not replace a state assertion. Reachability and correctness are separate claims, and most tests need both. ## Where it fits in a suite 1. Use it when the thing you mean to assert is **reachability**, not content or state. If you want to know what the page says, assert on what the page says. 2. Do not sprinkle it before every action. A real click already runs the same gate, so a trial immediately followed by the real call mostly doubles the work; it earns its place when the real action is one you do not want to perform. 3. Do not combine it with `force: true`. Force removes the checks and trial removes the action, so together they verify nothing and do nothing. 4. Give it its own timeout when you use it as a probe, so a failure reports quickly instead of consuming the whole test budget. Treated that way, `trial: true` is the precise expression of a question tests otherwise ask clumsily: could a user do this right now, without me doing it to find out?

  • How does a trial click differ from asserting that the button is visible?
    Visibility is one of four conditions. A trial click additionally waits for the element to stop moving, to be enabled, and to genuinely own the point a click would land on -- so it catches a banner painted over the button, which a visibility assertion passes without complaint.
  • Does a trial run still respect the action's timeout?
    Yes. The checks retry on the same clock, and if one never passes the call throws the usual timeout error with a call log naming the failed check. The only difference from a real call is that nothing is dispatched once the checks pass.

saying these in an interview costs you the question

  • Thinks a trial performs a silent click anyway
  • Believes trial skips the checks the way force does
  • Assumes a trial can never fail or throw
  • Uses trial where a state assertion is meant
  • Thinks trial and force combine usefully