Package selection guidance compiled from public package information, community data, and project usage.
A Dart unit testing library designed for OverReact components, providing a familiar API that mirrors the JavaScript react-testing-library. It enables developers to write intuitive, user-centric tests by focusing on component behavior rather than implementation details. The library supports web platforms and integrates seamlessly with Flutter's testing ecosystem. It promotes robust testing practices by encouraging testing of rendered UI elements as users would interact with them.
Use cases
Testing OverReact component rendering
Validating user interactions in web apps
Writing accessible and maintainable UI tests
Simulating real-world user scenarios
Ensuring component behavior matches expectations
Key features
Familiar API from JS react-testing-library
Focus on user-centric testing
Supports web platform only
Encourages testing of rendered output
Provides utilities for querying DOM-like structures
Suitable for
Developers using OverReact in web projects
Teams prioritizing accessibility and usability in tests
Testers wanting a simple, readable testing syntax
Projects requiring consistent UI test patterns
Flutter web applications with OverReact components
Considerations
Limited to web platform
Requires OverReact for component testing
Not suitable for non-OverReact Flutter components
May require learning curve for new users
Dependent on Workiva's maintenance and updates
Original README
Original README snapshot from the linked source repository. Visit the repository for the latest content.
Testing Library for Dart
Dart bindings for the JS dom-testing-library and react-testing-library packages, which provide simple and complete DOM/React testing utilities that encourage good testing practices.
To paint the full picture of how / why to use this library, please read the JS Testing Library Introduction, Guiding Principles and FAQs.
How Does It Work?
Rather than dealing with OverReactUiComponent instances, or React VDom ReactElements, your tests will work with actual DOM nodes. The utilities this library provides facilitate querying the DOM in the same way the user would. Finding form elements by their label text (just like a user would), finding links and buttons from their text (like a user would). It also exposes a recommended way to find elements by an HTML data-test-id attribute value as an "escape hatch" for elements where the text content and label do not make sense or is not practical.
This library encourages your Dart web applications to be more accessible and allows you to get your tests closer to using your components the way a user will, which allows your tests to give you more confidence that your application will work when a real user uses it.
dependencies:# This is not required to use this library, but it is assumed# that you are testing OverReact UI components, so it is # shown here for completeness.over_react:^4.0.0dev_dependencies:build_runner:">=1.7.1 <3.0.0"build_test:">=0.10.9 <3.0.0"build_web_compilers:">=2.12.0 <4.0.0"react_testing_library:^1.1.13test:^1.14.4# This is not technically required, # but makes the HTML portion of your test bootstrapping much easier!test_html_builder:^2.0.0
2. Configure build.yaml to generate test outputs
build.yaml
targets:$default:builders:build_web_compilers|entrypoint:# These are globs for the entrypoints you want to compile.generate_for:-test/**.browser_test.dart
Use the template .html file above and follow the test_html_builder library instructions for wiring it up!
Adding / committing your own HTML file(s)
If for some reason you do not wish to use the test_html_builder library to generate the necessary .html file(s), you must create one for each analogous *_test.dart file in which you are using react_testing_library as shown below. Note that you will have to have one .html file for each .dart file containing your unit tests.
test/unit/some_unit_test.html
<!DOCTYPE html><htmllang="en"><head><title>Some Unit Test</title><scriptsrc="packages/react/js/react.dev.js"></script><scriptsrc="packages/react_testing_library/js/react-testing-library.js"></script><linkrel="x-dart-test"href="some_unit_test.dart"><scriptsrc="packages/test/dart.js"></script></head></html>
5. Write test(s) for your component(s)!
Using the render function, you can now generate DOM using React components and query within that DOM to get the element(s) you want to test!
Then, you can use the Matchers from the matchers.dart entrypoint to perform assertions on that DOM, and the events and user events entrypoints or whatever to interact with the DOM.
import'dart:html';
import'package:test/test.dart';
import'package:react_testing_library/react_testing_library.dart'as rtl;
import'package:react_testing_library/matchers.dart';
import'package:your_package/src/components/greeting.dart';
main() {
group('Greeting', () {
rtl.RenderResult view;
tearDown(() {
view = null;
});
group('renders the expected elements:', () {
group('a <header>', () {
HtmlElement headerElement;
setUp(() {
view = rtl.render((Greeting()
..heading = 'Hello There!'
..subHeading = 'Welcome to the unit testing party.'
..getStartedRoute = '/start/partying'
)());
headerElement = view.getByRole('group');
});
test('with a child <h1> with a text value equal to props.heading', () {
final h1Element = rtl.within(headerElement).getByRole('heading', level: 1);
expect(h1Element, hasTextContent('Hello There!'));
});
test('with a child <h2> with a text value equal to props.subHeading', () {
final h2Element = rtl.within(headerElement).getByRole('heading', level: 2);
expect(h2Element, hasTextContent('Welcome to the unit testing party.'));
});
test('with a child <a> with an href equal to props.getStartedRoute', () {
final anchorElement = rtl.within(headerElement).getByRole('link');
expect(anchorElement, hasAttribute('href', '/start/partying'));
});
});
});
});
}
The react_testing_library Dart package strives to maintain API parity with the analogous JS testing-library packages within reason. However, there are certain differences that are either unavoidable, or intentional for the purposes of building Dart APIs that are easy to use and reason about.
Read more about Dart / JS API Parity for the following API categories: