[DavertMik]

When a locator matches nothing, ElementNotFound now adds hints about what the page has instead:

Field "#emial" was not found by text|CSS|XPath
  similar on page: #email, #email-label, #email-wrapper

Clickable element "#first-link" was not found by text|CSS|XPath
  found 1 match inside iframe [name="content"], use within({ frame: '[name="content"]' })

Hints cover:

• a match inside a same-origin iframe, with the within({ frame }) call to use
• matching elements excluded by the current within() context, or hidden ones
• up to 3 similar ids, classes or element names (fuse.js)

Design

All the logic lives in lib/helper/errors/ElementNotFound.js:

• ElementNotFound becomes an Error subclass.
• When it's created, it runs one in-page script through the active web helper's executeScript (found via the container), capped at 500 ms.
• It appends the hints to its own message and stack, about 10 ms after the throw, while the page is still open.
• err.explain() returns that pending work for callers that need to wait. MCP run_code awaits it (one line in bin/mcp-server.js).
• Errors from the page script, a closed page, or no web helper mean no hints. The original error is never masked.

No helper, hook, recorder, step or CLI changes. It works as-is for Playwright, Puppeteer, WebDriver and CDPBrowser (and Lightpanda, Obscura, Kitesurf, Moli, Appium through inheritance).

Not named fetchDetails, on purpose: the CLI awaits fetchDetails() after mocha's end, and nothing waits for that work to finish. With it, the whole failure report was lost under run-workers. The same race already affects MultipleElementsFound on 4.x: its failure details don't print, even in a single-process run. That's left for a separate fix.

Limitations

• Cross-origin iframes are not scanned.
• The first line of the error is unchanged. The hints are extra lines below it.

Tested locally

• test/unit/helper/element_not_found_test.js: 9 passing (message format, hints from page info, page script failure, unanswered page).
• #explainNotFound in the shared test/helper/webapi.js: Playwright 4/4, Puppeteer 4/4, CDPBrowser (Chrome) 4/4. Plus one Playwright hidden-match test with visibleLocator.
• A real codecept run and run-workers 2 both print the hint once, with a clean stack.
• Full unit suite: 950 passing. npm run def and eslint pass.
• WebDriver and the wider helper suites: CI. The local regression greps were stopped by a low-memory condition before they finished, so they have no result.

🤖 Generated with Claude Code