Do Not Fix a Browser Agent's Ambiguous Click with first()

A browser agent sees two Edit buttons. Its first attempt fails because the locator is ambiguous. The agent adds first(), the click succeeds, and the run is marked repaired.

But which record did it open?

Removing an exception is not the same as establishing the user's intended target. For browser automation that edits records, prepares messages or operates an administration panel, identity deserves its own check before an action.

Methodology and scope

We reviewed Playwright's locator guide, Locator API and assertion documentation on October 8, 2026. This is a proposed workflow for developers building browser skills and reviewing generated automation. We did not run it against a customer system.

The example uses fictional customer records. Its selection criterion is whether the locator identifies the requested business object, not whether a page has finished loading. Our table readiness guide covers that different problem.

Treat ambiguity as information

Playwright applies strictness to operations that imply a single target: multiple matches can raise an exception. It permits opting out with positional methods such as first, last and nth, but warns that page changes can cause them to choose an unintended element. The guide also explains that locators resolve an up-to-date DOM element for each action. Playwright locators.

Our interpretation for an agent workflow is straightforward: an ambiguity error is evidence that the current targeting rule is incomplete. Do not discard that evidence just because selecting an arbitrary match produces a successful click.

Position is appropriate when position is actually the user's selection rule, such as inspecting the first visible result under an agreed sort. It is weak evidence for a named customer, invoice or document.

Separate object identity from action identity

Consider a fictional customer table with two rows named Alex Chen. Each row has an Edit button. The user requested a change to customer C-104 in the Europe workspace.

The button label describes the action. The customer reference and workspace identify the object. Neither a global Edit locator nor an exact match on Alex Chen establishes all three.

Our recommended sequence is to confirm the workspace, find the container associated with C-104, inspect the displayed identity, and then resolve Edit within that container. Use the actual row, record link or stable identifier exposed by the application. Do not invent a test ID simply because it would make the code convenient.

When the interface exposes only duplicate names, ask for clarification or navigate through an authorized record-specific route. A guessed relationship between name and row order should not become permission to edit.

Use a zero, one, many decision

Before acting, define how each observed match count changes the workflow:

One is necessary for many actions, but it is not sufficient. A locator can uniquely match the wrong row.

Keep an identity note with the action proposal: workspace, requested reference, observed reference, scoped action and expected destination. This need not include customer data in public logs. The purpose is to make a disputed action explainable without recording an entire sensitive page.

Wait for the right condition, then check the effect

Playwright's auto-retrying assertions include toHaveCount, toHaveText and URL assertions. They are asynchronous and must be awaited; they keep checking until the condition passes or the assertion times out. Playwright assertions.

For our fictional workflow, an assertion that the scoped record count equals one is a useful precondition. It does not lock the application against changes between observation and action. Keep the object-specific targeting rule for the action itself.

After opening the editor, verify the record reference and workspace again before proposing a modification. A generic page heading such as Edit customer is not the expected object identity.

After an authorized save, inspect the intended record's resulting state. Do not infer success solely from a toast that could belong to another background operation. If the result is uncertain, preserve that uncertainty instead of repeating a potentially consequential action automatically.

Handle alternative interface states explicitly

The Locator API's or() creates a locator matching either or both alternatives. If both appear, the combined locator can have multiple matches. Its documented example uses first for a visibility wait, then checks which state is present before acting. Playwright Locator API.

That is not a blanket instruction to click the first of two competing actions. Our recommendation is to separate observation from execution.

For example, an editor and an account-warning dialog may both be visible. Decide how the warning affects the authorized task. Do not let DOM order choose whether the agent dismisses the warning, edits a record or submits a form.

Proposed rehearsal and limitations

Use non-sensitive fixtures to rehearse duplicate names, reordered rows, a removed target, a re-rendered record and two simultaneously visible dialogs. Define the expected stop or continuation for each before execution. We have not run these checks for any listed skill.

Identity checks add implementation work. Interfaces without stable identifiers may not support reliable unattended actions. In those cases, an explicit clarification is a valid result, not an automation failure to conceal.

This approach also does not replace authorization. Identifying the correct invoice does not authorize sending it; identifying the correct user does not authorize changing their permissions.

When evaluating a candidate in the skills directory, ask it to explain both sides of the action: why this object, and why this operation. A repaired locator should make that explanation stronger, not merely make the exception disappear.