flutter-testing

Flutter + NestJS 测试规范 Skill

适用于多区域 Flutter + NestJS 项目的测试基线。所有 <PLACEHOLDER> 替换为项目实际值。

本 skill 与 CI 强绑定：测试写完必须进 CI 门禁才有意义，CI 矩阵见 ~/.claude/skills/ci-cd-github-actions/SKILL.md。多区域项目最易漏测的就是 flavor 条件编译（第 6 节），必看。

1. 测试金字塔与原则

        ╱╲   e2e（少）—— 后端 supertest 打真实 HTTP + 测试库；关键业务链路
       ╱──╲
      ╱widget╲  widget（中）—— 页面渲染 / 交互 / 空态 / 加载态
     ╱────────╲
    ╱   unit    ╲ unit（多）—— Notifier 业务逻辑 / util / Service 纯逻辑
   ╱────────────╲

该测 / 不该测：

• ✅ 必测：业务规则（积分扣费/退款、多租户 where 过滤、切租户重置、语言归一）、flavor 工厂选择、错误分支（余额不足、越权、race 守卫）、数据映射（Freezed ↔ JSON）
• ✅ 建议测：关键 widget 的空态 CTA、加载骨架、向导 exit guard、i18n key 不缺失
• ❌ 不必测：纯 UI 布局像素（golden 覆盖即可）、第三方 SDK 内部、Freezed/json_serializable 生成代码、getter/setter
• ★ 禁止：为了覆盖率写无断言的假测试；测试里连真实生产后端 / 真实第三方 AI（用 mock）

2. Flutter 依赖与目录

pubspec.yaml dev_dependencies：

dev_dependencies:
  flutter_test:
    sdk: flutter
  mocktail: ^1.0.0          # mock（不需要 codegen，优于 mockito）
  golden_toolkit: ^0.15.0   # golden（可选）
  network_image_mock: ^2.1.1 # widget 测试里拦截 CachedNetworkImage

目录（与 lib/ 镜像）：

test/
├── unit/
│   ├── providers/        # Notifier / Provider 业务逻辑
│   ├── services/         # API service（mock Dio）
│   ├── utils/            # normalizeBusinessLanguageCode / date / locale
│   └── config/           # ★ flavor 工厂选择（第 6 节）
├── widget/               # 页面 / 组件渲染与交互
├── golden/               # golden 基准图
└── helpers/
    ├── pump_app.dart     # 统一 pumpWidget（注入 ProviderScope + l10n + theme）
    └── mocks.dart        # 共享 mock 类

3. Notifier / Provider 单元测试（ProviderContainer + override）

核心模式：用 ProviderContainer + overrideWith 注入 mock 依赖，直接驱动 Notifier，不启 UI。

// test/unit/providers/credits_provider_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:mocktail/mocktail.dart';

class MockCreditsApi extends Mock implements CreditsApiService {}

void main() {
  late MockCreditsApi api;

  setUp(() => api = MockCreditsApi());

  ProviderContainer makeContainer() => ProviderContainer(
        overrides: [creditsApiProvider.overrideWithValue(api)],
      );

  test('扣费成功后余额减少', () async {
    when(() => api.consume(any(), any(), any()))
        .thenAnswer((_) async => ConsumeResult(balance: 80));
    final c = makeContainer();
    addTearDown(c.dispose);

    await c.read(creditsProvider.notifier).consume('A1', 'generate', 20);

    expect(c.read(creditsProvider).balance, 80);
  });

  test('★ AI 调用失败必须触发退款（refundWithRetry）', () async {
    when(() => api.consume(any(), any(), any()))
        .thenAnswer((_) async => ConsumeResult(balance: 80));
    when(() => api.callAI(any())).thenThrow(Exception('upstream 500'));
    when(() => api.refundWithRetry(any(), any(), maxRetry: any(named: 'maxRetry')))
        .thenAnswer((_) async {});
    final c = makeContainer();
    addTearDown(c.dispose);

    await expectLater(
      c.read(someToolProvider.notifier).generate(),
      throwsA(isA<Exception>()),
    );
    // ★ 断言退款一定被调用一次（对应 _shared/rules.md §1 双保险）
    verify(() => api.refundWithRetry(20, any(), maxRetry: 3)).called(1);
  });
}