内容
description bug_report

小部件测试入门

内容

在 单元测试简介 食谱中，您学习了如何使用 test 包测试 Dart 类。要测试小部件类，您需要 flutter_test 包提供的几个额外工具，该包随 Flutter SDK 一起提供。

flutter_test 包提供了以下用于测试小部件的工具

  • WidgetTester 允许在测试环境中构建和交互小部件。
  • testWidgets() 函数会为每个测试用例自动创建一个新的 WidgetTester，并用作普通 test() 函数的替代。
  • Finder 类允许在测试环境中搜索小部件。
  • 特定于小部件的 Matcher 常量有助于验证 Finder 是否在测试环境中定位了一个或多个小部件。

如果这听起来很复杂，别担心。了解所有这些部分如何在这个食谱中协同工作，该食谱使用以下步骤

  1. 添加 flutter_test 依赖项。
  2. 创建一个要测试的小部件。
  3. 创建一个 testWidgets 测试。
  4. 使用 WidgetTester 构建小部件。
  5. 使用 Finder 搜索小部件。
  6. 使用 Matcher 验证小部件。

1. 添加 flutter_test 依赖项

#

在编写测试之前，请在 pubspec.yaml 文件的 dev_dependencies 部分中包含 flutter_test 依赖项。如果使用命令行工具或代码编辑器创建新的 Flutter 项目，此依赖项应该已经存在。

yaml
dev_dependencies:
  flutter_test:
    sdk: flutter

2. 创建要测试的小部件

#

接下来，创建一个用于测试的小部件。对于这个食谱，创建一个显示 title 和 message 的小部件。

dart
class MyWidget extends StatelessWidget {
  const MyWidget({
    super.key,
    required this.title,
    required this.message,
  });

  final String title;
  final String message;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Scaffold(
        appBar: AppBar(
          title: Text(title),
        ),
        body: Center(
          child: Text(message),
        ),
      ),
    );
  }
}

3. 创建一个 testWidgets 测试

#

有了要测试的小部件，就开始编写您的第一个测试。使用 flutter_test 包提供的 testWidgets() 函数来定义测试。testWidgets 函数允许您定义小部件测试并创建一个 WidgetTester 来使用。

此测试验证 MyWidget 是否显示给定的标题和消息。它将根据标题进行命名，并在下一部分中进行填充。

dart
void main() {
  // Define a test. The TestWidgets function also provides a WidgetTester
  // to work with. The WidgetTester allows you to build and interact
  // with widgets in the test environment.
  testWidgets('MyWidget has a title and message', (tester) async {
    // Test code goes here.
  });
}

4. 使用 WidgetTester 构建小部件

#

接下来，使用 WidgetTester 提供的 pumpWidget() 方法在测试环境中构建 MyWidget。pumpWidget 方法构建并渲染提供的小部件。

创建一个 MyWidget 实例，显示标题为“T”，消息为“M”。

dart
void main() {
  testWidgets('MyWidget has a title and message', (tester) async {
    // Create the widget by telling the tester to build it.
    await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
  });
}

关于 pump() 方法的说明

#

在首次调用 pumpWidget() 后，WidgetTester 提供了其他方法来重建相同的小部件。如果您正在处理 StatefulWidget 或动画，这将非常有用。

例如，点击按钮会调用 setState()，但 Flutter 不会在测试环境中自动重建您的 widget。使用以下方法之一来要求 Flutter 重建 widget。

tester.pump(Duration duration)
调度一个帧并触发 widget 的重建。如果指定了 Duration，它会将时钟向前推进该时间量并调度一个帧。即使持续时间超过一个帧，它也不会调度多个帧。
tester.pumpAndSettle()
使用给定的持续时间重复调用 pump()，直到不再调度任何帧。这实际上是在等待所有动画完成。

这些方法提供了对构建生命周期的细粒度控制，这在测试时特别有用。

5. 使用 Finder 搜索我们的 widget

#

在测试环境中拥有一个 widget 后，使用 Finder 在 widget 树中搜索 title 和 message 文本 widget。这允许验证 widget 是否正在正确显示。

为此，请使用 flutter_test 包提供的顶级 find() 方法来创建 Finder。由于您知道要查找的是 Text widget，因此请使用 find.text() 方法。

有关 Finder 类的更多信息，请参阅 在 widget 测试中查找 widget 食谱。

dart
void main() {
  testWidgets('MyWidget has a title and message', (tester) async {
    await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));

    // Create the Finders.
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');
  });
}

6. 使用 Matcher 验证 widget

#

最后，使用 flutter_test 提供的 Matcher 常量验证标题和消息 Text widget 是否出现在屏幕上。Matcher 类是 test 包的核心部分，并提供了一种通用的方法来验证给定值是否符合预期。

确保小部件在屏幕上只出现一次。为此，请使用 findsOneWidget Matcher。

dart
void main() {
  testWidgets('MyWidget has a title and message', (tester) async {
    await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');

    // Use the `findsOneWidget` matcher provided by flutter_test to verify
    // that the Text widgets appear exactly once in the widget tree.
    expect(titleFinder, findsOneWidget);
    expect(messageFinder, findsOneWidget);
  });
}

其他 Matcher

#

除了 findsOneWidget 之外，flutter_test 还为常见情况提供了其他匹配器。

findsNothing
验证没有找到任何小部件。
findsWidgets
验证找到一个或多个小部件。
findsNWidgets
验证找到特定数量的小部件。
matchesGoldenFile
验证小部件的渲染是否与特定位图图像（“黄金文件”测试）匹配。

完整示例

#
dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  // Define a test. The TestWidgets function also provides a WidgetTester
  // to work with. The WidgetTester allows building and interacting
  // with widgets in the test environment.
  testWidgets('MyWidget has a title and message', (tester) async {
    // Create the widget by telling the tester to build it.
    await tester.pumpWidget(const MyWidget(title: 'T', message: 'M'));

    // Create the Finders.
    final titleFinder = find.text('T');
    final messageFinder = find.text('M');

    // Use the `findsOneWidget` matcher provided by flutter_test to
    // verify that the Text widgets appear exactly once in the widget tree.
    expect(titleFinder, findsOneWidget);
    expect(messageFinder, findsOneWidget);
  });
}

class MyWidget extends StatelessWidget {
  const MyWidget({
    super.key,
    required this.title,
    required this.message,
  });

  final String title;
  final String message;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      home: Scaffold(
        appBar: AppBar(
          title: Text(title),
        ),
        body: Center(
          child: Text(message),
        ),
      ),
    );
  }
}