Unable to find an element with the text: This could be because the text is broken up by multiple elements

TL;DR

getByText matches per-element text, so "Hello world" split across two spans matches neither span. Use a function matcher that checks the combined textContent, or match a stable substring with exact set to false.

Error

Unable to find an element with the text: Hello world. This could be because the text
is broken up by multiple elements. In this case, you can provide a function for your
text matcher to make your matcher more flexible.

Steps

1. Confirm the split with screen.debug(): the string should appear across separate child elements. Expected: you see the markup dividing the text.
2. Replace the string matcher with a function matcher. Expected: the query returns the parent element holding the full text.

screen.getByText(function (content, element) {
  return element.textContent === 'Hello world'
})

3. Alternatively match a stable substring: screen.getByText('Hello', { exact: false }). Expected: it matches as long as that substring is unique on the page.
4. Rerun the test. Expected: it passes with no matcher error.

When to use

• The error message itself suggests the text is broken up by multiple elements.
• The text includes inline formatting (strong, em, line breaks) that splits it.
• i18n interpolation or variables split a sentence across elements.

When not to use

• The text never renders; check conditional rendering first.
• The text arrives after async work; use findByText, which waits.
• You need the exact child element, not the parent; restructure the component markup instead.

Tool compatibility

• @testing-library/dom 8 and newer, @testing-library/react 13 and newer.
• jest, Vitest, and Cypress component testing.

Variant phrasings

This could be because the text is broken up by multiple elements

The diagnostic sentence inside the error. It is telling you the fix: provide a function matcher.

you can provide a function for your text matcher to make your matcher more flexible

The suggested remedy in the same error. The function receives each element and you compare textContent.

Why it happens

The default text matcher compares each element's own text nodes and ignores children, so a parent whose full text spans several children never matches a plain string.

Edge cases

• A function matcher can match several elements, which throws a "multiple elements" error; scope it by checking the element tag or using a container.
• Whitespace and line breaks inside textContent need normalizing; collapse spaces before comparing.
• Matching the parent means assertions on its children still work, but be deliberate about which node you assert on.

Provenance

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

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

Thread query: Unable to find an element with the text: This could be because the text is broken up by multiple elements

TL;DR: getByText matches per-element text, so "Hello world" split across two spans matches neither span. Use a function matcher that checks the combined textContent, or match a stable substring with exact set to false.