feat(locator): show how many candidates each filter step left

Merged
DE
13d ago
+374-24

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.ts gains filterSpine(expression): the prefixes of a filtered chain, innermost first, following filter and index steps down their source. It returns undefined when no filter sits on the spine, which is what keeps plain queries and or() roots out of the message.
  • packages/e2e/src/locator/engine.ts builds the lines where the two failures are raised. The not-found path in resolveCounted and the ambiguity path both call candidateCounts, which resolves each prefix once through resolveNow on 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-level assertSingle became the async singleOf method, so both sites share one ambiguity error.
  • packages/e2e/tests/unit/expression.test.ts covers 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.ts adds 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 on LOCATOR_NOT_FOUND and LOCATOR_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: the LOCATOR_NOT_FOUND and LOCATOR_AMBIGUOUS entries 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/e2e fails the same 22 files on this branch as on the commit the branch was cut from, checked by diffing the failing-file sets of two tests/unit runs:
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 --noEmit in packages/e2e is clean, which includes the tests/types/sdk-types.ts assertions. oxlint reports 0 warnings and 0 errors on the four touched files.
  • node scripts/check-error-codes.ts reports 87 codes in source, all documented, with the two updated entries in the set. node scripts/check-peer-ranges.ts passes, and node scripts/check-changeset-bumps.ts reports 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 in spec.yml on 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/**/*.mdx page for the behavior, and skills/e2e/ if the skill describes it.
  • Contract change: emitted .d.ts reviewed, tests/types/sdk-types.ts updated; wire change edits the schema and both fixtures.
  • Engine contract change (e2e/engine): changesets for e2e, @e2e-dev/web, and @e2e-dev/mobile.