言试：测试工具

言试（yanxu-test）1.0.0 在言序标准测试模块之上提供工程化测试能力：有界断言与深比较、数据驱动套件、惰性夹具、Mock/Spy、快照、临时目录、内存 HTTP 传输、数据库回滚事务和仓储 CRUD 契约。它不会替代测试运行器。

版本与安装

测试工具应作为开发依赖安装：

yanbao add 言试 \
  --git https://github.com/yanxulang/yanxu-test.git \
  --rev v1.0.0 \
  --version '^1.0' \
  --dev

等价的 言序.toml清单：

[开发依赖]
言试 = { git = "https://github.com/yanxulang/yanxu-test.git", 修订 = "v1.0.0", 版 = "^1.0" }

言试自身把四个依赖分别固定在公开标签：言时 v1.0.0、言据 v1.2.0、言访 v1.0.0和言库 v1.0.0。测试项目仍应提交自己的 言序.lock。

核心能力与快速开始

引「包:言试」为 言试；

法 用户夹具（）：典 则
    归 {「编号」：42，「姓名」：「子衿」}；
终

法 清理用户（用户）：空 则
    归 空；
终

法 验证用户（上下文）：空 则
    定 用户：典 为 上下文.夹具（「用户」）；
    言试.相等（用户【「编号」】，42）；
    言试.应匹配（用户【「姓名」】，「^子」）；
    归 空；
终

言试.套件（「用户服务」）
    .夹具（「用户」，用户夹具，清理用户）
    .测试（「读取用户」，验证用户）
    .运行（）；

夹具第一次读取时才创建，并在当前测试结束后按反序清理。测试体失败后仍会执行每项后钩子与夹具清理；清理失败也会进入报告。

断言与数据驱动

言试.相等（2 加 2，4）；
言试.深相等（
    {「用户」：{「姓名」：「子衿」}}，
    {「用户」：{「姓名」：「子衿」}}
）；
言试.近似相等（0.1 加 0.2，0.3，0.000001）；

嵌套列和典应使用 深相等。深比较、复制和记录都有预算；大型合法样本应显式使用受限 API，并在测试中说明提高上限的理由。

表格测试使用行典组织可读案例，参数化测试把参数列按位置展开。两者都返回结构化运行结果，并在案例失败时让测试运行器正确标红。

套件、Mock 与隔离

套件提供测试前、测试后、每项前、每项后、夹具、测试、尝试运行和运行。尝试运行聚合通过、失败、跳过、逐项错误和生命周期错误；运行在结果不成功时抛 YANSHI_TEST_SUITE。

定 时钟 为 言试.虚拟时钟（0）；

定 模拟 为 言试.Mock（时钟）
    .依次返回（【「甲」，「乙」】）
    .依次抛错（【「暂时失败」】）；

言 模拟.调用（【1】）；
言试.相等（模拟.调用次数（），1）；
言试.断言（模拟.被调用于（【1】），「应记录参数」）；

Mock 可配置固定返回、队列返回、错误队列或自定义实现；Spy 调用原函数并记录同样的信息。调用参数、结果与记录会深复制。套件、Mock、Spy、快照库和 HTTP Mock 都有可变状态，不应跨并发测试共享实例。

快照使用单个 JSON 对象文件；更新模式应显式开启，并由评审检查变化。临时目录的子路径必须使用正斜线相对路径，拒绝 ..和反斜线。环境隔离是内存覆盖视图，不修改进程全局环境。

HTTP 客户端测试

引「包:言访」为 言访；

定 HTTP 为 言试.HTTPMock（）
    .响应JSON（
        「GET」，
        「https://api.example.test/users/42」，
        200，
        {「编号」：42}
    ）；

定 客户 为 言访.客户端（）
    .禁用重试（）
    .使用传输（HTTP.言访传输（））；

定 响应 为 客户.取（「https://api.example.test/users/42」）.发送（）；
言试.相等（响应.解析JSON（）【「编号」】，42）；

HTTPMock在内存中按精确或正则地址匹配路由，不劫持全局网络。言访传输()返回正式的言访自定义传输适配；未匹配请求使用 YANSHI_TEST_HTTP_UNMATCHED失败。HTTP 非 2xx 是正常响应，只有网络型错误与未匹配路由抛错。

数据库与仓储测试

法 建用户（事务）：数 则
    事务.执行（「INSERT INTO users(name) VALUES (?)」，【「子衿」】）；
    归 1；
终

言试.数据库测试事务（连接，建用户）；

连接必须支持言库托管事务。无论回调成功还是失败，数据库测试事务都会回滚并恢复连接；回调不能自行提交。回滚只能覆盖同一事务连接内的操作，消息、文件和其他外部副作用仍须由测试清理。

仓储协议、函数适配器和 CRUD 契约用于让 SQLite、PostgreSQL、MySQL 与测试替身共享语义。契约会调用重置()并清空数据，只能用于隔离测试仓储，绝不能指向开发或生产数据。

权限与安全边界

最终包清单声明：

[权限]
文件 = ["."]
网络 = []
TCP监听 = []
UDP绑定 = []
环境 = []
进程 = false
原生扩展 = false

文件能力服务于快照和临时目录 API。依赖权限不会自动传递，顶层测试项目仍须显式授权自己实际使用的路径；真实数据库连接、系统环境读取和其他外部能力同样由测试项目负责。HTTPMock不需要网络权限，数据库测试事务也不会创建连接或读取凭据。

错误使用稳定 YANSHI_TEST_*代码。快照、HTTP 记录、Mock 调用和错误可能含敏感值，不要把真实令牌、Cookie、个人数据或数据库凭据写入测试产物。

已知限制

• 套件是同步执行模型，不调度异步任务。
• 快照只支持 JSON 可表示的值，不承诺与其他快照框架互通。
• Mock/Spy 调用记录和快照会随用例规模线性占用内存，不适合无限压力记录。
• HTTP Mock 不模拟 DNS、TLS、连接分段或真实网络时序。
• 数据库回滚不能撤销事务连接外的副作用；仓储契约会执行破坏性重置。
• 有状态测试对象不应跨并发测试共享；需要共享依赖缓存时可让运行器使用 --并发 1。

项目链接

• GitHub 仓库
• 言试 1.0.0 Release