hasDescription function Matchers

Matcher hasDescription([ dynamic expectedDescription, bool normalizeWhitespace = true ])

Allows you to check whether the given element has a description or not.

An element gets its description via the aria-describedby attribute. Set this to the id of one or more other elements. These elements may be nested inside, be outside, or a sibling of the passed in element.

The whitespace of the element content is normalized unless you set normalizeWhitespace to false.

Elements with multiple space-separated ids as the value of its aria-describedby attribute will join the referenced elements’ text content separated by a space.

When a String argument is passed through, it will perform a whole case-sensitive match to the description text.

To perform a partial or case-insensitive match, you can use any of the string matchers like contains, or construct a RegExp with caseSensitive set to true.

Similar to jest-dom's toHaveDescription matcher.

Examples

<button aria-label="Close" aria-describedby="description-close">
  &times;
</button>
<div id="description-close">
  Closing will discard any changes
</div>

<button>Delete</button>

import 'package:react/react.dart' as react;
import 'package:react_testing_library/matchers.dart' show hasDescription;
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({
        'aria-label': 'Close',
        'aria-describedby': 'description-close',
      }, 'X'),
      react.div({'id': 'description-close'}, 'Closing will discard any changes'),
      react.button({}, 'Delete'),
    ));

    // Use react_testing_library queries to store references to the node(s)
    final closeButton = view.getByRole('button', name: 'Close');
    final deleteButton = view.getByRole('button', name: 'Delete');

    // Use the `hasDescription` matcher as the second argument of `expect()`
    expect(closeButton, hasDescription('Closing will discard any changes'));
    expect(closeButton, hasDescription(contains('will discard')));
    expect(closeButton, hasDescription(RegExp(r'^closing', caseSensitive: false))); // to use case-insensitive match
    expect(closeButton, isNot(hasDescription('Other description')));
    expect(closeButton, hasDescription()); // Will match a non-empty description
    expect(deleteButton, isNot(hasDescription())); // Will match a missing or empty-string description
  });
}

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.

Implementation

// ignore: avoid_positional_boolean_parameters
Matcher hasDescription([dynamic expectedDescription, bool normalizeWhitespace = true]) =>
    _HasDescription(expectedDescription, normalizeWhitespace: normalizeWhitespace);