queryByLabelText

queryByLabelText is a query function in React Testing Library that returns the form control element associated with a given label text. It searches the rendered DOM for a label that matches the provided text and then returns the element the label controls. The lookup respects standard accessibility associations, such as a label with an htmlFor attribute matching the input id or a nested input inside the label.

Return value and behavior: queryByLabelText returns the matched element if exactly one match exists. It returns null if no element matches. If more than one element matches the label text, it throws an error because the query is ambiguous. This behavior makes it useful for tests that expect a single control with a specific label.

Usage: It is commonly used to locate inputs, selects, textareas, and other labeled controls in tests. Example usage: const emailInput = queryByLabelText(/email/i); if (emailInput) { fireEvent.change(emailInput, { target: { value: '[email protected]' } }); } The function is part of the standard RTL query set and can be used with other RTL utilities like userEvent, fireEvent, and assertions.

Relation to other queries: queryByLabelText is one of the "query by" family, alongside getByLabelText and findByLabelText. getByLabelText throws if no match or multiple matches; findByLabelText is asynchronous and waits for an element to appear; queryByLabelText returns null on no match and throws on multiple matches.

Limitations: It relies on proper label associations and may not locate controls that lack a visible or accessible label. For asynchronous scenarios or to wait for appearance, findByLabelText is more appropriate.