## TL;DR

Espresso's onView requires exactly one match; AmbiguousViewMatcherException means your matcher hit two or more views. Combine matchers with allOf to add a distinguishing trait (text, parent, or visibility) instead of guessing with index hacks.

## Error

```text
androidx.test.espresso.AmbiguousViewMatcherException: 'with id: com.example:id/save' matches multiple views in the hierarchy.
```

## Steps

1. Read the exception's view dump to see each matched view and its parents. Expected: you can tell the two apart (one in a dialog, one in the activity, and so on).
2. Narrow with allOf plus a second trait: `onView(allOf(withId(R.id.save), withText("Save"))).perform(click())`. Expected: exactly one view matches.
3. If the text is identical, scope by hierarchy: `allOf(withId(R.id.save), isDescendantOfA(withId(R.id.dialog_root)))`. Expected: only the dialog's button matches.
4. If both views are truly identical, prefer fixing the layout (unique IDs per screen) over index-based matchers. Expected: the test reads unambiguously and survives layout changes.
5. Re-run the test. Expected: no AmbiguousViewMatcherException.

## When to use

- The exception is AmbiguousViewMatcherException.
- The same view ID exists in two fragments, a dialog, or a reused layout.
- It started after adding a second screen with a copy-pasted layout.

## When not to use

- NoMatchingViewException (zero matches; the opposite problem).
- PerformException (one view matched but the action failed).
- The matcher is on a RecyclerView item (use onData or RecyclerViewActions, not onView).

## Tool compatibility

- Espresso 3.x with AndroidX Test, any API level.

## Variant phrasings

### matches multiple views in the hierarchy

The classic text of this exception; the view dump below it names the culprits.

### withContentDescription matching two icons

Same fix: add withText, a parent scope, or isDisplayed to disambiguate.

### withText matching a visible and a hidden view

Hidden (GONE) views still match. Add isDisplayed inside the allOf.

## Why it happens

Matchers describe traits, not identities; copy-pasted layouts and dialogs reuse IDs, so a bare withId can match the activity's view and the dialog's view at once. Espresso refuses to guess which one you meant and throws instead.

## Edge cases

- Hidden views still match, so include isDisplayed when you mean the visible one.
- RecyclerView items need onData or RecyclerViewActions; onView cannot see them reliably.
- isDescendantOfA needs the ancestor's ID to be unique too, or you just move the ambiguity up one level.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_wRB24knN-hrRsTqDhTvV2A
