搜索插件、代码仓与 APP 分类

插件详情v3.1.2

react_testing_library

一个用于 OverReact 组件的 Dart 单元测试库,其 API 与 JS react-testing-library 相似

Web
近 30 天下载
1.8万
喜欢数
4
Pub 分数
120

安装插件

flutter pub add react_testing_library

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个专为 OverReact 组件设计的 Dart 单元测试库,提供与 JavaScript react-testing-library 类似的熟悉 API。它使开发者能够通过关注组件行为而非实现细节,编写直观、以用户为中心的测试。该库支持 Web 平台,并可无缝集成到 Flutter 的测试生态系统中。通过鼓励开发者像用户一样与渲染的 UI 元素进行交互来测试,该库促进了稳健的测试实践。

适合场景

  • 测试 OverReact 组件渲染
  • 验证 Web 应用中的用户交互
  • 编写可访问且可维护的 UI 测试
  • 模拟真实世界用户场景
  • 确保组件行为符合预期

主要特点

  • 熟悉的 JS react-testing-library API
  • 专注于以用户为中心的测试
  • 仅支持网页平台
  • 鼓励测试渲染输出
  • 提供用于查询类似 DOM 的结构的工具

适合对象

  • 在 Web 项目中使用 OverReact 的开发人员
  • 在测试中优先考虑可访问性和可用性的团队
  • 想要简单、可读性测试语法的测试人员
  • 需要一致的 UI 测试模式的项目
  • 带有 OverReact 组件的 Flutter Web 应用程序

使用建议

  • 仅限Web平台
  • 需要 OverReact 进行组件测试
  • 不适用于非 OverReact Flutter 组件
  • 新用户可能需要一定的学习曲线
  • 依赖 Workiva 的维护和更新

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

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.

Dart CI API Documentation


Introduction

The libraries in this package help you to test Dart UI components in a user-centric way.

The more your tests resemble the way your software is used, the more confidence they can give you.

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 OverReact UiComponent 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.

Getting Started

Before using this library, you should familiarize yourself with Dart, Dart's test library, ReactJS and OverReact first.

1. Add the necessary dependencies to your project
pubspec.yaml
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.0

dev_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.13
  test: ^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

The configuration above is a minimum recommendation only. Read more about configuring a Dart build to learn more / ensure your configuration meets your needs.

3. Configure dart_test.yaml to run your tests

Create dart_test.yaml in the root of your project.

dart_test.yaml
platforms:
  - chrome

paths:
  - test/unit/

The configuration above is a minimum recommendation only. Read more about configuring Dart tests, or about Dart's test library to learn more / ensure your configuration meets your needs.

4. Add an HTML template for your tests that will load the necessary React / react-testing-library JS files

NOTE: The names of the files below are recommendations only, and are not essential to a functional setup.

Using test_html_builder (recommended)

We strongly recommend using the test_html_builder library to create a template that will be used to load each .dart.js test file.

test/unit/rtl_unit_test_template.html
<!DOCTYPE html>
<html lang="en">
  <head>
      <title>{{testName}}</title>
      <script src="packages/react/js/react.dev.js"></script>
      <script src="packages/react_testing_library/js/react-testing-library.js"></script>

      {{testScript}}
      <script src="packages/test/dart.js"></script>
  </head>
</html>

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>
<html lang="en">
  <head>
      <title>Some Unit Test</title>
      <script src="packages/react/js/react.dev.js"></script>
      <script src="packages/react_testing_library/js/react-testing-library.js"></script>

      <link rel="x-dart-test" href="some_unit_test.dart">
      <script src="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.

For more in depth examples, see the migration guides.

lib/src/components/greeting.dart
import 'package:over_react/over_react.dart';

part 'greeting.over_react.g.dart';

mixin GreetingProps on UiProps {
  String heading;
  String subHeading;
  String getStartedRoute;
}

UiFactory<GreetingProps> Greeting = uiFunction(
  (props) {
    return (Dom.header()..role = 'group')(
      Dom.h1()(props.heading),
      Dom.h2()(props.subHeading),
      (Dom.a()..href = props.getStartedRoute)('Get started'),
    );
  },
  _$GreetingConfig, // ignore: undefined_identifier
);
test/unit/components/greeting_test.dart
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'));
        });
      });
    });
  });
}

Read more about how queries are scoped to both the view and return value of within()in the above example

Migration Guides

Dart / JS API Parity

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:

所属分类

依赖

依赖清单 7 项

源码仓库

使用此插件的项目

暂无相关数据。