Queries Topic

Queries are the functions / methods that Testing Library gives you to find elements on the page. There are several types of queries ("get", "find", "query"); the difference between them is whether the query will throw an error if no element is found or if it will return a Future and retry. Depending on what page content you are selecting, different queries may be more or less appropriate. See the priority guide for recommendations on how to make use of semantic queries to test your page in the most accessible way.

Scoping Queries

Scoping a query to a specified container within the DOM can be done in a number of ways:

  1. By specifying the container argument on a "top level" query function.
  2. By using the default container pre-defined for query methods exposed by the class instance returned from:
    1. render(): scoped to the root of the rendered ReactElement
    2. within(<container>): scoped to the provided <container>
    3. screen: scoped to document.body

The function signatures for the queries are identical no matter which place you call them from with the exception of the "top level" query functions - which require that a container be specified as the first argument as shown in the examples below.

Examples

test/unit/example_test.dart
import 'package:react/react.dart' as react;
import 'package:react_testing_library/react_testing_library.dart' as rtl;
import 'package:test/test.dart';

main() {
  final exampleVDom = react.nav({},
    react.ul({},
      react.li({}, 'Item 1'),
      react.li({}, 'Item 2'),
      react.li({}, 
        'Item 3',
        react.ul({},
          react.li({}, 'Item 3.1'),
          react.li({}, 'Item 3.2'),
        ),
      ),
    ),
  );
  
  test('', () {
    final view = rtl.render(exampleVDom);
    
    // Succeeds, there is only one in the react tree.
    final goodNavQuery = view.getByRole('nav');
    // This is identical to the first query, but shows how 
    // the top level queries must specify a container. 
    final moreVerboseNavQuery = 
        rtl.getByRole(view.container, 'nav');
    
    // Fails, there is more than one element with the list role 
    // in the default scope used by the `RenderResult` instance 
    // returned from `rtl.render`. If we want to get only the 
    // nested list, we should use a more tightly scoped query
    // like the one shown next.
    final badSubListQuery = view.getByRole('list');
    
    // Succeeds, there is only one list nested within the" "Item 3" item.
    final goodSubListQuery = 
        rtl.within(view.getByText('Item 3')).getByRole('list');
    
    // Lets say that our test above also renders an element that displays an 
    // overlay / "portal" dialog of some kind that renders in its own tree. 
    // This is where the `screen` queries come in handy - it allows you to 
    // easily query the entire document for something.
    final documentQueryOutsideTheReactTree = rtl.screen.getByRole('dialog');
    
    // If querying the entire document is too broad, you can still easily 
    // query outside the scope of the react tree rendered in the test 
    // by specifying a container using `within`:
    final scopedQueryOutsideTheReactTree = 
        rtl.within(someElementWhereYouExpectTheDialog).getByRole('dialog');
  });
}

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.

Classes

RenderResult Queries
The model returned from render, which includes all the ScopedQueries scoped to the container that the renderedElement was rendered within. [...]
WithinQueries Queries
Queries scoped to the provided container.

Properties

screen ScreenQueries Queries
Exposes all the "top-level" queries exposed by the dom-testing-library, but the scope/container is defaulted to document.body. [...]
read / write

Functions

findAllByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByAltText Queries
Returns a list of ImageElements, InputElements and/or AreaElements with the given text as the value of the alt attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
findAllByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByDisplayValue Queries
Returns a list of InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findAllByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByLabelText Queries
Returns a list of elements that are associated with a LabelElement with the given text, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findAllByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByPlaceholderText Queries
Returns a list of elements with the given text as the value of the placeholder attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
findAllByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level, Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByRole Queries
Returns a list of elements with the given role value, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findAllByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByTestId Queries
Returns a list of elements with the given testId value for the data-test-id attribute, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findAllByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script', Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByText Queries
Returns a list of elements with the given text content, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findAllByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<List<E>> Async ByTitle Queries
Returns a list of elements with the given title as the value of the title attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
findByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByAltText Queries
Returns a future with a single ImageElement, InputElement or AreaElement value with the given text as the value of the alt attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
findByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByDisplayValue Queries
Returns a future with a single InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByLabelText Queries
Returns a future with a single element that is associated with a LabelElement with the given text, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByPlaceholderText Queries
Returns a future with a single element value with the given text as the value of the placeholder attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
findByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level, Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByRole Queries
Returns a future with a single element value with the given role value, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByTestId Queries
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). [...]
findByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script', Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByText Queries
Returns a future with a single element value with the given text content, defaulting to an exact match after waiting 1000ms (or the provided timeout duration). [...]
findByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), Duration timeout, Duration interval, QueryTimeoutFn onTimeout, MutationObserverOptions mutationObserverOptions = defaultMutationObserverOptions}) Future<E> Async ByTitle Queries
Returns a future with a single element value with the given title as the value of the title attribute, defaulting to an exact match after waiting 1000ms (or the specified timeout duration). [...]
getAllByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByAltText Queries
Returns a list of ImageElements, InputElements and/or AreaElements with the given text as the value of the alt attribute, defaulting to an exact match. [...]
getAllByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByDisplayValue Queries
Returns a list of InputElements, TextAreaElements or SelectElements that have the matching value displayed, defaulting to an exact match. [...]
getAllByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector}) List<E> ByLabelText Queries
Returns a list of elements that are associated with a LabelElement with the given text, defaulting to an exact match. [...]
getAllByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByPlaceholderText Queries
Returns a list of elements with the given text as the value of the placeholder attribute, defaulting to an exact match. [...]
getAllByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level}) List<E> ByRole Queries
Returns a list of elements with the given role value, defaulting to an exact match. [...]
getAllByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByTestId Queries
Returns a list of elements with the given testId value for the data-test-id attribute, defaulting to an exact match. [...]
getAllByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script'}) List<E> ByText Queries
Returns a list of elements with the given text content, defaulting to an exact match. [...]
getAllByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByTitle Queries
Returns a list of elements with the given title as the value of the title attribute, defaulting to an exact match. [...]
getByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByAltText Queries
Returns a single ImageElement, InputElement or AreaElement with the given text as the value of the alt attribute, defaulting to an exact match. [...]
getByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByDisplayValue Queries
Returns a single InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match. [...]
getByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector}) → E ByLabelText Queries
Returns a single element that is associated with a LabelElement with the given text, defaulting to an exact match. [...]
getByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByPlaceholderText Queries
Returns a single element with the given text as the value of the placeholder attribute, defaulting to an exact match. [...]
getByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level}) → E ByRole Queries
Returns a single element with the given role value, defaulting to an exact match. [...]
getByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByTestId Queries
Returns a single element with the given testId value for the data-test-id attribute, defaulting to an exact match. [...]
getByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script'}) → E ByText Queries
Returns a single element with the given text content, defaulting to an exact match. [...]
getByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByTitle Queries
Returns a single element with the given title as the value of the title attribute, defaulting to an exact match. [...]
queryAllByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByAltText Queries
Returns a list of ImageElements, InputElements and/or AreaElements with the given text as the value of the alt attribute, defaulting to an exact match. [...]
queryAllByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByDisplayValue Queries
Returns a list of InputElements, TextAreaElements or SelectElements that have the matching value displayed, defaulting to an exact match. [...]
queryAllByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector}) List<E> ByLabelText Queries
Returns a list of elements that are associated with a LabelElement with the given text, defaulting to an exact match. [...]
queryAllByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByPlaceholderText Queries
Returns a list of elements with the given text as the value of the placeholder attribute, defaulting to an exact match. [...]
queryAllByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level}) List<E> ByRole Queries
Returns a list of elements with the given role value, defaulting to an exact match. [...]
queryAllByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByTestId Queries
Returns a list of elements with the given testId value for the data-test-id attribute, defaulting to an exact match. [...]
queryAllByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script'}) List<E> ByText Queries
Returns a list of elements with the given text content, defaulting to an exact match. [...]
queryAllByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) List<E> ByTitle Queries
Returns a list of elements with the given title as the value of the title attribute, defaulting to an exact match. [...]
queryByAltText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByAltText Queries
Returns a single ImageElement, InputElement or AreaElement with the given text as the value of the alt attribute, defaulting to an exact match. [...]
queryByDisplayValue<E extends Element>(Node container, dynamic value, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByDisplayValue Queries
Returns a single InputElement, TextAreaElement or SelectElement that has the matching value displayed, defaulting to an exact match. [...]
queryByLabelText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector}) → E ByLabelText Queries
Returns a single element that is associated with a LabelElement with the given text, defaulting to an exact match. [...]
queryByPlaceholderText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByPlaceholderText Queries
Returns a single element with the given text as the value of the placeholder attribute, defaulting to an exact match. [...]
queryByRole<E extends Element>(Node container, dynamic role, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), bool hidden = false, dynamic name, bool selected, bool checked, bool pressed, bool expanded, bool queryFallbacks = false, int level}) → E ByRole Queries
Returns a single element with the given role value, defaulting to an exact match. [...]
queryByTestId<E extends Element>(Node container, dynamic testId, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByTestId Queries
Returns a single element with the given testId value for the data-test-id attribute, defaulting to an exact match. [...]
queryByText<E extends Element>(Node container, dynamic text, {bool exact = true, NormalizerFn normalizer([NormalizerOptions]), String selector, dynamic ignore = 'script'}) → E ByText Queries
Returns a single element with the given text content, defaulting to an exact match. [...]
queryByTitle<E extends Element>(Node container, dynamic title, {bool exact = true, NormalizerFn normalizer([NormalizerOptions])}) → E ByTitle Queries
Returns a single element with the given title as the value of the title attribute, defaulting to an exact match. [...]
within(Node node) WithinQueries Queries
Takes a DOM node and binds it to the raw query functions. [...]