Zinc Unittest

---
name: zinc-unittest
description: War3Lib/Xlimon 的 Zinc 单元测试流程规范。用于创建或重构 Jass/Zinc 单测时按当前仓库选择流程：War3Lib 使用 `.j + .cfg + _Test.j`、TaskCreateUT.lua 与 chain 依赖；Xlimon 使用 `.j + _Test.j + edit/config/UnitTest.h`。两边均使用 UnitTestFramwork.assert 与可检索日志。
---

# Zinc Unit Test Workflow (War3Lib/Xlimon)

先识别当前仓库，再按对应流程执行，保持最小改动和可复现。

## 仓库分流

- War3Lib：继续执行下方主流程，使用 `scripts/create_ut.sh`、`references/ut-file-layout.md`、`references/assert-trace-pattern.md`、`references/examples.md`。
- Xlimon：使用 `scripts/create_xlimon_ut.sh`、`references/xlimon-ut-file-layout.md`、`references/xlimon-assert-trace-pattern.md`、`references/xlimon-examples.md`；不创建 War3Lib 专用的 `.cfg`/`[chain]`，而是切换 `edit/config/UnitTest.h`。
- 不允许跨仓库混用生成脚本；运行前先用 `git rev-parse --show-toplevel` 核实根目录。

## 1. 建立三件套文件

1. 以目标模块 `Xxx.j` 为中心，确认同目录存在：`Xxx.cfg`、`Xxx_Test.j`。
2. `Xxx.cfg` 不存在时创建，并补齐：公开 API 关键词 + `[chain]` 基础依赖。
3. 需要物编辅助测试时，按需创建同名扩展文件：`Xxx.w3a`(技能)、`Xxx.w3u`(单位)、`Xxx.w3i`(物品)。

说明：`cfg` 前半段用于外部 dependency 注入关键词；`[chain]` 是该库底层依赖，用于递归注入。

## 2. 生成或刷新 `_Test.j`（必须走任务脚本）

优先复用项目脚本，不手写测试壳。

1. 运行：`bash .codex/skills/zinc-unittest/scripts/create_ut.sh <Xxx.j>`。
2. 该流程会调用 `Lua/tasks/TaskCreateUT.lua`，并使用模板 `Jass/template/UTTemplate.j`。
3. 已存在 `_Test.j` 时默认不覆盖，仅更新 `Jass/config/UnitTest.h` 的 include 到当前测试文件。

如果脚本不可用，再手动按 `UTTemplate.j` 结构补齐占位符：`{UnitTest}`、`LibraryName`、`#include`。

## 3. 编写测试逻辑（参考 UnitUtils 风格）

1. 在 `library UTXxx requires Xxx,...` 中按功能拆分 `Test_*` 私有函数。
2. 使用 `UnitTestAutoTimer` 安排自动测试，避免初始化竞争。
3. 聊天命令入口走 `s1..s10` 或 `-参数`，复用模板函数 `TTestUTXxx*` / `TTestActUTXxx1`。
4. 断言优先使用 `UnitTestFramwork.assert`：`Boolean/Integer/Real/String`。
5. 需要输出到日志时优先用 `Trace(...)`（YDLua），不要依赖仅本地可见的原生提示。

## 4. 宏保护与命名

1. 测试专用注册与入口放在测试文件中；若写在业务库，必须加：`#if (CURRENT_BUILD_VERSION != VERSION_RELEASE)`。
2. 不使用 `_` 开头标识符。
3. 用模块名前缀组织测试名与提示文案，保证日志可检索。

## 5. 验收检查

1. `Xxx.cfg` 关键词覆盖公开能力；`[chain]` 不漏基础库。
2. `_Test.j` 可独立触发核心断言，失败日志能定位到具体测试。
3. 若依赖物编，`Xxx.w3a/w3u/w3i` 与测试步骤匹配，并在说明中写出用途。

## References（按需加载）

- `references/ut-file-layout.md`
- `references/assert-trace-pattern.md`
- `references/examples.md`
- `references/xlimon-ut-file-layout.md`
- `references/xlimon-assert-trace-pattern.md`
- `references/xlimon-examples.md`

## Xlimon 快速流程

1. 运行 `bash .codex/skills/zinc-unittest/scripts/create_xlimon_ut.sh edit/.../Xxx.j`。
2. 默认仅在不存在时生成 `Xxx_Test.j`，并把 `edit/config/UnitTest.h` 的 include 切到该测试；只有确认旧壳可丢弃时才加 `--force`。
3. 使用 `UnitTestAutoTimer`、`UnitTestFramwork.assert` 与 `Trace`；无 `Trace` 时使用带模块前缀的 `BJDebugMsg`。
4. 验收 `_Test.j` 可直接触发核心断言，且可选 `.w3a/.w3u/.w3i` 与测试步骤匹配。