cypress cy.contains() found no elements: debugging

TL;DR

When cy.contains() finds nothing, the text is almost never where and when you think it is. Check the exact text including case and whitespace, confirm the element is actually in the DOM at query time (not rendered late by an async call), and look for shadow DOM or hidden duplicates. Log the DOM in the failure screenshot before changing the test.

The query

cypress cy.contains() found no elements: debugging

Use this when

• cy.contains() fails but you can see the text in a manual pass
• The text is rendered by an async request or a client-side framework
• The same test passes locally and fails in CI

Not for

• Choosing between contains and get (selector strategy)
• Cross-origin iframe content (that needs a different approach)
• Testing that text is absent (use a not-exist assertion instead)

Steps

1. Read the failure output carefully. Cypress prints the subject and the timeout it waited. Note whether it retried the full timeout or failed fast.

Expected output: the exact error message with the waited duration, copied into your notes.

1. Compare exact text. Check case, punctuation, and whitespace, including non-breaking spaces. Copy the text from the DOM, not from the design mock.

Expected output: the literal string from the DOM, character for character.

1. Check timing. The text may render after an API call resolves. Add a temporary wait on the network request or the element's parent before the contains call.

Expected output: identification of whether the element exists at query time, from a DOM snapshot on failure.

1. Look for shadow DOM and hidden copies. Frameworks sometimes render text in shadow roots or keep hidden duplicates that contains skips.

Expected output: a DOM inspection showing where the text actually lives.

1. Scope the search. Pass a selector as the first argument to limit contains to the right container instead of the whole page.

Expected output: a passing test with contains scoped to the specific component.

Provenance

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