queryByRole<E extends Element> method Null safety

Returns a single element with the given role value, defaulting to an exact match.

Returns null if no element is found. Use getByRole if a RTE is expected.

You can also query the returned element(s) by their accessible name by specifying the name argument: getByRole(expectedRole, name: 'The name').

The accessible name is for simple cases equal to the label of a form element, or the text content of a button, or the value of the aria-label attribute. It can be used to query a specific element if multiple elements with the same role are present on the rendered content.

See: testing-library.com/docs/queries/byrole#api for more details and examples.

Use the logRoles utility to help determine what roles and names are visible to query for.

Related: queryAllByRole

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

Example

The example below demonstrates the usage of the getByRole query. However, the example is also relevant for getAllByRole, queryByRole, queryAllByRole, findByRole and findAllByRole.

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

<button onClick="...">Ok</button>
<button onClick="...">Cancel</button>

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({},
      react.button({'onClick': (_) { /*...*/ }}, 'Ok'),
      react.button({'onClick': (_) { /*...*/ }}, 'Cancel'),
    ));

    expect(view.getByRole('button', name: 'Ok'), isInTheDocument);
    expect(view.getByRole('button', name: 'Cancel'), 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

role

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.

hidden

If you set hidden to true, elements that are normally excluded from the accessibility tree are considered for the query as well.

The default behavior follows www.w3.org/TR/wai-aria-1.2/#tree_exclusion with the exception of role="none" and role="presentation" which are considered in the query in any case.

See: testing-library.com/docs/queries/byrole#hidden for more details and examples.

selected

You can filter the returned elements by their selected state by setting selected: true or selected: false.

To learn more about the selected state and which elements can have this state see ARIA aria-selected.

See: testing-library.com/docs/queries/byrole#selected for more details and examples.

checked

You can filter the returned elements by their checked state by setting checked: true or checked: false.

See: testing-library.com/docs/queries/byrole#checked for more details and examples.

pressed

Buttons can have a pressed state. You can filter the returned elements by their pressed state by setting pressed: true or pressed: false.

To learn more about the pressed state see ARIA aria-pressed.

See: testing-library.com/docs/queries/byrole#pressed for more details and examples.

expanded

You can filter the returned elements by their expanded state by setting expanded: true or expanded: false.

To learn more about the expanded state and which elements can have this state see ARIA aria-expanded.

See: testing-library.com/docs/queries/byrole#expanded for more details and examples.

queryFallbacks

By default, it's assumed that the first role of each element is supported, so only the first role can be queried. If you need to query an element by any of its fallback roles instead, you can use queryFallbacks: true.

See: testing-library.com/docs/queries/byrole#queryfallbacks for more details and examples.

level

An element with the heading role can be queried by any heading level getByRole('heading') or by a specific heading level using the level option getByRole('heading', level: 2).

The level option queries the element(s) with the heading role matching the indicated level determined by the semantic HTML heading elements <h1>-<h6> or matching the aria-level attribute.

To learn more about the aria-level property, see ARIA aria-level.

See: testing-library.com/docs/queries/byrole#level for more details and examples.