# Zeling v2 · 测试方案总索引

> **文档版本**：1.0  
> **创建日期**：2026-05-13  
> **覆盖范围**：`Assets/Scripts/` 全量代码  
> **Unity 版本**：2022.3 LTS  
> **测试框架**：Unity Test Framework（NUnit）

---

## 一、测试策略概述

本项目测试分为两大类：

### 1.1 单元测试（EditMode / 代码测试）

凡满足以下条件之一的逻辑，**必须编写 NUnit 单元测试**：

- 纯 C# 类（无 `MonoBehaviour` 继承），逻辑完全与 Unity 运行时解耦
- 有明确输入/输出的算法（序列化、状态机转换、数值计算）
- 可通过 Mock / Stub 隔离 Unity 依赖的组件

测试文件存放于 `Assets/Tests/EditMode/`，程序集 `BaseGames.Tests.EditMode`。

### 1.2 手动测试（Unity Editor Play Mode）

需要在 Unity Editor 中运行 Play Mode 的场景验证：

- 动画状态机（Animancer FSM）与物理交互
- HitBox/HurtBox 碰撞判定
- 敌人 AI 行为（Behavior Designer）
- 场景切换与相机系统
- VFX/Feedback 链路

### 1.3 测试前必做环境检查

每次进行任何测试前，请先完成以下检查：

| 检查项 | 操作 |
|--------|------|
| Console 无红色 Error | `Window → General → Console`，Error 数量 = 0 |
| Addressables 已构建 | `Window → Asset Management → Addressables → Groups → Build → New Build → Default Build Script` |
| NavSurface 已烘焙 | 选中 NavSurface GameObject → Inspector → Bake，Scene 视图显示蓝绿网格 |
| SO 事件资产已生成 | `BaseGames → Tools → Create Event Channel Assets`，`Assets/Data/Events/` 下存在 `.asset` 文件 |
| Physics2D Layer 矩阵已配置 | `Edit → Project Settings → Physics 2D` → PlayerHitBox ↔ EnemyHurtBox 开启碰撞 |

---

## 二、文档列表

### 单元测试文档（包含可直接运行的 C# 测试代码）

| 文档 | 覆盖模块 | 测试类型 |
|------|---------|---------|
| [01_Unit_EventSystem_ServiceLocator.md](01_Unit_EventSystem_ServiceLocator.md) | SO 事件系统、ServiceLocator、CompositeDisposable | EditMode 单元测试 |
| [02_Unit_SaveSystem.md](02_Unit_SaveSystem.md) | SaveMigrator、SaveData 序列化、Checksum | EditMode 单元测试 |
| [03_Unit_StatusEffects.md](03_Unit_StatusEffects.md) | StatusEffect 叠加/互斥/到期（扩展现有测试） | EditMode 单元测试 |
| [04_Unit_GameStateMachine.md](04_Unit_GameStateMachine.md) | GameStateMachine 状态注册/转换/非法转换 | EditMode 单元测试 |

### 手动测试文档（Unity Editor Play Mode 操作步骤）

| 文档 | 覆盖模块 | 测试类型 |
|------|---------|---------|
| [05_Manual_Core_Infrastructure.md](05_Manual_Core_Infrastructure.md) | ServiceLocator 初始化、ObjectPool、Addressables | Play Mode 手动 |
| [06_Manual_PlayerFSM_Movement.md](06_Manual_PlayerFSM_Movement.md) | 玩家 FSM、移动、跳跃、冲刺、蹬墙、治疗 | Play Mode 手动 |
| [07_Manual_CombatSystem.md](07_Manual_CombatSystem.md) | 战斗管道、弹反、护盾、霸体、状态效果 | Play Mode 手动 |
| [08_Manual_EnemySystem.md](08_Manual_EnemySystem.md) | 敌人 AI、寻路、远程/飞行/Boss | Play Mode 手动 |
| [09_Manual_WorldSystem.md](09_Manual_WorldSystem.md) | 房间切换、互动机关、液态谜题、存档点 | Play Mode 手动 |
| [10_Manual_ProgressionSystem.md](10_Manual_ProgressionSystem.md) | 技能/护符/任务/成就/商店/形态切换 | Play Mode 手动 |
| [11_Manual_UIAudioVFX.md](11_Manual_UIAudioVFX.md) | HUD、UI 面板、音频 Mixer、VFX/Feedback | Play Mode 手动 |
| [12_Manual_CameraSystem.md](12_Manual_CameraSystem.md) | 区域相机切换、CinemachineConfiner、屏幕抖动 | Play Mode 手动 |
| [13_Manual_PlayerAbilities_Skills.md](13_Manual_PlayerAbilities_Skills.md) | 攻击三连击/上劈/下劈Pogo/空中攻击、抓墙/蹬墙跳、二段跳、无敌冲刺、三形态切换、三套资源、灵泉使用/充能、魂技能/魄技能、弹反 | Play Mode 手动 |

---

## 三、运行单元测试

1. 打开 Unity Editor
2. 菜单 `Window → General → Test Runner`
3. 在 **Test Runner** 窗口选择 `EditMode` 标签页
4. 点击 `Run All` 或展开 `BaseGames.Tests.EditMode` 运行指定测试套件
5. 所有测试应显示 **绿色勾**，无红色失败

### 新增测试文件操作

1. 在 `Assets/Tests/EditMode/` 下创建新的 `.cs` 文件
2. 确保文件头部有正确命名空间和 `[TestFixture]` 特性
3. 确保 `.asmdef` 引用了被测程序集（见各单元测试文档说明）

---

## 四、缺陷登记

发现问题时，在下表记录：

| BUG-ID | 模块 | 描述 | 复现步骤 | 严重程度 | 状态 |
|--------|------|------|---------|---------|------|
| BUG-001 | | | | P0/P1/P2/P3 | 开放/修复 |