kards-env/docs/TESTING.md

# KARDS Battle System - Testing Guide

## 📋 测试概述

项目包含全面的pytest测试套件，确保所有核心功能的正确性和稳定性。

## 🧪 测试套件

### 移动系统测试 (`test_comprehensive_movement.py`)
涵盖所有移动场景和边界条件：

**成功场景：**
- ✅ 移向空的前线占领前线
- ✅ 移向有己方的前线，进入空格  
- ✅ 移向有己方的前线，挤占已有位置
- ✅ 移动消耗正确的Kredits

**失败场景：**
- ❌ 前线移向敌方阵线（应失败）
- ❌ 前线已满时移向前线（应失败）
- ❌ 前线有敌人时移向前线空地（应失败）
- ❌ 前线单位不能在前线内移动
- ❌ Kredits不足时移动失败
- ❌ 非当前回合无法移动

### 回合流逝和资源系统测试 (`test_turn_and_resources.py`)
验证资源管理和回合机制：

**资源系统：**
- ✅ 随回合Slots增加，Kredits补满
- ✅ Kredits Slot达到12时不再自动增加
- ✅ Kredits超过24时自动设为24（绝对上限）
- ✅ 每回合Kredits重置为Slot数值

**回合系统：**
- ✅ 回合阶段正确轮换 (0→1→0→1...)
- ✅ 双方在各自阶段都获得正确资源
- ✅ 正确扣除和验证Kredits

## 🚀 运行测试

### 方法一：使用提供的脚本
```bash
# 运行所有pytest测试
./run_pytest.sh
```

### 方法二：直接使用uv
```bash
# 运行移动系统测试
uv run pytest tests/test_comprehensive_movement.py -v

# 运行回合和资源测试  
uv run pytest tests/test_turn_and_resources.py -v

# 运行所有新测试
uv run pytest tests/test_comprehensive_movement.py tests/test_turn_and_resources.py -v
```

### 方法三：运行特定测试
```bash
# 运行单个测试方法
uv run pytest tests/test_comprehensive_movement.py::TestMovementScenarios::test_move_to_empty_frontline_occupies_control -v

# 运行特定测试类
uv run pytest tests/test_turn_and_resources.py::TestTurnProgression -v
```

## 📊 测试统计

| 测试套件 | 测试数量 | 状态 |
|---------|----------|------|
| 移动系统测试 | 10个 | ✅ 全部通过 |
| 回合和资源系统测试 | 9个 | ✅ 全部通过 |
| **总计** | **19个** | **✅ 全部通过** |

## 🔧 环境要求

项目使用uv管理Python环境和依赖：

```toml
[project]
dependencies = [
    "pytest>=8.4.1",
]
```

### 首次设置
```bash
# 创建虚拟环境并安装依赖
uv add pytest

# 验证环境
uv run pytest --version
```

## 📝 测试编写指南

### 测试文件命名
- 文件名：`test_*.py`
- 类名：`Test*`
- 方法名：`test_*`

### 测试结构示例
```python
class TestFeatureName:
    def setup_method(self):
        """每个测试前的设置"""
        self.engine = BattleEngine("Germany", "USA", debug_mode=True)
        
    def test_specific_behavior(self):
        """测试：具体行为描述"""
        # Arrange - 准备测试数据
        unit = create_german_infantry()
        
        # Act - 执行被测试的操作
        result = self.engine.deploy_unit_to_support(unit, 0)
        
        # Assert - 验证结果
        assert result['success']
        assert result['position'] == 1
```

### 调试技巧
```python
# 使用debug模式创建引擎
engine = BattleEngine("Germany", "USA", debug_mode=True)

# 设置测试资源
engine.debug_set_kredits(0, kredits=10)

# 查看战场状态
print(engine.battlefield)
```

## 🎯 覆盖的核心功能

测试套件验证了以下核心系统：

1. **战场系统**：3线布局、单位位置、前线控制
2. **移动系统**：所有移动规则和限制条件
3. **资源系统**：Kredits Slot增长、Kredits消耗和限制
4. **回合系统**：阶段轮换、资源重置
5. **权限系统**：回合权限、操作验证
6. **边界条件**：各种失败场景和错误处理

这确保了系统的健壮性和可靠性。