用途:验证某个已构建的 Convex 功能是否真正按预期工作。类型检查通过只说明代码能解析,不能证明非所有者会被拒绝、查询返回正确的行、或变更产生声称的效果;本能力用「播种 → 驱动 → 断言」的循环弥补这一缺口,借助 convex-test 在进程内运行,无需部署。其最高价值的断言是负向断言(本应被拒绝的调用者确实被拒绝),因为这类授权缺陷是最常见的真实 bug,也是单纯跑通正向路径的演示永远抓不到的。
主要能力:识别待验证的具体导出 query/mutation/action 及其预期行为(谁应被允许、应返回什么数据、变更应改变什么);搭建 convex-test 环境;通过应用自身的函数播种数据;以不同身份驱动被测功能;断言正向与负向行为、数据可见范围;运行测试并报告结论与失败项。
使用方式:需先确认 convex-test 与 vitest 为开发依赖,并配置 vitest.config.ts 设置 test.environment 为 "edge-runtime" 且 server.deps.inline 含 "convex-test"——缺少该配置时 convexTest(schema) 会在运行时以 import.meta.glob is not a function 失败,另需安装 @edge-runtime/vm。之后 convexTest(schema) 返回 t 句柄;若项目已有测试配置则复用,不另起一套。播种时尽量走应用自身函数,无法由公开 API 创建的夹具再用 t.run(async (ctx) => ctx.db.insert(...)),并至少播种调用者自己的行与第二个用户的行,以便测试跨用户访问。驱动时用 t.withIdentity({ subject, tokenIdentifier, ... }) 分别以合法所有者、其他已认证用户、未认证三种身份调用,身份结构需与应用认证实际使用的一致。断言包含正向(所有者得到预期行、变更产生预期改变)、负向(其他用户被拒绝,如 rejects.toThrow(/forbidden|not authorized|403/);需要认证处未认证调用者被拒绝)以及数据范围(列表/查询只返回调用者自己的行,断言第二个用户的行不存在)。最后运行 npx vitest run 并报告哪些正负向断言通过、哪些失败,失败即可能是上线前的真实授权漏洞,并按 specs/finding.schema.json 在总线上发出发现(class authz/correctness,证据 kind probe-result,含确切失败调用)。
适用场景:针对刚构建或修改的某个具体 Convex 功能做行为验证,尤其是需要检查权限与数据可见范围的场景。
限制:不得为了让测试通过而削弱断言——若仅所有者可见的查询返回了他人数据,修复点在被测函数而非断言,应交给 convex-authz;未经证实就修改测试直到通过毫无意义。本能力面向具体功能验证,若需求是通用搭建测试框架,应使用测试能力。