getByRole<E extends Element> function Null safety ByRole Queries

E getByRole<E extends Element>(
  1. Node container,
  2. dynamic role,
  3. {bool exact = true,
  4. NormalizerFn normalizer(
    1. [NormalizerOptions?]
  5. bool hidden = false,
  6. dynamic name,
  7. bool? selected,
  8. bool? checked,
  9. bool? pressed,
  10. bool? expanded,
  11. bool queryFallbacks = false,
  12. int? level}

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

Throws if no element is found within the provided container. Use queryByRole if a RTE is not 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: for more details and examples.

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

Related: getAllByRole



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.



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.


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.


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.


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 with the exception of role="none" and role="presentation" which are considered in the query in any case.

See: for more details and examples.


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: for more details and examples.


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

See: for more details and examples.


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: for more details and examples.


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: for more details and examples.


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: for more details and examples.


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: for more details and examples.


E getByRole<E extends Element>(
  Node container,
  /*TextMatch*/ dynamic role, {
  bool exact = true,
  NormalizerFn Function([NormalizerOptions?])? normalizer,
  bool hidden = false,
  /*TextMatch*/ dynamic name,
  bool? selected,
  bool? checked,
  bool? pressed,
  bool? expanded,
  bool queryFallbacks = false,
  int? level,
}) =>
        exact: exact,
        normalizer: normalizer,
        hidden: hidden,
        name: name,
        selected: selected,
        checked: checked,
        pressed: pressed,
        expanded: expanded,
        queryFallbacks: queryFallbacks,
        level: level);