如何测试Flutter应用程序：单元测试、组件测试、黄金标准测试以及集成测试详解

有两种交互行为出现得非常频繁，因此值得专门用示例来讲解：在字段中输入内容，以及滚动页面以查看屏幕外的内容。

testWidgets('在字段中输入内容并提交会触发相关操作', (tester) async {
  final repository = MockTaskRepository();
  when(() => repository.fetchTasks()).thenAnswer((_) async => []);
  when(() => repository.addTask(any)).thenAnswer((_) async {};

  await tester.pumpWidget(MaterialApp(
    home: TaskScreen(notifier: TaskNotifier(repository)),
  );
  await tester.pumpAndSettle();

  // enterText方法可以模拟直接输入文本的操作——在绝大多数测试中，没有必要模拟每次按键的动作。
  await tester.enterText(find.byKey(const Key('new_task_field')), '买牛奶');
  await tester.tap(find.byKey(const Key('add_task_button'));
  await tester.pumpAndSettle();

  verify(() => repository.addTask('买牛奶').called(1);
});

testWidgets('滚动页面可以显示屏幕下方的任务', (tester) async {
  final repository = MockTaskRepository();
  when(() => repository.fetchTasks()).thenAnswer(
    (_) async => List.generate(
      30,
      (i) => Task(id: '$i', title: '任务 $i'),
    ),
  );

  await tester.pumpWidget(MaterialApp(
    home: TaskScreen(notifier: TaskNotifier(repository)),
  );
  await tester.pumpAndSettle();

  // 在一个包含30项任务的列表中，第25项在首次渲染时是显示在屏幕外的。
  expect(find.text('任务25'), findsNothing);

  // scrollUntilVisible方法会反复滚动固定距离，并在每次滚动后检查页面内容——当不知道需要滚动多远才能看到特定项目时，这个方法非常有用。
  await tester.scrollUntilVisible(
    find.text('任务25'),
    500.0,
    scrollable: find.byType(Scrollable),
  );

  expect(find.text('任务25'), findsOneWidget);
});

黄金测试：捕捉视觉回归问题

到目前为止，所有的测试都在检查行为是否正确：比如正确的文本是否出现了，数量是否得到了准确的更新。然而，这些测试无法发现那些会导致复选框列表在小屏幕上超出容器范围的问题，也无法察觉那些会使得重试按钮移出屏幕范围的细节修改。这就是为什么需要黄金测试的存在。

黄金测试会将某个组件渲染出来，然后将其每一像素都与保存好的参考图像进行对比。

// test/task_screen_golden_test.dart
import 'package:flutter/material.dart';
import 'packageflutter_test/flutter_test.dart';
import 'package:mocktail/mocktail.dart';
import 'package:my_app/task.dart';
import 'package:my_app/taskNotifier.dart';
import 'package:my_app/task_repository.dart';
import 'package:my_app/task_screen.dart';

class MockTaskRepository extends Mock implements TaskRepository {}

void main() {
  testWidgets('带有数据的任务页面应与黄金参考文件一致', (tester) async {
    final repository = MockTaskRepository();
    when(() => repository.fetchTasks()).thenAnswer(
      (_) async => [
        const Task(id: '1', title: '买牛奶'),
        const Task(id: '2', title: '遛狗', isDone: true),
      ],
    );

    await tester.pumpWidget(MaterialApp(
      home: TaskScreen(notifier: TaskNotifier(repository)),
    );
    await tester.pumpAndSettle();

    // 在第一次运行时，这个测试会生成参考图像；之后每次运行如果有任何像素不同，这个测试就会失败。
    await expectLater(
      find.byType(TaskScreen),
      matchesGoldenFile('goldens/task_screen_with_data.png'),
    );
  });

  testWidgets('任务页面的错误状态应与黄金参考文件一致', (tester) async {
    final repository = MockTaskRepository();
    when(() => repository.fetchTasks()).thenThrow(Exception('error'));
    }

    await tester.pumpWidget(MaterialApp(
      home: TaskScreen(notifier: TaskNotifier(repository)),
    );
    await tester.pumpAndSettle();

    await expectLater(
      find.byType(TaskScreen),
      matchesGoldenFile('goldens/task_screen_error.png'),
    );
  });
}

使用以下命令生成初始参考图像：

flutter test --update-goldens test/task_screen_golden_test.dart

将生成的〈.png〉文件与测试代码一起提交。从此之后，执行〈flutter test〉命令时会进行对比检查，而不会重新生成参考图像。如果后续的修改导致某个像素的位置发生变化，测试就会失败，并会显示差异信息，这样就不会等到三轮迭代后才发现真实设备上的界面显示有异常。

在大量依赖这一机制之前，有两点需要注意。首先，不同机器或持续集成工具在字体渲染方面可能存在细微差异，这可能会导致一些与代码无关的错误出现。在一致的Docker环境中运行参考图像生成脚本，或者使用像〈golden_toolkit〉这样的工具（该工具可以统一字体加载方式），就能解决大部分这类问题。

其次，在开发过程中屏幕布局经常发生变化时，维护这些参考图像会非常耗时。因此，我只会为那些稳定性较高、需要重点测试的界面生成参考图像，而不是为每一个布局调整都重新生成它们，因为这样做反而违背了生成参考图像的初衷。

多设备及深色模式下的参考图像生成

单个参考图像仅能证明在某一屏幕尺寸和某一主题下界面显示是正确的。我曾经就是这样发现一个错误的：在一个标准尺寸的手机上，任务标题能够正常显示，但在小屏幕设备上却会超出显示范围9像素，直到有使用旧款窄屏手机的用户提交支持请求，我们才发现了这个问题。

〈golden_toolkit〉中的〈multiScreenGolden〉功能可以在一次测试中同时检测多个设备尺寸下的界面显示效果，这也是我在所有需要生成参考图像的测试中都会使用的方法：

devDependencies:
  golden_toolkit: ^0.15.0

testGoldens('task screen across device sizes', (tester) async {
  final repository = MockTaskRepository();
  when(() => repository.fetchTasks()).thenAnswer(
    (_) async => [const Task(id: '1', title: 'Buy milk, eggs, and bread')]
  );

  final builder = DeviceBuilder()
    ..overrideDevicesForAllScenarios(devices: [
      Device.phone,       // 窄屏设备——正是这种设备发现了文本显示超出的问题
      Device.iphone11,
      Device.tabletLandscape,
    ])
    ..addScenario(
      widget: MaterialApp(home: TaskScreen(notifier: TaskNotifier(repository))),
      name: 'with data',
    );

  await tester.pumpDeviceBuilder(builder);
  await screenMatchesGolden(tester, 'task_screen_multi_device');
});

如果你的应用程序支持深色模式，那么也应该为深色模式生成参考图像。如果某个文本颜色在深色背景下无法被显示出来，那就会成为一个非常尴尬的错误；而如果所有的参考图像生成测试都只在浅色模式下进行，那么这种问题就完全不会被发现。

testGoldens('task screen in dark mode', (tester) async { final repository = MockTaskRepository(); when(() => repository.fetchTasks()).thenAnswer( (_) async => [const Task(id: '1', title: 'Buy milk')] ); await tester.pumpWidgetBuilder( TaskScreen(notifier: TaskNotifier(repository)), wrapper: materialAppWrappertheme: ThemeData.dark()), ); await tester.pumpAndSettle(); await screenMatchesGolden(tester, 'task_screen_dark_mode'); });

防止金色测试成为维护负担

我在多个团队中都观察到过这样的情况：起初人们会热情地添加许多金色测试用例，但后来某个合理的设计变更影响了十五个界面中共同使用的组件，结果这十五个金色测试用例全部失败了。团队随后直接执行了`--update-goldens`命令，却并没有仔细检查每一处代码差异。毕竟，在截止日期的压力下，逐一审查十五份代码差异显然显得很不值得。

就在这一刻，金色测试用例就不再能起到保护作用了。因为从那时起，团队的反应往往是“重新生成测试用例然后继续工作”，而不是“仔细查看发生了哪些变化，并确认这些变化确实是故意为之的”。

有两条措施可以避免这种情况的发生。首先，要确保金色测试用例的数量控制在较少范围内，并且要精心挑选这些测试用例。我之前已经提到过这一点，但这里还是需要再次强调：应该选择五到六个具有高价值的界面进行测试，而不是五十个。

其次，当有一批金色测试用例失败时，应该把这视为一个信号，认真查看相关的代码差异，而不仅仅是简单地勾选某个复选框来忽略这些错误。大多数用于执行金色测试的持续集成系统都允许将代码差异文件作为构建结果上传，这样审查人员就可以在拉取请求中快速查看这些差异文件，而不需要先在本地下载相关分支。

集成测试：端到端的整体应用测试

单元测试和组件测试是在模拟的Dart环境中运行的。在这种环境下并没有真正的渲染引擎或平台环境，网络连接也是通过虚拟的仓库来实现的。正因为如此，这些测试的执行速度很快，但同时也正是这种环境使得它们无法检测出这样一个问题：当应用程序的所有组件真正被连接在一起时，它在真实的设备或模拟器上是否能够正常运行。

dev_dependencies:
  integration_test:
    sdk: flutter

// integration_test/complete_task_test.dart
import 'packageflutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:my_app/main.dart' as app;

void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('用户能够加载任务并完成整个流程', (tester) async {
    // 这里会运行实际的应用程序代码——无论是真实的应用程序本身，还是与之连接的后端服务，
    // 在这个构建环境中通常是在预发布环境下进行测试。
    app.main();
    await tester.pumpAndSettle();

    expect(find.text('Buy milk'), findsOneWidget);
    expect(find.textContaining('0 done'), findsOneWidget);

    await tester.tap(find.byType(CheckboxListTile).first);
    await tester.pumpAndSettle();

    expect(find.textContaining('1 done'), findsOneWidget);
  });
}

你可以在真实的设备或模拟器上运行这个测试：

flutter test integration_test/complete_task_test.dart

这种测试方式的速度较慢（耗时以秒而非毫秒为单位），因为它是真正在编译并运行整个应用程序，而不是模拟某个界面结构。正是由于这种测试需要消耗一定的资源，因此集成测试应该重点覆盖那些一旦出现故障就会造成严重后果的操作流程，比如完成购买操作或登录流程——这些才是应用程序存在的根本目的，也就是让用户能够执行的核心功能。而在一个实际的项目中，我会进行五到六次这样的测试，以便在用户真正使用应用程序之前，了解那些需要重点关注的操作流程。

不稳定现象、重试机制与真实设备

与其他三种类型的测试不同，集成测试常常会以一些与错误无关的原因导致失败：例如，CI模拟器的运行速度比平时慢， staging环境中的网络请求耗时超过了预期，或者在下一个操作执行之前动画效果尚未完成等等。所有这些情况导致的失败，都与应用程序是否真正能够正常工作毫无关系。

有一个习惯让我避免了很多麻烦：即使看起来有些多余，我也从不直接将tester.tap()与另一个交互操作连接起来，而一定会在中间添加pumpAndSettle()（或显式的pump(duration))。这个习惯对我帮助很大。

// 不稳定的情况：如果tester.tap()触发了某些异步操作（比如网络请求或动画效果），那么在这些操作完成之前，下一个find()操作就会执行，从而导致测试结果无法预测。
await tester.tap(find.byType(CheckboxListTile).first);
expect(find.textContaining('1 done'), findsOneWidget);

// 可靠的做法：要确保tester.tap()触发的所有操作都完成之后，再检查测试结果。
await tester.tap(find.byType(CheckboxListTile).first);
await tester.pumpAndSettle();
expect(find.textContaining('1 done'), findsOneWidget);

对于CI测试来说，使用真实设备来进行集成测试能够发现一些模拟器完全无法捕捉到的错误：比如权限对话框的行为差异、摄像头或生物识别功能的异常反应，以及只有在真实硬件环境下才会出现的内存压力问题。不过，这种测试方式也是最耗时且成本最高的，因此我通常会定期进行这类测试（比如每晚或在发布新版本之前），而不是在每次代码提交后都执行。

如果你的应用程序足够复杂，需要使用更高级的集成测试工具来处理复杂的逻辑流程（如原生权限管理、生物识别功能的模拟测试等），那么patrol这个工具值得你考虑。它是在integration_test的基础上开发的，增加了许多基础包所没有的功能。

各种测试类型的实际作用所在

在使用这种四层测试架构开发了几款应用程序之后，我总结了如下分配测试资源的策略及其原因：

单元测试应得到充分重视。编写和运行单元测试的成本几乎为零，而且它们是唯一能够在错误产生之前就将其发现的测试层次。任何涉及复杂逻辑的计算、过滤操作或业务逻辑处理，都应该进行单元测试。

对于那些具有多种状态界的界面，都需要进行Widget测试。界面的加载状态、错误状态和成功状态分别对应不同的代码执行路径，而错误很可能隐藏在这些不同的状态下。如果一个界面只有一种状态，那么进行Widget测试的意义就不大；但如果该界面有三种状态，那么忽略其中两种状态的测试，就相当于忽略了该界面三分之二的实际功能表现。

针对那些决定应用程序功能的核心流程，需要进行集成测试。这些测试并不追求全面性，但足以确保当所有组件真正连接在一起时，应用程序仍能正常运行。

逐渐破坏测试套件的错误

这些错误并不会立即导致构建失败，但如果不加以解决，它们会让测试套件变得越来越不可靠。就像一个结构混乱的代码库一样，虽然不会在任何一天直接引发故障，但每个月都会变得越来越难以修改。

第一个常见的错误是：对实际需要测试的对象进行模拟。我曾经看到过这样的“单元测试”：它对HTTP客户端进行了极其彻底的模拟，以至于这种测试实际上只是在验证Dio框架自带的客户端是否按照其文档中描述的方式运行而已。如果当代码中存在真实故障时，测试依然能够通过，那么这种测试就根本无法真正检验你的代码。

第二个错误是：因为设置起来比较麻烦，所以故意跳过那些可能引发故障的测试路径。在本文中提到的每一个测试场景，都会出现加载状态、错误状态和成功状态。我见过一些团队（包括我自己在早期也这么做过）只编写针对成功状态的测试，因为这些测试更容易设置。然而，错误状态恰恰是最有可能存在真实故障的地方，因为在手动测试过程中，开发者很少会去测试这些状态。

将那些偶尔会失败但重试后又能通过的测试视为需要“重新尝试”而非“修复”的对象，也是一个错误的做法。如果一个测试在二十次执行中有一次会失败，但在重试后却能通过，那么它并不是“偶尔出现故障”，而是你在代码中存在某种竞争条件问题，或者是你的测试在时间计算方面存在假设错误。如果使用持续集成工具的自动重试机制来掩盖这些问题，整个团队就会逐渐不再信任那些显示为红色的构建结果，而这个问题的严重性远远超过那个偶尔失败的测试本身。

最后，另一个错误的做法是编写那些只检验实现细节而非行为结果的测试。例如，如果一个测试检查的是`notifier._tasks.length`（一个私有字段），而不是`notifier.tasks.length`或渲染后的用户界面，那么这个测试就与一些本不应该被直接测试的内部结构紧密相关。一旦你对这些内部实现进行了重构，但实际的行为并没有改变，这个测试就会失败，而这种失败的原因与任何真正的故障都无关。

整体运行所有测试

一个`Makefile`或持续集成脚本，如果能够按顺序执行这四种类型的测试，并且先执行成本较低的测试，那么就能在那些成本较高的测试开始之前发现大多数问题：

# 首先运行这些逻辑测试，以便尽快发现逻辑错误。
flutter test test/task_logic_test.dart

# 然后测试所有界面状态下的组件行为。
flutter test test/task_screen_test.dart

# 接着检查关键界面的视觉效果是否发生变化。
flutter test test/task_screen_golden_test.dart

# 最后，在真实的设备或模拟器上运行集成测试，因为这个过程最耗时。
flutter test integration_test/complete_task_test.dart

端到端：在一个持续集成流程中完成所有四层测试

# .github/workflows/test.yml
name: 测试

on: [pull_request, push]

jobs:
  unit-and-widget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
      - run: flutter pub get
      # 单元测试和组件测试一起执行——这两种测试都很快，而且会在每个拉取请求时自动运行，无需考虑成本问题。
      - run: flutter test test/task_logic_test.dart test/task_screen_test.dart

  golden:
    runs-on: ubuntu-latest
    needs: unit-and-widget
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
      - run: flutter pub get
      - run: flutter test test/task_screen_golden_test.dart
      # 上传测试结果差异文件，这样审核人员就可以清楚地看到哪些地方发生了变化，而无需在本地拉取相关分支——这一措施能够确保“黄金标准”测试中的失败案例不会被简单地忽略或标记为“已修复”。
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: golden-diffs
          path: test/failures/

  integration:
    runs-on: macos-latest # 需要iOS模拟器；否则可以使用ubuntu和Android模拟器
    needs: golden
    if: github.ref == 'refs/heads/main' # 仅在代码合并到主分支时执行，而不是每次收到拉取请求时都运行
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
      - run: flutter pub get
      - run: flutter test integration_test/complete_task_test.dart -d "iPhone 15"

最后的思考

我第一次编写测试代码时并没有编写那个测试用例。现在我才把它写出来，同时也为每一个重要的功能都编写了相应的测试用例。其实整个关键就在于这一点：并不是说进行测试本身有什么复杂之处，而是这四种类型的测试各自都在回答其他三种类型无法解决的问题。