testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Testing Strategy

测试策略

Test Pyramid: More unit and widget tests, fewer integration tests. Unit tests are fastest and cheapest.
Mirror Test Rule: 100% logic and widget coverage. No code without a test.
Mirror Organization: Test files MUST strictly mirror the
```
lib/
```
directory structure and end with
```
_test.dart
```
.
Coverage Targets: Target 100% logic coverage for
```
domain
```
and
```
bloc
```
layers.
Test Independence: Each test MUST be independent. No shared mutable state between tests.

测试金字塔：多写单元测试和widget测试，少写集成测试。单元测试速度最快、成本最低。
镜像测试规则：实现100%的逻辑和widget覆盖率，不存在无测试的代码。
镜像组织结构：测试文件必须严格镜像
```
lib/
```
目录结构，且以
```
_test.dart
```
结尾。
覆盖率目标：
```
domain
```
层和
```
bloc
```
层的逻辑覆盖率目标为100%。
测试独立性：每个测试必须独立，测试之间不能共享可变状态。

Unit Testing

单元测试

Follow the Arrange-Act-Assert (Given-When-Then) convention for clear and maintainable tests
Use mocks for dependencies except for lightweight third-party services
Test business logic in isolation from the UI
For tests, ensure to create 5 to 8 tests for logical operations with real scenarios
Mocking Protocol: Use
```
mocktail
```
for all dependency mocking. STRICTLY prohibit using real implementation dependencies in unit tests.
Pure Logic: Business logic inside BLoCs or UseCases should be extracted to static pure functions for 100% unit test coverage.

遵循Arrange-Act-Assert（Given-When-Then）规范，保证测试清晰易维护
依赖项使用mock，轻量第三方服务除外
业务逻辑测试要与UI隔离
针对逻辑操作，需结合真实场景编写5到8个测试用例
Mock规范：所有依赖项的mock都使用
```
mocktail
```
，严格禁止在单元测试中使用真实实现的依赖
纯逻辑要求：BLoC或UseCase中的业务逻辑应提取为静态纯函数，以实现100%的单元测试覆盖率

Widget Testing

Widget测试

Write widget tests for all major UI components
Test user interactions and state changes
Widget Keys: Use
```
Key('feature_action_id')
```
format on interactive widgets for test access
Test Localization: Use
```
AppLocalizations
```
(
```
context.l10n
```
) in widget tests — no hardcoded strings

为所有核心UI组件编写widget测试
测试用户交互和状态变化
Widget Key规范：在可交互widget上使用
```
Key('feature_action_id')
```
格式的命名，方便测试访问
本地化测试：在widget测试中使用
```
AppLocalizations
```
（
```
context.l10n
```
），禁止硬编码字符串

Integration Testing

集成测试

Use

IntegrationTestWidgetsFlutterBinding.ensureInitialized()

at the start of integration tests

Interact with widgets via

Key

(e.g.,

find.byKey(const ValueKey('increment'))

)

Use
```
pumpAndSettle()
```
to wait for animations and async operations to complete
Run with:
```
flutter test integration_test/
```

集成测试开头需要调用

IntegrationTestWidgetsFlutterBinding.ensureInitialized()

通过

Key

和widget交互（例如

find.byKey(const ValueKey('increment'))

）

使用
```
pumpAndSettle()
```
等待动画和异步操作执行完成
运行命令：
```
flutter test integration_test/
```

Test Naming & Structure

测试命名与结构

Test Naming: Use string interpolation for test group names:
```
group('$ClassName',
```
not
```
group('ClassName',
```
. This ensures consistency and enables better tooling support.
Test Grouping: Use
```
group()
```
to organize tests by feature, class, or state for clearer reporting.
Descriptive Names: Test names should clearly describe what is being tested and why.

测试命名：测试组名称使用字符串插值：
```
group('$ClassName',
```
而非
```
group('ClassName',
```
，这样可以保证一致性，获得更好的工具支持
测试分组：使用
```
group()
```
按功能、类或状态组织测试，让测试报告更清晰
描述性命名：测试名称应清晰描述测试对象和测试目的

Common Test Errors

常见测试错误

```
A RenderFlex overflowed...
```
— Wrap widget in
```
Expanded
```
or constrain dimensions in test

Vertical viewport was given unbounded height

— Wrap

ListView

SizedBox

with fixed height in test

```
setState called during build
```
— Defer state changes to post-frame callback

```
A RenderFlex overflowed...
```
— 测试中把widget包裹在
```
Expanded
```
中，或者限制其尺寸

Vertical viewport was given unbounded height

— 测试中把

ListView

包裹在固定高度的

SizedBox

中

```
setState called during build
```
— 把状态变更延迟到帧后回调中执行

Running Tests

运行测试

```
flutter test
```
— Run all unit and widget tests

flutter test test/path/to/file_test.dart

— Run specific test file

```
flutter test integration_test/
```
— Run integration tests
```
flutter test --coverage
```
— Run with coverage report

```
flutter test
```
— 运行所有单元测试和widget测试

flutter test test/path/to/file_test.dart

— 运行指定的测试文件

```
flutter test integration_test/
```
— 运行集成测试
```
flutter test --coverage
```
— 运行测试并生成覆盖率报告