A2UI v0.9 规范 JSON Schema 测试套件实战指南：用 AJV 验证 Agent 到 UI 消息协议

A2UI v0.9 规范 JSON Schema 测试套件实战指南用 AJV 验证 Agent 到 UI 消息协议【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui本篇指南围绕 A2UI 开源仓库中specification/v0_9/test目录的测试体系展开讲解如何通过 Python 脚本与 ajv-cli 组合对 A2UI v0.9 的 JSON Schemaserver_to_client.json、client_to_server.json、common_types.json、catalog.json进行自动化校验。读完本文你将掌握测试套件的运行方式、测试用例 JSON 的编写格式、底层验证原理以及如何为新的协议特性补充回归测试为基于 A2UI 协议开发 Agent 端或渲染端提供可靠的校验防线。一、测试套件定位为 A2UI 协议兜底的 schema 回归防线A2UIAgent to UI协议通过 JSON 消息动态构建和更新用户界面。这些消息的合法性直接决定了 Agent 端与渲染端之间的通信是否可靠。specification/v0_9/test目录的核心使命就是用一套可重复执行的测试用例持续验证specification/v0_9/json下的 JSON Schema 定义是否与协议文档保持一致防止协议演进过程中出现Schema 改坏、消息跑偏的回归问题。从仓库结构看v0.9 的测试体系与协议本体分层清晰Schema 定义specification/v0_9/json/ 下存放server_to_client.json、client_to_server.json、common_types.json等官方 Schema目录清单specification/v0_9/catalogs/basic/ 存放基本组件目录Button、TextField、Tabs 等组件定义与校验规则测试用例与运行器即本文主角 specification/v0_9/test/ 下的run_tests.py与cases/*.json。同样的测试组织方式也出现在 v0_9_1 与 v1_0 版本中见 specification/v0_9_1/test/ 与 specification/v1_0/test/可见这套JSON Schema 用例目录 统一运行器的验证模式是 A2UI 规范版本管理的通用做法。二、环境准备Python 3 与 Yarn 双依赖运行测试前需要准备两个基础依赖依赖用途说明Python 3驱动测试运行器运行run_tests.py负责编排用例、调用 AJV、汇总结果Yarn执行 ajv-cli测试通过yarn run ajv调用校验工具其中 ajv-cli 及其配套的ajv-formats提供日期时间、URI、邮箱等格式校验由测试目录内的package.json声明版本约束为ajv-cli ^5.0.0、ajv-formats ^3.0.1见 specification/v0_9/test/package.json。安装依赖可选为了加速测试执行可以本地安装依赖cd specification/v0_9/test yarn install如果跳过yarn installajv-cli 可能不存在运行器会在检测不到命令时给出明确提示并退出见 run_tests.py 中FileNotFoundError的处理分支。三、运行测试一条命令跑完全部用例从仓库根目录或测试目录均可执行python3 specification/v0_9/test/run_tests.py该脚本执行时依次完成三件事与 README.md 描述一致加载specification/v0_9/json下的全部 Schema执行specification/v0_9/test/cases/*.json中定义的所有测试套件逐个输出用例的 pass/fail 状态最后汇总总数。实际上package.json已经内置了测试入口脚本也可以直接用cd specification/v0_9/test yarn test它等价于执行python3 run_tests.py见 package.json。若全部用例通过脚本退出码为 0只要存在任一失败用例退出码即为 1见 run_tests.py这一约定使其天然适合接入 CI 流水线。输出样例解读运行器会按套件打印摘要例如Running suite: button_checks.json (7 tests) Target Schema: server_to_client.json [FAIL] Button with deprecated enabled property (should fail) Expected Valid: False, Got Valid: True[FAIL]行会附带期望结果与实际结果若数据未通过校验还会打印 AJV 的详细错误输出方便定位 Schema 问题还是用例问题。四、测试用例格式一套 JSON 规范双断言模式在cases/目录下新建一个 JSON 文件即可注册一套测试例如cases/my_feature.json{ schema: server_to_client.json, tests: [ { description: Description of the test case, valid: true, data: { updateComponents: { ... } } }, { description: Should fail validation, valid: false, data: { ... } } ] }字段语义如下字段必填说明schema是指定本套用例针对哪个 Schema 文件取值须在运行器支持的映射表内tests是测试用例数组description是用例描述失败时会原样打印valid是期望结果true表示数据应当通过校验false表示应当被拒绝data是待校验的完整消息数据顶层必须携带version字段valid双断言模式是本套件的精髓既有合法消息必须通过的正向用例也有非法消息必须被拒的负向用例两者共同把 Schema 的约束边界钉死。运行器支持的 Schema 映射运行器内置的 Schema 映射表见 run_tests.py决定了schema字段的合法取值schema 取值实际加载文件server_to_client.jsonspecification/v0_9/json/server_to_client.jsoncommon_types.jsonspecification/v0_9/json/common_types.jsoncatalog.json运行时由catalogs/basic/catalog.json动态生成见下文catalog 别名机制client_to_server.jsonspecification/v0_9/json/client_to_server.json若用例引用了映射表之外的 schema 名运行器会报错并跳过该套件见 run_tests.py。五、仓库内既有用例全景八套 JSON 加一份 JSONL 示例specification/v0_9/test/cases/下现有 9 个文件覆盖了协议验证的多个关键维度用例文件目标 Schema覆盖要点button_checks.jsonserver_to_clientButton 组件的checks校验表达式、variant枚举、已废弃的enabled/primary属性必须被拒绝function_catalog_validation.jsonserver_to_client函数目录中的required、regex、length、numeric、email、formatString、formatNumber、formatCurrency、formatDate、pluralize、openUrl以及逻辑组合and/or/not的参数与返回类型约束client_messages.jsonclient_to_serveraction消息、error消息以及已更名的updateDataModel必须被拒绝theme_validation.jsonserver_to_clientcreateSurface中theme的类型约束、十六进制颜色格式、允许扩展自定义属性contact_form_example_test.jsonserver_to_client联系表单端到端示例createSurface → updateComponents → updateDataModel 三连消息contact_form_example.jsonlserver_to_client同一表单示例的逐行 JSONL 版本运行器会按行独立校验tabs_checks.jsonserver_to_clientTabs 组件的tabs数组非空约束checkable_components.jsonserver_to_client可勾选组件CheckBox 等的校验text_variants.jsonserver_to_clientText 组件variant枚举约束从用例看协议约束的实际形态以button_checks.json为例可以直观看到 v0.9 协议对 Button 的约束力度见 button_checks.json正向用例variant取primary、borderless均为合法checks支持嵌套的and/or/required组合表达式例如必须接受条款且邮箱或电话至少提供一个负向用例使用已废弃的enabled或primary属性会校验失败——这是 v0.8 迁移到 v0.9 时属性更名的回归护栏checks内condition的returnType必须为合法类型结构内不允许出现extraProp之类的多余字段。function_catalog_validation.json则展示了函数目录Function Catalog的精细校验见 function_catalog_validation.jsonlength的min/max必须是非负整数、numeric的min/max必须是数字、regex的pattern必须是字符串、email不允许多余参数、formatCurrency必须携带currency、openUrl的url必须是合法 URI 且returnType必须为void、and/or的values至少两个元素、not的参数必须是布尔值。这些用例共同锁定了表达式求值的类型安全边界。client_messages.json则负责客户端到服务端方向见 client_messages.json验证action含surfaceId、sourceComponentId、timestamp、context与error消息的合法性并确保 v0.8 时代的updateDataModel不再被接受。六、运行器源码剖析catalog 别名、AJV 调用与 JSONL 校验理解run_tests.py的实现能帮你更精准地编写用例。1. catalog 别名机制解决跨文件 $ref 解析server_to_client.json中的组件定义通过$ref: catalog.json#/$defs/anyComponent引用 catalog Schema见 server_to_client.json。为了让这个引用能正确解析运行器在启动时执行setup_catalog_alias()见 run_tests.py读取specification/v0_9/catalogs/basic/catalog.json用正则将其$id归一化为通用的https://a2ui.org/specification/v0_x/catalog.json形式写入临时文件catalog.json并作为catalog.json注册进 Schema 映射表。这样server_to_client.json引用catalog.json时即可解析到实际目录内容测试结束后临时文件会被清理。2. AJV 调用参数Draft 2020-12 宽松模式 formats核心校验函数validate_ajv()见 run_tests.py通过子进程执行yarn run ajv validate \ -s schema_path \ --specdraft2020 \ --strictfalse \ -c ajv-formats \ -d data_path关键参数含义参数作用--specdraft2020使用 JSON Schema Draft 2020-12 规范与 Schema 头部的$schema声明一致--strictfalse关闭严格模式避免未知关键字触发告警导致校验中断-c ajv-formats启用 format 校验uri、date-time 等格式检查theme中十六进制颜色等约束依赖它-r path将其他 Schema 一并作为引用注册使跨文件$ref可解析3. 两条验证流水线JSON 套件 JSONL 示例main()见 run_tests.py先按文件名排序逐个执行cases/*.json套件随后单独调用validate_jsonl_example()对contact_form_example.jsonl逐行校验。JSONL 的每行都是一条独立消息运行器把每行写入临时文件后走与套件相同的 AJV 校验流程从而保证示例文档中的每条消息都始终是合法消息。每个用例的数据会先json.dump写入临时文件再交给 AJV失败时通过is_valid expect_valid比对得出 verdict汇总后如有失败则sys.exit(1)供 CI 判定。七、实战为协议新特性添加一套回归测试以为某个新组件变体添加校验为例完整流程如下确定目标 Schema组件类消息通常属于server_to_client.json新建用例文件在specification/v0_9/test/cases/下创建cases/my_feature.json按第四节格式编写编写正向用例构造一条完整合法的消息含version、surfaceId、组件树valid设为true编写负向用例针对每个要禁止的形态错误类型、多余字段、废弃属性、非法枚举值各写一条valid: false运行验证执行python3 specification/v0_9/test/run_tests.py观察新增用例是否全部按预期通过。编写要点data顶层必须携带version: v0.9因为 Schema 对version使用了const约束见 server_to_client.jsonupdateComponents消息中应包含root组件Schema 要求组件树必须存在id为root的根节点负向用例务必只错一处仅注入单一违规点便于失败时快速定位是哪条约束被违反涉及theme颜色等格式约束时确保本地yarn install已安装ajv-formats否则格式类断言可能失效。八、测试即文档把用例当作协议约束的活字典对协议使用者而言cases/目录的价值远超跑通测试本身协议约束速查button_checks.json、function_catalog_validation.json等文件将零散写入docs/的协议规则转化为机器可读、可执行的断言是了解 v0.9 消息合法形态的第一手材料迁移对照负向用例如拒绝enabled、primary、updateDataModel明确标注了 v0.9 相对旧版本的破坏性变更点配合 specification/v0_9/docs/evolution_guide.md 可快速完成存量消息的迁移自查端到端示例contact_form_example.jsonl是一个从建面、渲染到数据回写的完整可运行示例可作为 Agent 端生成消息的黄金参考。无论是规范维护者还是 A2UI 协议的二次开发者把改 Schema 必跑测试、写用例即写文档作为工作习惯就能让这套测试体系持续为协议的稳定性与可演进性保驾护航。【免费下载链接】a2ui项目地址: https://gitcode.com/GitHub_Trending/a2/a2ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考