测试框架原则PRINCIPLES.md本文件是宪法级约束不可违背mock 测试框架的每一次设计、每一行测试、每一次修改都必须符合以下原则。原则为定论不是建议。若实现与原则冲突改实现若原则之间冲突以更高编号原则优先编号小者优先。本文件收录用户明确提出的原则原话逐条展开为「阐述 示例」。新增原则必须由用户确认后追加。1. 测试为 AI 设计阐述人类只负责用自然语言描述测试目标“要测什么、期望什么行为”不写具体测试代码AI 自动把目标翻译为实现并反过来驱动框架补齐能力。因此框架本身必须结构化、可追溯、断言明确每一步可被 AI 读取、可被 grep 检索、断言一眼可读让 AI 能仅凭框架输出判断对错。示例用户说测结算幂等框架/测试就把这条自然语言目标落到SETTLE_SEMANTICS.md的具体断言重复投递相同 token 不得重复落账断言语句明确写出期望值AI 依据断言结果直接给出通过/失败 证据而不是靠人工读日志猜测。2. 集成测试原则阐述当用户要求的是集成测试时禁止退化为很小的单点测试。必须把依赖的具体部分——由用户明确给定的那部分——纳入测试范围并按用户要求构建 mock 测试环境与脚本从客户端 UI 开始一步一步测到服务器走完整个全流程UI 事件 → 网络 → 服务器 → 状态回包 → UI 渲染而不是只测中间某一个孤立的函数。示例测杠后补牌结算不能只测 settle 函数本身要起 mock 环境脚本从麻将 UI 点杠出发驱动路由到服务器结算节点回包后再断言 UI 渲染出了正确结果全程可回放、可追溯。3. 测试标准原则阐述不得恶意降低测试标准来让测试通过。测试要按本当实现的 PRD 需求目标来构建而不是单纯按现有代码实现来构建——代码怎么写不代表需求就是什么。只有物理事实上不可能达成的目标才能调低标准这是硬性规定不允许实现麻烦、框架不支持这类理由。测试用例覆盖足够时mock 必须保证代码可编译、可运行若运行结果脱离预期优先怀疑测试目标写错了目标与 PRD 不符、断言写错其次才怀疑被测代码。示例PRD 要求断线重连后玩家状态不丢即使当前代码就是会丢测试也必须按 PRD 写断言并失败而不是把断言改成允许丢。调低标准仅当目标在物理上不可达成如 mock 无法模拟真实网络延迟到毫秒级时才允许且必须写明理由。4. 状态一致性原则阐述有状态帧循环游戏帧循环驱动测试核心是状态客户端状态、服务器状态、客户端-服务器状态且客户端 UI 状态 客户端状态这条等式不可违背。服务器什么状态UI 就必须渲染什么状态不能缺少渲染UI 显示超过服务器及设计预期 根本问题。输入确定性 → 输出确定性同样的输入序列必须产生同样的状态序列不符预期必是 BUG不允许用顺序/时序问题含糊带过。示例服务器把金币从 100 降到 50 并回包UI 必须立刻渲染出 50若 UI 仍显示 100是渲染缺失 BUG若 UI 显示了服务器从未下发的状态如凭空多出 10 金币是超出预期的根本问题。同一操作序列重跑两次状态演进必须完全一致。5. 测试定位 BUG 原则阐述测试的目的是用正确的测试定位 BUG然后修复它。不是把测试改到能通过。测试失败时先怀疑被测代码与目标语义禁止为了绿灯而删断言、改断言、放宽范围、跳过用例。示例断言失败 → 先查是目标/断言写错原则 3 优先怀疑还是被测代码确有缺陷若是代码缺陷修复代码唯一允许改测试的情况是证明测试本身与 PRD 目标相悖并写明证据改后仍须覆盖原目标。6. 框架可改进原则阐述任何人都可以修改框架进行改进框架不是已定型不可动的黑盒。当框架不能支持某个测试或对某个测试覆盖不完整时必须补充、改进框架而不是绕过或降级该测试。最终目标尽可能模拟真实环境。测试本身不可靠mock 失实、时序失真则测试结论就是错的——框架改进服务于测试可信度。示例测试需要模拟服务器重启后玩家断线重连而当前 mock 没有节点重启能力 → 给框架补节点生命周期/重启注入而不是把该测试标跳过或简化成直接调用重连函数。7. 系统边界原则阐述畅玩阁与麻将是同一个系统的两个模块不是两个独立系统smallgame小游戏与其 UI 同样同属该系统。因此测试必须两者都覆盖不能只测麻将本身而漏掉畅玩阁/小游戏。一个改动若同时影响两个模块必须对两个模块都建立并运行测试。示例结算走麻将链路、入口在畅玩阁大厅测试必须从畅玩阁入口进入并走到麻将结算验证跨模块全链路不能只测麻将的 settle 而假设畅玩阁反正没改。8. 目录分类原则阐述docs/、scripts/、tests/下的所有内容均按系统类型分类存放mahjong/、mahjong_ui/、smallgame/等不混放。文档归文档目录、脚本归脚本目录、测试归测试目录同一系统的三类内容放在同名子目录下跨系统内容框架级单列。示例麻将服务器语义 →docs/mahjong/SETTLE_SEMANTICS.md麻将 UI 行为 →docs/mahjong_ui/UI_BEHAVIOR.md对应测试 →tests/mahjong/、tests/mahjong_ui/框架级说明 →docs/ARCHITECTURE.md。禁止把系统 A 的测试脚本塞进系统 B 的目录。9. 真实模拟原则阐述时间、配置、控件均尽可能真实时间用多物理时钟各节点独立真实计时而不是一个全局假时钟拍平配置用真实 .tab 配置表加载而不是写死的硬编码数值控件用真实 XML 控件树与 UI 声明同源音效用真实语音/音效跟踪能跟踪到具体音效文件的触发与播放。越接近真实环境测试结论越可信见原则 6。示例延迟测试必须用独立的物理时钟给不同节点计时验证超时/重发逻辑在真实时序下成立配置必须走tab_loader读真实 .tab 表表里把超时改成 3000ms 时测试行为跟着变而不是在测试里硬编码 5000ms。10. 调用堆栈原则阐述框架要诚实记录调用堆栈——真实记录谁调用了谁、经过哪些链路到达这里不裁剪、不美化、不伪造。完整真实的堆栈既便于定位 BUG直接看到失败链路也便于 AI 用 grep 搜索按函数名/链路关键字即可检索到相关记录与断言。示例一次 UI→路由→结算→回包的调用堆栈如实记录UI_CLICK → ROUTE_SEND → SCENE_FORWARD → SETTLE_APPLY → UI_RENDER每一跳BUG 出现在SETTLE_APPLY时grepSETTLE_APPLY就能搜出全部相关调用记录与断言上下文而不用人工重放。11. 流程正确则测试必过原则宪法级如果流程是正确的测试就应该通过只有流程不正确测试才会失败。对 AI 而言测试没跑通 必须去找问题并修复——不管问题是产品代码 BUG、框架缺口、还是测试目标编写错误。严禁把跑不通的测试搁置、跳过、或标记为’预期失败’而不修。没跑通就得找问题找出来就得改改完必须重跑验证。