feat(locator): show how many candidates each filter step left
What and why
A filtered locator fails with one line that names the whole expression, and that is all it says. With a chain like the one below, LOCATOR_NOT_FOUND can mean any of three things: there are no list items yet, the text is spelled differently, or the button is named differently. Working out which step emptied the candidate set means reading the tree by hand, or rewriting the locator one step at a time and rerunning. LOCATOR_AMBIGUOUS only says how many nodes the whole chain matched, so the step that failed to narrow stays anonymous there too.
screen.getByRole('listitem')
.filter({ hasText: 'Order 1042' })
.filter({ has: screen.getByRole('button', 'Cancel order') });
For a filtered locator, the two failures now carry the count each step left, in the error message itself:
locator matched no nodes within getByRole("listitem").filter({ hasText: "Order 1042" }).filter({ has: getByRole("button", name: "Cancel order") }); candidates left after each filter step, counted after the failure:
getByRole("listitem"): 6
getByRole("listitem").filter({ hasText: "Order 1042" }): 1
getByRole("listitem").filter({ hasText: "Order 1042" }).filter({ has: getByRole("button", name: "Cancel order") }): 0
The counts are read after the failure, one immediate resolve per prefix on a short fresh deadline, and the message says so, because a page that changes between the failing attempt and the diagnostic pass can disagree with it. The step labels reuse the existing expression rendering, so nothing new learns to describe a locator, and the text goes through the run's redaction at record time like any error message.
A few boundaries keep the message quiet when the lines would say nothing. A locator with no filter step, an index-only chain, and a union root keep today's message. If the diagnostic pass cannot read, the failure stands without the lines, since a diagnostic must not fail the failure. LOCATOR_AMBIGUOUS keeps its matches detail and gains the same lines.
No new API and no wire change. The counts live in the message text, report-v1 bounds the message through serializeError as before, and error codes, exit codes, and the public type surface are unchanged. CONTRIBUTING.md's stability policy does not cover the exact text of error messages.
What changed
packages/e2e/src/locator/expression.tsgainsfilterSpine(expression): the prefixes of a filtered chain, innermost first, followingfilterandindexsteps down theirsource. It returns undefined when no filter sits on the spine, which is what keeps plain queries andor()roots out of the message.packages/e2e/src/locator/engine.tsbuilds the lines where the two failures are raised. The not-found path inresolveCountedand the ambiguity path both callcandidateCounts, which resolves each prefix once throughresolveNowon a fresh 500 ms deadline capped by the attempt budget, and returns undefined when any resolve throws, so the message stays as it is today. The old module-levelassertSinglebecame the asyncsingleOfmethod, so both sites share one ambiguity error.packages/e2e/tests/unit/expression.test.tscovers the spine: the prefixes in order, an index step between filters, the no-filter cases, and a union root.packages/e2e/tests/unit/locator-engine.test.tsadds a fake session that answers per expression, keyed by the rendered locator, so the tests pin exactly which expressions a failure path resolves and in which order. They cover the per-step lines onLOCATOR_NOT_FOUNDandLOCATOR_AMBIGUOUS, a locator with no filter step left alone, the plain failure kept when the walk cannot read, and an index step between filters counted under its own label.docs/reference/errors.mdx: theLOCATOR_NOT_FOUNDandLOCATOR_AMBIGUOUSentries name the per-step listing.- A patch changeset for
e2e, since the locator engine ships in the published package.
Issue
Fixes #1293
Verified
Ran it locally: yes
- The tests were written first and run against the unmodified engine. The 9 new tests failed on exactly the missing feature, and after the change the two touched files pass in full.
before: 9 failed | 79 passed (88)
after: 88 passed (88) tests/unit/expression.test.ts + tests/unit/locator-engine.test.ts
- The unit suite of
packages/e2efails the same 22 files on this branch as on the commit the branch was cut from, checked by diffing the failing-file sets of twotests/unitruns:
branch: Tests 61 failed | 2973 passed | 34 skipped (3068)
main: the same 22 failing files, none added, none gone
Those failures are this machine's Windows baseline, CRLF checkouts, symlink privilege, and path separators, and they are identical on both sides. The locator-adjacent files all pass: expression, locator-engine, resolve-expression, locate, locator-action-options, locator-basics, locator-union, and locator-wait-for, 296 tests together.
tsc --noEmitinpackages/e2eis clean, which includes thetests/types/sdk-types.tsassertions.oxlintreports 0 warnings and 0 errors on the four touched files.node scripts/check-error-codes.tsreports 87 codes in source, all documented, with the two updated entries in the set.node scripts/check-peer-ranges.tspasses, andnode scripts/check-changeset-bumps.tsreports the new changeset in the pending set with no unannounced 0.x minor or major.- Integration tests did not run on this machine: their fixtures import the runner from
dist, which needs a full rebuild this box has not done. They run inspec.ymlon every pull request.
Checklist
- Changeset added (
pnpm changeset) for any change to a published package, or the change is testbed, docs, or CI only. - Breaking change: title carries
!, the changeset body names what breaks and what replaces it, and the deprecation warning landed a window earlier (stability policy in CONTRIBUTING.md). - Docs updated in the same PR: the
docs/**/*.mdxpage for the behavior, andskills/e2e/if the skill describes it. - Contract change: emitted
.d.tsreviewed,tests/types/sdk-types.tsupdated; wire change edits the schema and both fixtures. - Engine contract change (
e2e/engine): changesets fore2e,@e2e-dev/web, and@e2e-dev/mobile.