whale-town/tests/TEST_GUIDE.md

测试指南

🎯 测试概览

本项目包含完整的测试套件，覆盖核心系统功能。

测试类型

• 属性测试：使用随机数据验证通用属性（每个测试 50-100 次迭代）
• 单元测试：验证特定功能和边界情况
• 集成测试：测试系统间的交互

快速测试

运行所有测试（推荐）

1. 在 Godot 编辑器中打开 tests/RunAllTests.tscn
2. 按 F6 运行当前场景
3. 查看控制台输出，所有测试应该显示 ✅ PASSED
4. 测试完成后窗口会自动关闭

运行单个测试

消息协议测试：

• 打开 tests/TestRunner.tscn
• 按 F6
• 预期输出：

  [Property Test] Serialization Roundtrip
    Result: 100/100 passed
    ✅ PASSED
  [Unit Test] Message Creation
    ✅ PASSED
  [Unit Test] Message Validation
    ✅ PASSED
  

游戏状态管理器测试：

• 打开 tests/TestGameStateManager.tscn
• 按 F6
• 预期输出：

  [Unit Test] Initial State
    ✅ PASSED
  [Unit Test] State Transitions
    ✅ PASSED
  [Unit Test] State Change Signal
    ✅ PASSED
  [Unit Test] Data Persistence
    ✅ PASSED
  [Unit Test] Data Serialization
    ✅ PASSED
  

角色数据测试：

• 打开 tests/TestCharacterData.tscn
• 按 F6
• 预期输出：

  [Property Test] Character ID Uniqueness
    Result: 100 characters created, 100 unique IDs
    ✅ PASSED
  [Unit Test] Character Creation
    ✅ PASSED
  [Unit Test] Name Validation
    ✅ PASSED
  [Unit Test] Data Validation
    ✅ PASSED
  [Unit Test] Position Operations
    ✅ PASSED
  [Unit Test] Serialization Roundtrip
    ✅ PASSED
  

测试主游戏场景

运行主场景查看基础系统初始化：

1. 打开 scenes/Main.tscn
2. 按 F5 运行项目
3. 预期控制台输出：

   NetworkManager initialized
   GameStateManager initialized
   Initial state: LOGIN
   No saved player data found
   AI Town Game - Main scene loaded
   Godot version: 4.5.1-stable
   Initializing game systems...
   

测试覆盖

已测试的功能

✅ 消息协议 (test_message_protocol.gd)

• 属性测试：数据序列化往返（100次迭代）
• 单元测试：消息创建（所有类型）
• 单元测试：消息验证

✅ 游戏状态管理 (test_game_state_manager.gd)

• 单元测试：初始状态
• 单元测试：状态转换（LOGIN → CHARACTER_CREATION → IN_GAME → DISCONNECTED）
• 单元测试：状态变化信号
• 单元测试：数据持久化（保存/加载）
• 单元测试：JSON 序列化

✅ 角色数据模型 (test_character_data.gd)

• 属性测试：角色 ID 唯一性（100次迭代）
• 单元测试：角色创建
• 单元测试：名称验证（长度、空白检查）
• 单元测试：数据验证
• 单元测试：位置操作
• 单元测试：序列化往返

✅ 角色控制器 (test_character_controller.gd)

• 属性测试：碰撞检测（100次迭代）
• 属性测试：位置更新同步（100次迭代）
• 属性测试：角色移动能力（100次迭代）

✅ 输入处理器 (test_input_handler.gd)

• 属性测试：设备类型检测（100次迭代）
• 单元测试：键盘输入响应
• 单元测试：输入信号

测试统计

• 测试套件: 5 个
• 属性测试: 6 个（各 100 次迭代）
• 单元测试: 18 个
• 总测试迭代: 600+ 次

故障排除

如果测试失败

1. 检查控制台输出：查找 "FAILED" 或 "Assertion failed" 消息
2. 查看错误详情：失败的测试会显示具体的断言信息
3. 重新运行：某些测试（如 ID 唯一性）使用随机数，可以重新运行确认

常见问题

Q: 看不到测试输出？ A: 确保 Godot 的输出面板是打开的（视图 → 输出）

Q: 测试运行后立即关闭？ A: 这是正常的，查看输出面板的历史记录

Q: 某个测试一直失败？ A: 检查该测试文件的代码，可能需要调整

下一步

测试通过后，你可以：

1. 游戏测试：运行 scenes/TestGameplay.tscn 测试游戏功能
2. 启动服务器：cd server && yarn dev 启动多人服务器
3. 继续开发：参考 .kiro/specs/godot-ai-town-game/tasks.md

测试文件位置

tests/
├── RunAllTests.tscn              # 运行所有测试
├── RunPropertyTests.tscn         # 运行属性测试
├── TestGameplay.tscn             # 游戏功能测试
├── test_*.gd                     # 测试脚本
└── TEST_GUIDE.md                 # 本文档