xcuitest failed to get matching snapshot: how to fix

TL;DR

XCUITest snapshots the accessibility hierarchy; queries run against a stale snapshot after UI changes. Re-query after transitions, wait for existence, and keep queries simple.

Error

Failed to get matching snapshot: No matches found for "loginButton"

Steps

1. Add waitForExistence(timeout:) before the query. Expected: the UI settles first.
2. Re-fetch the element after every navigation or sheet dismissal; never reuse queries across transitions. Expected: fresh snapshots.
3. Simplify the query: fewer predicates, stable identifiers. Expected: less to go stale.
4. Check the hierarchy with debugDescription printout. Expected: you see what actually exists.
5. Re-run. Expected: green.

When to use

• failed to get matching snapshot in XCUITest.
• After screen transitions.

When not to use

• Appium XCUITest driver issues (different layer).
• Launch failures.

Tool compatibility

• XCUITest; Xcode 14/15.

Variant phrasings

XCUITest no matches found

The short form; re-query after transitions.

XCUITest stale query

The mechanism; snapshots go stale.

Why it happens

XCUITest resolves queries against a captured hierarchy snapshot. UI changes invalidate it, and old query objects do not refresh.

Edge cases

• firstMatch is faster but riskier; use it only for unique elements.
• Animations delay snapshot updates; wait for them.
• System alerts interrupt the hierarchy; handle them explicitly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1FEwqoxQLeA26SdWQ1mNng