339 lines
14 KiB
Markdown
339 lines
14 KiB
Markdown
# 59 · QA 测试框架（QA Testing Framework）
|
||
|
||
> **命名空间** `BaseGames.QA`
|
||
> **所属文档集** [← 返回索引](./README.md) · [总览](./00_Overview.md)
|
||
> **依赖** Unity Test Framework · `BaseGames.Reliability` · `BaseGames.Analytics`
|
||
> **关联** 49_AntiSoftlockSystem · 56_CrashRecoverySystem · 46_PlatformIntegration · 29_DifficultyModesGuide
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [QA 策略总览](#1-qa-策略总览)
|
||
2. [自动化测试分层架构](#2-自动化测试分层架构)
|
||
3. [关键系统回归清单](#3-关键系统回归清单)
|
||
4. [平台认证矩阵（TCR/TRC）](#4-平台认证矩阵tcrtrc)
|
||
5. [Softlock 测试方法论](#5-softlock-测试方法论)
|
||
6. [本地化 QA 流程](#6-本地化-qa-流程)
|
||
7. [性能基准 SOP](#7-性能基准-sop)
|
||
8. [Bug 等级分类与阻塞标准](#8-bug-等级分类与阻塞标准)
|
||
9. [PlayTest 流程规范](#9-playtest-流程规范)
|
||
10. [CI/CD 质量门禁](#10-cicd-质量门禁)
|
||
|
||
---
|
||
|
||
## 1. QA 策略总览
|
||
|
||
```
|
||
QA 测试金字塔
|
||
┌─────────────┐
|
||
│ 手动 QA │ ← PlayTest / 平台认证 / 本地化审校
|
||
│ (少量，慢) │
|
||
├─────────────┤
|
||
│ 集成测试 │ ← 跨系统流程（存档↔进度、对话↔任务）
|
||
│ │
|
||
├─────────────┤
|
||
│ 单元测试 │ ← 纯逻辑（伤害计算、存档序列化、物理层）
|
||
│ (大量，快) │
|
||
└─────────────┘
|
||
```
|
||
|
||
**测试目标**：
|
||
- 发行日不存在 P0/P1 Bug
|
||
- 平台认证一次通过（不因可预期的问题而拒审）
|
||
- 关键游戏数据（存档、能力解锁）不因边界条件损坏
|
||
|
||
**QA 工具链**：
|
||
- Unity Test Framework（EditMode + PlayMode）
|
||
- Custom QA CI Runner（GitHub Actions / 本地 MSBuild）
|
||
- GameCI Docker（Unity 无头构建）
|
||
- 手动 Bug 追踪（GitHub Issues 或 Notion）
|
||
|
||
---
|
||
|
||
## 2. 自动化测试分层架构
|
||
|
||
### 2.1 EditMode 测试（纯逻辑，不需要场景）
|
||
|
||
存放路径：`Assets/Tests/EditMode/`
|
||
|
||
| 测试文件 | 覆盖内容 |
|
||
|---------|---------|
|
||
| `SaveDataSerializationTests.cs` | 存档 JSON 序列化/反序列化往返，版本迁移 |
|
||
| `DamageCalculationTests.cs` | 伤害公式、暴击、减伤计算 |
|
||
| `PhysicsLayerTests.cs` | Layer 注册正确、Collision Matrix 符合 57_PhysicsLayerMatrix |
|
||
| `EconomyTests.cs` | Geo 计算、稀有掉落保底逻辑（EconomyConfigSO）|
|
||
| `CompletionTrackerTests.cs` | 完成度积分计算，各分类加分逻辑 |
|
||
| `WorldStateRegistryTests.cs` | SetFlag/HasFlag/LoadFromSave 往返一致性 |
|
||
| `AbilityGateTests.cs` | AbilityGate 阻挡/通过逻辑 |
|
||
| `SpeedrunTimerTests.cs` | IGT 在各种暂停状态下的计时精度 |
|
||
|
||
### 2.2 PlayMode 测试（需要场景上下文）
|
||
|
||
存放路径：`Assets/Tests/PlayMode/`
|
||
|
||
| 测试文件 | 覆盖内容 |
|
||
|---------|---------|
|
||
| `PlayerMovementTests.cs` | 跳跃、冲刺、抓墙物理行为 |
|
||
| `CombatFlowTests.cs` | 攻击 → HitBox → HurtBox → 伤害 → 击退完整流程 |
|
||
| `SaveLoadCycleTests.cs` | 存档 → 读档 → 状态一致（跨场景）|
|
||
| `DialogueTriggerTests.cs` | NPC 交互 → 对话触发 → 完成 → 状态变更 |
|
||
| `SoftlockDetectorTests.cs` | SoftlockDetector 计时器触发行为 |
|
||
| `RoomTransitionTests.cs` | 场景切换、传送、存档点等场景跳转流程 |
|
||
|
||
### 2.3 测试运行命令
|
||
|
||
```bash
|
||
# 运行所有 EditMode 测试（无需 Unity 编辑器 GUI）
|
||
unity -runTests -testPlatform EditMode -projectPath . -testResults ./TestResults/EditMode.xml
|
||
|
||
# 运行所有 PlayMode 测试
|
||
unity -runTests -testPlatform PlayMode -projectPath . -testResults ./TestResults/PlayMode.xml
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 关键系统回归清单
|
||
|
||
每次发布前**必须**手动验证的核心流程（自动化未覆盖的场景）：
|
||
|
||
### 3.1 存档系统
|
||
- [ ] 存档 → 强制退出 → 重启 → 进度完整
|
||
- [ ] 在 Boss 房间内强制退出 → 重启 → 在 Boss 房间外重生（不是在 Boss 房间里）
|
||
- [ ] 3 个存档槽独立，不相互干扰
|
||
- [ ] 硬件时钟倒退后，存档时间戳不异常
|
||
- [ ] 磁盘满时，错误 UI 正常显示（手动制造磁盘满条件）
|
||
|
||
### 3.2 进度与能力
|
||
- [ ] 获得双跳后，双跳立即可用（不需要重启）
|
||
- [ ] 冲刺能力解锁后，冲刺 AbilityGate 正确开启
|
||
- [ ] NG+ 开始后，继承列表中的能力/符文完整
|
||
- [ ] NG+ 不继承 Boss 状态（Boss 重置为未击败）
|
||
|
||
### 3.3 地图与世界
|
||
- [ ] 所有房间首次进入后，地图正确标记
|
||
- [ ] 地图上的 NPC 图标随 NPC 迁移而更新
|
||
- [ ] 商店库存随进度解锁
|
||
- [ ] 所有房间都能从入口正常进入/退出（无穿模）
|
||
|
||
### 3.4 战斗
|
||
- [ ] 攻击 HitBox 在各方向正确（上攻/下攻/左右攻方向一致）
|
||
- [ ] 弹反判定窗口与动画帧同步
|
||
- [ ] Boss 各阶段转场正确（不跳相）
|
||
- [ ] 死亡 → Geo 掉落 → 拾取 Geo 恢复
|
||
- [ ] 永久死亡（Geo 无法恢复）的边界条件（掉入深渊底部）
|
||
|
||
### 3.5 对话与叙事
|
||
- [ ] 关键 NPC 的对话版本随世界状态标志正确切换
|
||
- [ ] 长对话跳过后，剧情标志仍然正确设置
|
||
- [ ] 侧任务完成条件满足后，任务 UI 正确完成
|
||
|
||
---
|
||
|
||
## 4. 平台认证矩阵（TCR/TRC）
|
||
|
||
> 每个平台的具体认证要求参见 46_PlatformIntegration.md §4。本表列出常见拒审原因及对应测试项。
|
||
|
||
| 平台 | 常见拒审原因 | 测试项 |
|
||
|------|-----------|-------|
|
||
| **Steam** | 游戏崩溃 / 卡死 / 无响应 | 4小时稳定性测试（各区域循环游玩）|
|
||
| | 成就不触发 | 每个成就手动验证触发条件 |
|
||
| | 截图库无截图 / 描述不准确 | 按 Steam 商店指南核对资产 |
|
||
| **Nintendo Switch** | 休眠后无法恢复（挂起/恢复） | 在各游戏状态下触发 Switch 休眠，恢复后验证 |
|
||
| | 控制器断开后崩溃 | 运行时拔出 Joy-Con，验证提示 UI |
|
||
| | 未使用 Switch 按钮图标 | 检查所有操作提示图标（A/B/X/Y 不用 XBox 图标）|
|
||
| | 本地多人存档不隔离 | 多用户账号分别进行存档验证 |
|
||
| | Home Menu 警告文本缺失 | 检查所有 Modal 有无必要的 Home Menu 提示 |
|
||
| **PlayStation** | 数据管理要求（自动存档） | TRC T-09X 系列：自动存档符合 TCR |
|
||
| | 奖杯不解锁 / 解锁过多重复 | 每个奖杯手动验证，确认不重复触发 |
|
||
| | 营销资产规格不符 | 按 PlayStation 素材规格核对 |
|
||
|
||
### Switch 强制测试项
|
||
|
||
```
|
||
测试: 挂起/恢复 (Suspend/Resume)
|
||
环境: 在以下每种状态下触发 Switch 休眠键
|
||
- 主菜单
|
||
- 正常游玩（普通房间）
|
||
- Boss 战中
|
||
- 过场动画播放中
|
||
- 存档中（SaveIndicator 可见时）
|
||
- 加载中（黑屏过渡）
|
||
预期结果: 恢复后游戏完整可用，无崩溃，无数据丢失
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Softlock 测试方法论
|
||
|
||
> 配合 49_AntiSoftlockSystem.md §6 的 `EscapeGuaranteeValidator` 工具使用。
|
||
|
||
### 5.1 自动化检查（EditorWindow BFS）
|
||
|
||
1. 打开 `Tools → Zeling → Escape Guarantee Validator`
|
||
2. 点击"Run All Rooms"，工具遍历所有房间的 `RoomEscapeInfoSO`
|
||
3. 检查是否每个房间都有对应所有能力状态的逃生路线
|
||
|
||
### 5.2 手动 Softlock 测试清单
|
||
|
||
| 测试场景 | 操作步骤 | 预期行为 |
|
||
|---------|---------|---------|
|
||
| 无能力状态进入任何房间 | 使用 Debug 模式删除全部能力，进入目标房间 | SoftlockDetector 45s 后触发，传送选项出现 |
|
||
| 被敌人推入凹陷地形 | 找到地图中所有凹形地形，测试是否可逃出 | 能跳出，或跌落重生 |
|
||
| Boss 房间门关闭后能力丢失 | 进入 Boss 房间 → 通过 Debug 移除 Dash → Boss 死亡门未开 | SoftlockDetector 触发，或 Boss 房间门有保底开门逻辑 |
|
||
| 液体区域无游泳能力 | 进入液体区域，移除游泳能力 | 玩家在液体中逐渐失血，死亡后正常重生（不卡死）|
|
||
| AbilityGate 入口无出口 | 进入 AbilityGate 保护的区域，然后条件不满足 | 区域内必须有出口或逃生路线（EscapeGuaranteeValidator 保证）|
|
||
|
||
---
|
||
|
||
## 6. 本地化 QA 流程
|
||
|
||
### 6.1 支持语言列表
|
||
|
||
| 语言 | 代码 | 审核负责人 |
|
||
|------|------|---------|
|
||
| 简体中文（主语言）| zh-CN | 内部团队 |
|
||
| 繁体中文 | zh-TW | 外包审校 |
|
||
| 英文 | en | 外包翻译 + 内部审核 |
|
||
| 日文 | ja | 外包翻译（必须含母语审校）|
|
||
| 韩文 | ko | 外包翻译（建议）|
|
||
|
||
### 6.2 本地化 QA 检查项
|
||
|
||
- [ ] **文本溢出**：所有 UI 文本在最长翻译（通常是德文/日文）下不溢出容器
|
||
- [ ] **字体覆盖**：所有语言的特殊字符正确显示（日文假名、韩文字符、中文繁体异体字）
|
||
- [ ] **语境正确性**：道具名称/NPC 名称在句子中语法正确（特别是日语助词）
|
||
- [ ] **图像内文字**：所有包含硬编码文字的图像都有对应语言版本
|
||
- [ ] **音频字幕同步**：过场动画字幕与原声音频时间轴对齐（±0.5s 内）
|
||
- [ ] **数字格式**：货币、日期格式符合各地区习惯（如日文不用逗号分隔千位数）
|
||
|
||
### 6.3 本地化自动检查工具
|
||
|
||
```csharp
|
||
// 在 CI 中运行 LocalizationAuditTool，自动检测：
|
||
// 1. 所有本地化 Key 都有对应翻译（无缺失 Key）
|
||
// 2. 无翻译超过容器字数限制（基于 Font Asset + TextMeshPro 计算）
|
||
// 3. 所有音频 Key 对应的音频文件存在
|
||
LocalizationAuditTool.RunAudit(outputPath: "./TestResults/LocalizationAudit.html");
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 性能基准 SOP
|
||
|
||
### 7.1 目标平台性能指标
|
||
|
||
| 平台 | 目标帧率 | 允许最低帧率 | 内存上限 |
|
||
|------|---------|-----------|---------|
|
||
| PC（中端，GTX 1060）| 60 FPS | 45 FPS（极端粒子特效）| 2 GB RAM |
|
||
| PC（低端，集成显卡）| 30 FPS（低质量预设）| 25 FPS | 1.5 GB RAM |
|
||
| Nintendo Switch（TV 模式）| 60 FPS | 50 FPS | 3.5 GB RAM |
|
||
| Nintendo Switch（手持模式）| 60 FPS | 45 FPS | 3.5 GB RAM |
|
||
|
||
### 7.2 性能测试标准场景
|
||
|
||
每次大版本发布前在以下场景运行 5 分钟帧率采样：
|
||
|
||
| 场景 | 测试内容 |
|
||
|------|---------|
|
||
| `Scene_Forest_Main`（大地图）| 正常游玩，含大量背景层植被 |
|
||
| `Scene_Cave_BossArena`（Boss 战）| Abyss Boss 第3阶段（最多粒子特效）|
|
||
| `Scene_Core_Final`（最终区域）| 最多光照/后处理 |
|
||
| `Scene_StressTest_500Enemies`（压测）| 人工压测场景，500个激活敌人 |
|
||
|
||
### 7.3 性能基准工具
|
||
|
||
```csharp
|
||
// 在场景中放置 PerformanceBenchmarkRunner 组件
|
||
// 运行后输出 CSV：帧率、CPU ms、GPU ms、内存、DrawCall 等
|
||
[RequireComponent(typeof(Camera))]
|
||
public class PerformanceBenchmarkRunner : MonoBehaviour
|
||
{
|
||
[SerializeField] float testDurationSeconds = 300f;
|
||
[SerializeField] string outputPath = "TestResults/Performance/";
|
||
|
||
// 每帧记录 FrameTimingManager 数据，结束后输出 CSV
|
||
}
|
||
```
|
||
|
||
### 7.4 内存泄漏检测 SOP
|
||
|
||
1. 打开 Unity Memory Profiler（包名：`com.unity.memoryprofiler`）
|
||
2. 在 `Scene_Forest_Main` 游玩 10 分钟，每隔 2 分钟截取一次内存快照
|
||
3. 比较前后快照，检查 `MonoBehaviour` / `Texture2D` / `AudioClip` 是否持续增长
|
||
4. 重点检查：切换场景后旧场景的 Addressable 资源是否正确卸载
|
||
|
||
---
|
||
|
||
## 8. Bug 等级分类与阻塞标准
|
||
|
||
| 等级 | 定义 | 示例 | 发布阻塞 |
|
||
|------|------|------|---------|
|
||
| **P0（致命）** | 导致游戏无法进行，数据丢失，或认证不通过 | 存档损坏、游戏崩溃、平台认证必需功能缺失 | 🔴 必须修复后方可发布 |
|
||
| **P1（严重）** | 游戏流程卡死，主线任务无法完成 | Softlock、Boss 无敌、主线对话不触发 | 🔴 必须修复后方可发布 |
|
||
| **P2（主要）** | 功能异常但有规避方法，或影响较大的视觉/音频 Bug | 支线任务 Bug、成就不触发、音频缺失 | 🟡 目标修复，首发前尽力解决 |
|
||
| **P3（次要）** | 小视觉 Bug，不影响游戏性 | 个别图层 z-order 错误、UI 文字截断 | 🟢 可首发后热更新 |
|
||
| **P4（优化）** | 性能问题或用户体验改善建议 | 帧率偶尔下降、操作手感微调 | 🟢 可后续版本跟进 |
|
||
|
||
---
|
||
|
||
## 9. PlayTest 流程规范
|
||
|
||
### 9.1 内部 PlayTest
|
||
|
||
| 阶段 | 时机 | 目标 | 参与者 |
|
||
|------|------|------|--------|
|
||
| **Alpha PlayTest** | 核心系统完成后 | 核心游戏循环验证，P0/P1 Bug 猎杀 | 开发团队 |
|
||
| **Beta PlayTest** | 内容完整后 | 完整流程通关，难度曲线，本地化初检 | 团队 + 10~20 名外部测试者 |
|
||
| **Pre-cert PlayTest** | 提交平台认证前 2 周 | 模拟平台认证检查，平台合规 | 专注平台认证的 QA |
|
||
| **Gold Candidate** | 发行前 1 周 | 最终回归，P0/P1 清零确认 | 全团队 |
|
||
|
||
### 9.2 PlayTest 问卷（标准版）
|
||
|
||
外部 PlayTest 结束后必须填写：
|
||
|
||
1. 整体评分（1~10）
|
||
2. 操作手感评分（1~10）
|
||
3. 难度评分（太简单 / 刚好 / 太难）
|
||
4. 是否遇到 Bug？（是/否，详细描述）
|
||
5. 是否遇到不明白如何继续的情况？（描述卡关位置）
|
||
6. 最喜欢的部分是什么？
|
||
7. 最不喜欢的部分是什么？
|
||
8. 游玩时长
|
||
|
||
---
|
||
|
||
## 10. CI/CD 质量门禁
|
||
|
||
所有 PR 合并前必须通过以下自动化检查（GitHub Actions）：
|
||
|
||
```yaml
|
||
# .github/workflows/qa.yml（示例结构）
|
||
quality_gates:
|
||
- name: Unity Build (PC)
|
||
command: unity -buildTarget StandaloneWindows64 -batchmode -quit
|
||
fail_on: build_error
|
||
|
||
- name: EditMode Tests
|
||
command: unity -runTests -testPlatform EditMode
|
||
fail_on: any_test_failure
|
||
|
||
- name: Localization Audit
|
||
command: dotnet run --project Tools/LocalizationAudit
|
||
fail_on: missing_keys | overflow_detected
|
||
|
||
- name: Physics Layer Validation
|
||
command: unity -runTests -testPlatform EditMode -testFilter PhysicsLayerTests
|
||
fail_on: any_test_failure
|
||
|
||
- name: Code Coverage (minimum 60%)
|
||
command: unity -runTests -enableCodeCoverage
|
||
fail_on: coverage_below_60_percent
|
||
```
|
||
|
||
**门禁规则**：任何门禁失败，PR 不可合并，必须修复后重新提交。
|
||
|
||
---
|
||
|
||
*本文档版本 1.0 · 2026-04 · 关联 49_AntiSoftlockSystem / 56_CrashRecoverySystem / 46_PlatformIntegration*
|