findByTestId<E extends Element> function Async ByTestId Queries

Future<E> findByTestId<E extends Element>(Node container, dynamic testId, { bool exact = true, NormalizerFn normalizer([ NormalizerOptions? ])?, Duration? timeout, Duration interval = defaultAsyncCallbackCheckInterval, QueryTimeoutFn? onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions, })

Returns a future with a single element value with the given testId value for the data-test-id attribute, defaulting to an exact match after waiting 1000ms (or the provided timeout duration).

If there is a specific condition you want to wait for other than the DOM node being on the page, wrap a non-async query like getByTestId or queryByTestId in a waitFor function.

ByTestId Caveats

Guiding Principles / Priority In the spirit of the guiding principles, it is recommended to use this only when a more accessible query is not an option. Using data-test-id attributes do not resemble how your software is used and should be avoided if possible. That said, they are way better than querying based on DOM structure or styling css class names. Learn more about data-test-ids from the blog post "Making your UI tests resilient to change".

Enabling Test Mode When using a *ByTestId query on an OverReact component, you must call enableTestMode() within main() of your test(s).

Throws if exactly one element is not found within the provided container.

Related: findAllByTestId

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

Example

The example below demonstrates the usage of the getByTestId query. However, the example is also relevant for getAllByTestId, queryByTestId, queryAllByTestId, findByTestId and findAllByTestId.

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

<div data-test-id="custom-element" />

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 the DOM shown in the example snippet above
    final view = rtl.render(
      react.div({'data-test-id': 'custom-element'}),
    );

    expect(view.getByTestId('custom-element'), 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

testId

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.

Async Options

timeout

How long to wait for the node to appear in the DOM before throwing a TestFailure, defaulting to 1000ms.

interval

How often the callback is called, defaulting to 50ms.

onTimeout

Is called if the timeout duration passes before the node is found in the DOM, and can be used to customize a TestFailure message.

mutationObserverOptions

The default values are:

{subtree: true, childList: true, attributes: true, characterData: true}

which will detect additions and removals of child elements (including text nodes) in the container and any of its descendants. It will also detect attribute changes. When any of those changes occur, it will re-run the callback.

Implementation

Future<E> findByTestId<E extends Element>(
  Node container,
  /*TextMatch*/ dynamic testId, {
  bool exact = true,
  NormalizerFn Function([NormalizerOptions?])? normalizer,
  Duration? timeout,
  Duration interval = defaultAsyncCallbackCheckInterval,
  QueryTimeoutFn? onTimeout,
  MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions,
}) =>
    within(container).findByTestId<E>(testId,
        exact: exact,
        normalizer: normalizer,
        timeout: timeout,
        interval: interval,
        onTimeout: onTimeout,
        mutationObserverOptions: mutationObserverOptions);