---
name: gameplay_unit_test.aivalidator
description: 路径消除玩法的纯逻辑单元测试框架。使用 vitest 测试 LevelParser、碰撞检测、消除规则、胜负条件，不依赖 Phaser 或浏览器。
triggers: 单元测试,unit test,vitest,测试玩法,测试逻辑,验证消除规则,test gameplay
---

# 玩法逻辑单元测试（Gameplay Unit Tests）

## 说明

为路径消除玩法的核心逻辑提供**纯函数单元测试**：

- 不依赖 Phaser（不需要浏览器或 Canvas）
- 不依赖 DOM（纯 Node.js 环境运行）
- 测试覆盖：坐标解析、碰撞检测、消除规则、胜负判定

## Scaffold

| 目标路径 | 来源 | 说明 |
|---------|-----|------|
| `tests/gameplay.test.ts` | `ref/gameplay.test.ts` | 完整测试用例 |
| `vitest.config.ts` | `ref/vitest.config.ts` | Vitest 配置 |

`package.json` 新增：
```json
{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "devDependencies": {
    "vitest": "^3.0.0"
  }
}
```

## 使用方式

```bash
pnpm test          # 运行所有测试
pnpm test:watch    # 监听模式（修改代码自动重跑）
```

## 测试覆盖

| 模块 | 测试点 |
|------|--------|
| `LevelParser` | Cocos→Phaser 坐标翻转 / 路径离散化 / 方向推导 |
| 碰撞检测 | `isCellOccupied` 正确性 / `ignorePathIndex` 排除自身 |
| 消除规则 | 方向无阻挡→成功 / 方向有阻挡→失败 / 已消除不参与碰撞 |
| 胜负条件 | 全部消除→胜利 / 生命归零→失败 |
| 数据校验 | 坐标越界检测 / 空路径检测 |

## Recipe

| 决策 | 原因 |
|------|------|
| **与 Phaser 完全解耦** | 玩法规则（坐标解析、碰撞检测、消除判断）是纯函数，不需要 Canvas 或 DOM；在 Node.js 中运行测试速度快 10 倍以上 |
| **Vitest 而非 Jest** | 项目使用 ESM 模块，Vitest 原生支持 ESM + TypeScript，无需额外 Babel 配置 |
| **测试纯函数，不测场景生命周期** | Phaser Scene 的 `create/update` 测试成本高且价值低；核心算法的正确性才是单元测试的目标 |

## Adapter

- **Role**: `gameplayTest` — 玩法逻辑纯函数单元测试框架
- **Provides**: `tests/gameplay.test.ts` 测试套件、`vitest.config.ts` 测试配置、`pnpm test` / `pnpm test:watch` 命令
- **Requires**: `arrow_path_data_format.aicomponent`（LevelParser、LevelTypes 被测对象）
- **Consumed by**: Agent 在修改游戏逻辑后执行 `pnpm test` 验证正确性；无上游 skill 依赖
- **Integration point**: 根目录 `vitest.config.ts` —— `pnpm test` 运行 `tests/` 目录下所有测试文件

## Imports

- `arrow_path_data_format.aicomponent`（硬依赖：LevelParser + LevelTypes）
- `path_elimination_rules.aigameplay`（参考：PGS 测试用例）
- `level_data_validator.aivalidator`（可选：集成校验测试）

## Skill Definition

```yaml
tools:
  - read_file
  - write_file
inputs:
  - source: ref/gameplay.test.ts
  - source: ref/vitest.config.ts
outputs:
  - testSuite: tests/gameplay.test.ts
  - testConfig: vitest.config.ts
  - testScripts: test / test:watch npm scripts
```