queryAllByLabelText<E extends Element> function ByLabelText Queries

List<E> queryAllByLabelText<E extends Element>(Node container, dynamic text, { bool exact = true, NormalizerFn normalizer([ NormalizerOptions? ])?, String? selector, })

Returns a list of elements that are associated with a LabelElement with the given text, defaulting to an exact match.

Returns an empty list if no element(s) are found within the provided container. Use getAllByLabelText if a RTE is expected.

Related: queryByLabelText

See: testing-library.com/docs/queries/bylabeltext/

Example

The examples below demonstrate the usage of the getByDisplayValue query. However, the example is also relevant for getAllByLabelText, queryByLabelText, queryAllByLabelText, findByLabelText and findAllByLabelText.

Read more about the different types of queries to gain more clarity on which one suits your use-cases best.

The example below will find the input node for the following DOM structures:

// for/htmlFor relationship between label and form element id
<label for="username-input">Username</label>
<input id="username-input" />

// The aria-labelledby attribute with form elements
<label id="username-label">Username</label>
<input aria-labelledby="username-label" />

// Wrapper labels
<label>Username <input /></label>

// Wrapper labels where the label text is in another child element
<label>
  <span>Username</span>
  <input />
</label>

// aria-label attributes
// Take care because this is not a label that users can see on the page,
// so the purpose of your input must be obvious to visual users.
<input aria-label="username" />

import 'package:react/react.dart' as react;
import 'package:react_testing_library/matchers.dart' show isInTheDocument;
import 'package:react_testing_library/react_testing_library.dart' as rtl;
import 'package:test/test.dart';

main() {
  test('', () {
    // Render some of the DOM shown in the example snippet above
    final view = rtl.render(react.div({},
      react.label({'htmlFor': 'username-input'}, 'Username'),
      react.input({
        'type': 'text',
        'id': 'username-input',
      }),
    ));

    expect(view.getByLabelText('Username'), isInTheDocument);
  });
}

NOTE: render() supports React vDom elements / custom components created using either the

react or over_react packages.

The examples shown here use the react package since the react_testing_library does not have a direct dependency on over_react - but both libraries are fully supported.

Options

text

This argument can be set to a String, RegExp, or a Function which returns true for a match and false for a mismatch.

See the JS TextMatch docs for more details and examples.

exact

Defaults to true; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive. It has no effect on regex or function arguments. In most cases using a regex instead of a string gives you more control over fuzzy matching and should be preferred over exact: false.

normalizer

An optional function which overrides normalization behavior.

Before running any matching logic against text in the DOM, DOM Testing Library automatically normalizes that text. By default, normalization consists of trimming whitespace from the start and end of text, and collapsing multiple adjacent whitespace characters into a single space.

If you want to prevent that normalization, or provide alternative normalization (e.g. to remove Unicode control characters), you can provide a normalizer function. This function will be given a string and is expected to return a normalized version of that string.

NOTE: Specifying a value for normalizer replaces the built-in normalization, but you can call getDefaultNormalizer to obtain a built-in normalizer, either to adjust that normalization or to call it from your own normalizer.

See the JS TextMatch precision and JS TextMatch normalization docs for more details and examples.

selector

Set selector to a CSS selector that will narrow the scope of the existing query to only match element(s) that match the selector.

Implementation

List<E> queryAllByLabelText<E extends Element>(
  Node container,
  /*TextMatch*/ dynamic text, {
  bool exact = true,
  NormalizerFn Function([NormalizerOptions?])? normalizer,
  String? selector,
}) =>
    within(container).queryAllByLabelText<E>(text, exact: exact, normalizer: normalizer, selector: selector);