# 属性测试指南

## 概述

本项目实现了基于属性的测试（Property-Based Testing），用于验证游戏系统的正确性属性。属性测试通过生成大量随机输入来验证系统在各种情况下都能保持预期的行为。

## 已实现的属性测试

### 1. 属性 11: 键盘输入响应
**文件**: `tests/test_property_keyboard_input.gd`  
**场景**: `tests/TestPropertyKeyboardInput.tscn`  
**验证需求**: 5.1

**测试内容**:
- 验证所有键盘移动输入（上、下、左、右）都能正确转换为方向向量
- 验证对角线移动（组合输入）的正确性
- 运行 100+ 次迭代，测试各种输入组合

**如何运行**:
```bash
# 在 Godot 编辑器中
1. 打开场景: tests/TestPropertyKeyboardInput.tscn
2. 点击运行场景按钮（F6）
3. 查看控制台输出的测试结果
```

### 2. 属性 30: 服务器更新同步
**文件**: `tests/test_property_server_sync.gd`  
**场景**: `tests/TestPropertyServerSync.tscn`  
**验证需求**: 12.5

**测试内容**:
- 验证客户端能正确接收和处理服务器推送的更新消息
- 测试不同类型的消息（角色移动、角色状态、世界状态）
- 验证消息数据的完整性和一致性
- 运行 50 次迭代

**如何运行**:
```bash
# 在 Godot 编辑器中
1. 打开场景: tests/TestPropertyServerSync.tscn
2. 点击运行场景按钮（F6）
3. 查看控制台输出的测试结果
```

### 3. 属性 22: 在线角色显示
**文件**: `tests/test_property_online_characters.gd`  
**场景**: `tests/TestPropertyOnlineCharacters.tscn`  
**验证需求**: 11.1

**测试内容**:
- 验证所有在线玩家的角色都能正确显示在游戏场景中
- 检查角色是否在场景树中、是否可见、是否标记为在线
- 验证世界管理器正确管理所有在线角色
- 运行 50 次迭代，每次生成 1-5 个随机在线角色

**如何运行**:
```bash
# 在 Godot 编辑器中
1. 打开场景: tests/TestPropertyOnlineCharacters.tscn
2. 点击运行场景按钮（F6）
3. 查看控制台输出的测试结果
```

### 4. 属性 23: 离线角色显示
**文件**: `tests/test_property_offline_characters.gd`  
**场景**: `tests/TestPropertyOfflineCharacters.tscn`  
**验证需求**: 11.2

**测试内容**:
- 验证所有离线玩家的角色都能作为 NPC 显示在游戏场景中
- 检查离线角色是否正确标记为离线状态
- 验证离线角色不会被从世界中移除
- 运行 50 次迭代，每次生成 1-5 个随机离线角色

**如何运行**:
```bash
# 在 Godot 编辑器中
1. 打开场景: tests/TestPropertyOfflineCharacters.tscn
2. 点击运行场景按钮（F6）
3. 查看控制台输出的测试结果
```

## 运行所有属性测试

### 方法 1: 使用测试运行器（推荐）

```bash
# 在 Godot 编辑器中
1. 打开场景: tests/RunPropertyTests.tscn
2. 点击运行场景按钮（F6）
3. 测试运行器会自动运行所有属性测试并生成报告
```

### 方法 2: 逐个运行

按照上面每个测试的说明，逐个打开场景并运行。

## 测试结果解读

### 成功的测试输出示例
```
=== Property Test: Keyboard Input Response ===
Running 100 iterations...

=== Test Results ===
Total iterations: 104
Passed: 104
Failed: 0

✅ PASSED: All keyboard input responses work correctly
Property 11 validated: Keyboard inputs correctly translate to character movement
```

### 失败的测试输出示例
```
=== Property Test: Online Character Display ===
Running 50 iterations...

=== Test Results ===
Total iterations: 50
Passed: 45
Failed: 5

❌ FAILED: Some iterations failed
First 5 errors:
  Error 1: {"iteration": 12, "num_characters": 3, "errors": [...]}
  ...
```

## 属性测试的优势

1. **广泛覆盖**: 通过随机生成测试数据，能够测试到手动测试难以覆盖的边界情况
2. **自动化**: 一次编写，可以运行数百次迭代
3. **回归检测**: 确保代码修改不会破坏已有的正确性属性
4. **文档作用**: 属性测试清晰地表达了系统应该满足的不变量

## 故障排除

### 测试失败怎么办？

1. **查看错误详情**: 测试输出会显示前 5 个错误的详细信息
2. **检查相关代码**: 根据失败的属性，检查对应的实现代码
3. **单独运行失败的测试**: 使用单个测试场景进行调试
4. **添加调试输出**: 在测试代码中添加 `print()` 语句来追踪问题

### 常见问题

**Q: 测试运行很慢**  
A: 属性测试需要运行多次迭代，这是正常的。可以临时减少 `TEST_ITERATIONS` 常量来加快测试速度。

**Q: 某些测试偶尔失败**  
A: 这可能表明存在竞态条件或时序问题。检查异步操作和信号处理。

**Q: 如何添加新的属性测试？**  
A: 参考现有的测试文件，创建新的测试脚本和场景，然后添加到 `RunPropertyTests.gd` 的测试列表中。

## 持续集成

属性测试可以集成到 CI/CD 流程中：

```bash
# 使用 Godot 命令行运行测试
godot --headless --path . tests/RunPropertyTests.tscn
```

## 参考资料

- [设计文档](../.kiro/specs/godot-ai-town-game/design.md) - 查看所有正确性属性的定义
- [需求文档](../.kiro/specs/godot-ai-town-game/requirements.md) - 查看验证的需求
- [任务列表](../.kiro/specs/godot-ai-town-game/tasks.md) - 查看测试任务的状态