Name: dart-add-unit-test
Author: flutter

Dart 与 Flutter 应用测试指南

组织测试文件目录

按照 lib 目录结构来组织测试文件，保持代码结构的可预测性。

将所有测试代码统一放在包（Package）根目录下的 test 文件夹中。
所有测试文件名结尾必须加上 _test.dart（例如 lib/src/utils.dart 对应的测试文件应为 test/src/utils_test.dart）。
如果编写集成测试，请将其放在包根目录下的 integration_test 文件夹中。

编写测试

使用 package:test 作为 Dart 应用的标准测试库。

引入 package:test/test.dart（如果是 Flutter 项目，则引入 package:flutter_test/flutter_test.dart）。
使用 group() 函数对相关测试进行分组，提供共享的上下文。
使用 test() 函数定义单个测试用例。
使用 expect() 函数配合 Matcher（如 equals()、isTrue、throwsA()）验证测试结果。
使用标准的 async/await 语法编写异步测试，测试运行器会自动等待 Future 执行完成。
使用 setUp() 和 tearDown() 回调管理测试前置准备与后置清理。
如果测试代码依赖依赖注入，可结合使用 package:mockito 与 package:test 来生成 Mock 对象、配置固定场景并验证交互逻辑。

执行测试

根据项目类型和测试文件位置选择合适的测试运行器（Test Runner）。

如果是纯 Dart 项目，使用 dart test 命令执行测试。
如果是 Flutter 项目，使用 flutter test 命令执行测试。
如果运行集成测试，需要显式指定目录路径，因为默认运行器会忽略该目录：dart test integration_test 或 flutter test integration_test。

测试实现工作流

在实现新的测试套件时，请遵循以下流程。你可以复制该清单来追踪进度。

任务进度

[ ] 1. 在 test/ 目录下创建测试文件，确保包含 _test.dart 后缀。
[ ] 2. 引入 package:test/test.dart 和目标库。
[ ] 3. 定义 main() 函数。
[ ] 4. 使用 setUp() 初始化共享资源或 Mock 对象。
[ ] 5. 使用 group() 按功能分组编写 test() 用例。
[ ] 6. 使用对应的 CLI 命令执行测试套件。
[ ] 7. 反馈循环：运行测试 -> 查看失败堆栈信息 -> 修复实现代码或断言 -> 重新运行直到全部通过。

代码示例

标准单元测试套件

演示分组、初始化、同步及异步测试写法。

import 'package:test/test.dart';
import 'package:my_package/calculator.dart';

void main() {
  group('Calculator', () {
    late Calculator calc;

    setUp(() {
      calc = Calculator();
    });

    test('adds two numbers correctly', () {
      expect(calc.add(2, 3), equals(5));
    });

    test('handles asynchronous operations', () async {
      final result = await calc.fetchRemoteValue();
      expect(result, isNotNull);
      expect(result, greaterThan(0));
    });
  });
}

使用 Mockito 进行 Mock 测试

演示如何为依赖注入测试配置 Mock 对象。

import 'package:test/test.dart';
import 'package:mockito/mockito.dart';
import 'package:mockito/annotations.dart';
import 'package:my_package/api_client.dart';
import 'package:my_package/data_service.dart';

// 使用 build_runner 生成 Mock：dart run build_runner build
@GenerateNiceMocks([MockSpec<ApiClient>()])
import 'data_service_test.mocks.dart';

void main() {
  group('DataService', () {
    late MockApiClient mockApiClient;
    late DataService dataService;

    setUp(() {
      mockApiClient = MockApiClient();
      dataService = DataService(apiClient: mockApiClient);
    });

    test('returns parsed data on successful API call', () async {
      // 配置 Mock 行为
      when(mockApiClient.get('/data')).thenAnswer((_) async => '{"id": 1}');

      // 执行待测系统
      final result = await dataService.fetchData();

      // 验证结果与交互行为
      expect(result.id, equals(1));
      verify(mockApiClient.get('/data')).called(1);
    });
  });
}

dart-add-unit-test

相关 Skills