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

🚀 运行测试

方法一：使用提供的脚本

# 运行所有pytest测试
./run_pytest.sh

方法二：直接使用uv

# 运行移动系统测试
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

方法三：运行特定测试

# 运行单个测试方法
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环境和依赖：

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

首次设置

# 创建虚拟环境并安装依赖
uv add pytest

# 验证环境
uv run pytest --version

📝 测试编写指南

测试文件命名

• 文件名：test_*.py
• 类名：Test*
• 方法名：test_*

测试结构示例

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

调试技巧

# 使用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. 边界条件：各种失败场景和错误处理

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