In Playwright, how does locator.dispatchEvent('click') differ from locator.click(), and when is it wrong?

## Two different machines Playwright gives you two ways to make a page think a click happened, and they run on completely different machinery. `locator.click()` drives the **input pipeline**. Playwright moves its virtual pointer to a point on the resolved element and sends the whole `mousemove`, `mousedown`, `mouseup`, `click` sequence at real coordinates. Hover styles fire on the way in. Whatever element is topmost at that point is what receives the press, so an overlay that covers the button intercepts the click exactly as it would for a user. The events carry a button, coordinates, and `isTrusted` set to `true`. `locator.dispatchEvent(type, eventInit?)` runs **inside the page**. Playwright constructs an event object of the given type, initialises it from `eventInit`, and calls `dispatchEvent` on the matched node. No pointer moves. No coordinates are involved. The element's visibility state is irrelevant -- the documented behaviour is that the event is dispatched regardless -- so a button underneath a modal receives its `click` event and its handler runs. ## What the dispatched event looks like The event Playwright builds is `composed`, `cancelable` and bubbling by default, so it propagates up the tree and a listener on an ancestor still sees it. The one thing it cannot be is trusted: an event created and dispatched from script has `isTrusted` set to `false`, and the browser will not perform the default user-activation-gated behaviours that a real click unlocks. | | `locator.click()` | `locator.dispatchEvent('click')` | |---|---|---| | pointer moves | yes | no | | coordinates | real, from the element box | none | | element under an overlay | the overlay is hit | the element is hit | | visibility matters | yes | no | | hover and pointer events on the way | fired | not fired | | `isTrusted` | `true` | `false` | | you can shape the event | only through the click options | freely, through `eventInit` | ## eventInit and live objects `eventInit` supplies the event-specific initialisation properties, and which ones are meaningful depends entirely on the type: `key` for a `KeyboardEvent`, `button` and `clientX` for a `MouseEvent`, `deltaY` for a `WheelEvent`, `dataTransfer` for a `DragEvent`. Plain values are serialised into the page, which is fine for numbers and strings but useless for a live browser object. For those you pass a handle instead. The canonical case is a drag event that has to carry a real `DataTransfer`: ```typescript const dataTransfer = await page.evaluateHandle(() => new DataTransfer()); await source.dispatchEvent('dragstart', { dataTransfer }); await target.dispatchEvent('drop', { dataTransfer }); ``` This is the shape of use that `dispatchEvent` is genuinely for: raising an event the pointer pipeline cannot construct on its own, with a payload only the page can create. ## Where it is the right tool, and where it is not Legitimate uses: - raising an event with a payload, such as the `dragstart`/`drop` pair above - exercising a handler for an event the browser will not generate on demand at all, such as a device orientation event - deliberately simulating a click "by any means possible" in a throwaway setup step whose purpose is to reach a state, not to test the click The trap is the fourth use, and it is the one interviewers are probing for: swapping `dispatchEvent('click')` in because `click()` failed. When a click on the issue tracker's "Resolve" button times out because a toast covers it, the failure **is the finding** -- a real user cannot reach that button either. Dispatching the event straight at the node turns a genuine product defect into a green test, and it removes the whole point of driving a real pointer. The right fixes are to wait for the toast to clear, dismiss it, or file the overlap as a bug. The second trap is subtler: because nothing hovers on the way in, a widget that only becomes interactive on `pointerenter` never gets set up, so a dispatched `click` can run against a half-initialised component and produce a passing test for behaviour that never happens in a browser. ## How to talk about it The compact answer is that `click()` asks the browser to click the element and `dispatchEvent()` tells the element that it was clicked. The first can be wrong about your intent because the page is genuinely in the way; the second is never wrong about your intent and, for exactly that reason, never tells you the page was in the way.