战国 Mod 开发文档

测试与验收

五项覆盖、离线回归怎么跑、自己的模块怎么测。

离线回归

.venv/bin/python -m unittest discover -s tests            # 全量
.venv/bin/python -m unittest tests.test_example_mods -v   # 单个文件
.venv/bin/python -m unittest tests.test_X.TestY.test_z    # 单个用例

全量跑一遍约两分钟。任何改动都要全量过——模块之间会互相影响, 单测绿不代表整体绿。

每个模块要覆盖的五项

覆盖断言什么
声明装载成功;能力、状态、工具都注册上了
行为动作真的改了世界,边界情况也成立
存档存下来再读回来,to_save() 完全相等
错误路径非法参数、资源不足、越权操作都失败得清楚
跨模块和别的模块协作时数据对得上

写测试的样子

class TestHelloMod(unittest.TestCase):
    def setUp(self):
        self.runtime = Runtime.load(ROOT / 'mods/examples/hello')
        self.world = self.runtime.world_class()()

    def test_add_accumulates(self):
        self.runtime.call(self.world, 'a', 'hello_add', {'amount': 3})
        self.runtime.call(self.world, 'a', 'hello_add', {'amount': 4})
        self.assertEqual(self.runtime.call(self.world, 'a', 'hello_total')['count'], 7)

    def test_bad_argument_is_rejected(self):
        with self.assertRaises(Exception):
            self.runtime.call(self.world, 'a', 'hello_add', {'amount': '不是数'})

模型客户端也要测

模型客户端是最容易出「跑起来才炸」的一环。用假后端测,不要真的调 API:

class FakeBackend:
    def __init__(self, responses=None):
        self.responses = list(responses or [])
        self.requests = []

    def chat_turn(self, messages, tools, cfg, on_retry=None):
        self.requests.append({'messages': messages, 'tools': tools})
        message = self.responses.pop(0) if self.responses else {'content': ''}
        return message, {'hit': 10, 'miss': 2}

    def complete_text(self, messages, cfg, tools=None, **kwargs):
        return '…', {'hit': 8, 'miss': 1}

装上假后端,跑一整局:

host = GameHost.new(cfg)
host.clients['scenario:qin']._backend = FakeBackend([...])
receipts = host.clients['scenario:qin'].play(host.player('scenario:qin'))
self.assertTrue(all(receipt['ok'] for receipt in receipts))

要断言的至少三样:

  1. 模型看到的工具表里有你的工具;
  2. 模型调用成功(没有未知工具、参数不合法);
  3. end_turn 的回执里有 text(否则模型客户端会抛异常)。

仓库里 tests/test_model_view_contract.py 是这套做法的样板: 它同时守住了「发行版无关」和「minigame 能被模型驱动」两件事。

验收一局真实对局

离线测试过了,还要看模型是不是真的在用你的内容:

.venv/bin/python mp_run.py --config <配置> --new --turns 3

看三样:

  • 工具回执里有没有你的工具在动;
  • 审计记录里模型的调用序列合不合理;
  • 有没有反复犯同一个错(说明工具描述写得不够清楚)。

文档也要跟得上

改动要同步
新增模块docs/site/content/附录/01-示例索引.md 登记
改了工具/字段跑 python3 scripts/api_doc.py 重新生成 API 参考
改了发行版清单重新生成发行版清单参考页

scripts/api_doc.py --check 可以在 CI 里检查参考页是否与代码同步。