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 与测试步骤匹配。