Skip to content

Commit 19db0e2

Browse files
DavertMikclaude
andcommitted
feat(playwright): explain element not found errors
Add explainNotFound option (default true). When a step fails with ElementNotFound, the error gets hints: a match inside an iframe, matches outside the current within(), hidden-only matches with visibleLocator, and up to 3 similar elements ranked by ARIA names or CSS ids/classes. Bounded at 300 ms and runs only after a failed lookup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 352466d commit 19db0e2

6 files changed

Lines changed: 241 additions & 52 deletions

File tree

‎docs/playwright.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,22 @@ await within('.todoapp', () => {
219219
I.see('0 items left', '.todo-count')
220220
```
221221

222+
### Element Not Found Hints
223+
224+
When a step fails because an element was not found, Playwright helper adds hints about what the page has instead: a match inside an iframe, matches outside the current `within` block, hidden matches when `visibleLocator` is on, and up to 3 similar elements.
225+
226+
```
227+
Field "#emial" was not found by text|CSS|XPath
228+
similar ids: #email, #email-label, #email-wrapper
229+
```
230+
231+
```
232+
Clickable element "#first-link" was not found by text|CSS|XPath
233+
found 1 match inside iframe "content" — use within({ frame: 'iframe[name="content"]' })
234+
```
235+
236+
Hints are collected only after a lookup has failed and take at most 300 ms. The first line of the error doesn't change. Disable them with `explainNotFound: false` in the helper config.
237+
222238
### Each Element <Badge text="Since 3.3" type="warning"/>
223239

224240
Usually, CodeceptJS performs an action on the first matched element.

‎lib/aria.js‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -293,4 +293,14 @@ function ariaSnapshotFromAXNodes(axNodes, backendNodeId) {
293293
return root ? ariaSnapshotFromTree(toTree(root)) : ''
294294
}
295295

296-
export { diffAriaSnapshots, compactAriaSnapshot, ariaSnapshotFromTree, ariaSnapshotFromAXNodes }
296+
function interactiveAriaNodes(snapshot) {
297+
const walk = nodes =>
298+
nodes.flatMap(node => {
299+
const fromChildren = walk(node.children)
300+
if (!INTERACTIVE_ROLES.has(node.role) || !node.name || !node.name.trim()) return fromChildren
301+
return [{ role: node.role, name: node.name.trim() }, ...fromChildren]
302+
})
303+
return walk(parseSnapshot(snapshot))
304+
}
305+
306+
export { diffAriaSnapshots, compactAriaSnapshot, ariaSnapshotFromTree, ariaSnapshotFromAXNodes, interactiveAriaNodes }

0 commit comments

Comments
 (0)