Matter YAML 测试完全指南编写认证测试、本地运行与 CI 集成connectedhomeip【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeipYAML 测试是 Matterconnectedhomeip 仓库认证与回归测试的核心载体它以结构化的 YAML 描述测试步骤再由 Python 运行器解析并翻译成 chip-tool 命令与被测设备DUT交互。本文以 docs/testing/yaml.md 为主线完整讲解测试文件写法、常用动作发命令、读写属性、解析响应、伪集群、变量与门控、本地/CI 运行流程与 CI 参数定义并辅以仓库源码与真实测试用例如 Test_TC_OO_2_1.yaml、TestEqualities.yaml进行印证。读完本文你将能够独立编写、调试并在本地或 CI 中运行一套 Matter YAML 测试。YAML 测试在 Matter 中的定位与运行机制YAML 是一种结构化的、人类可读的数据序列化语言。与 JSON 或 protobuf 类似YAML 本身只定义结构与解析器具体的应用层 Schema 由使用它的应用自行定义。在 Matter 中YAML 被用于描述测试与测试步骤一个 YAML 解析与运行器负责把 YAML 指令翻译成与被测设备Device Under TestDUT交互的实际动作。Matter 测试使用的主运行器会把 YAML 指令解析为chip-tool 命令。从源码可以印证这一机制scripts/tests/chipyaml/chiptool.py 通过send_yaml_command将 YAML 测试发送给以interactive server模式启动的 chip-tool默认server_arguments即为interactive serverchip-tool 通过 socket 接收指令并执行。此外运行器还支持通过--server_path指定自定义的 WebSocket 服务端或通过--server_name默认chip-tool让 scripts/tests/chipyaml/paths_finder.py 在 SDK 目录树中自动查找对应二进制。测试 YAML 的完整 Schema 定义见 docs/testing/yaml_schema.md由脚本generate_yaml_doc_tables.py自动生成请勿手工编辑。编写 YAML 测试文件结构与顶层 Schema大多数 YAML 测试为**认证certification**而编写遵循标准格式便于在测试台Test HarnessTH中直观展示。一个典型测试文件的顶层结构如下源自 Test_TC_OO_2_1.yamlname: 3.2.1. [TC-OO-2.1] Attributes with server as DUT PICS: - OO.S config: nodeId: 0x12344321 cluster: On/Off endpoint: 1 tests: - label: Step 1: Commission DUT to TH cluster: DelayCommands command: WaitForCommissionee arguments: values: - name: nodeId value: nodeId根据 yaml_schema.md文件顶层支持的关键字段有namestr测试名称PICSstr / list测试级别的 PICS 门控可在测试台中整体门控整个测试config全局配置区支持nodeIdint、clusterstr、endpointint以及自定义变量_variableName_配type与defaultValuetests测试步骤列表。每个步骤label为必填字符串可携带identity、nodeId、runIf、groupId、endpoint、cluster、attribute、command、event、eventNumber、disabled、fabricFiltered、verification、PICS、arguments、response、saveResponseAs、minInterval、maxInterval、keepSubscriptions、timeout、timedInteractionTimeoutMs、dataVersion、busyWaitMs、wait、minRevision、maxRevision等标签。其中nodeId、groupId、endpoint、dataVersion、minRevision、maxRevision、arguments/response内的部分取值支持变量见下文配置变量与 saveAs。常用动作一发送集群命令无参数命令最简单的测试步骤是向 DUT 发送一条不带参数的集群命令- label: This label gets printed cluster: On/Off command: Onlabel—— 执行该步骤前打印的说明文字cluster—— 命令所属集群名称command—— 要发送的命令名称。上述步骤即向 DUT 的 On/Off 集群发送On命令。对大多数测试而言DUT 的nodeID与目标endpoint定义在文件顶部的config区并自动应用于每个测试步骤当然也可以在单个步骤内覆盖。带参数命令带参数的集群命令示例如下- label: This label gets printed before the test step command: MoveToColor arguments: values: - name: ColorX value: 32768 - name: ColorY value: 19660 - name: TransitionTime value: 0 - name: OptionsMask value: 0 - name: OptionsOverride value: 0label—— 执行前打印的说明文字command—— 要发送的命令名称arguments—— 参数列表接受value或values两种标签。带参数的命令都使用结构化字段structured fields因此必须使用values标签加列表列表中的每个字段由一对name/value表示。注意上面示例省略了cluster标签——整个测试的集群可在顶部config区设置也可像上文那样在单个步骤中覆盖。常用动作二读写属性在 Matter 测试 YAML Schema 中属性读写被建模为一种特殊命令需要额外的attribute标签。读取属性- label: TH reads the ClusterRevision from DUT command: readAttribute attribute: ClusterRevision写入属性——写属性命令始终要求arguments标签- label: Write example attribute command: writeAttribute attribute: ExampleAttribute arguments: value: 1实际认证测试中这两者的组合非常典型例如 Test_TC_OO_2_1.yaml 中用readAttributeresponse.constraints校验OnOff属性类型为boolean、OnTime属性值域为 0~65535。解析响应response 标签与约束发送命令、读取或写入属性之后通常需要校验响应。这通过response标签及其子标签完成。下面的示例是带两个略显冗余检查的简单响应解析- label: TH reads the ClusterRevision from DUT command: readAttribute attribute: ClusterRevision response: value: 1 constraints: minValue: 1可用于解析响应的标签对照如下示例说明response:value: [1, 2, 3, 4]必须精确匹配。允许使用变量与 saveAs 保存的值response:values:- name: response_fieldvalue: 1必须精确匹配。用于返回带命名字段的命令响应的命令response:error: CONSTRAINT_ERROR期望收到错误成功场景下省略该项。变量与 saveAs 值在此不适用response:constraints:...更复杂的检查完整描述见 yaml_schema.mdresponse支持的内层字段包括value、name、error、clusterError、constraints、saveAs等。其中constraints下可用的子约束非常丰富hasValuebool是否必须存在值typestr期望的响应类型minLength/maxLengthint字符串长度范围isHexString、startsWith、endsWith、isUpperCase、isLowerCasebool / str字符串形态校验minValue/maxValueint/float数值范围支持变量contains/excludeslist列表包含 / 排除校验hasMasksSet/hasMasksClearlist位掩码校验notValue不等于某值支持变量anyOflist满足任一即可pythonstr自定义 Python 表达式校验支持变量。列表与结构体Lists and structs列表与结构体在测试中按以下方式表示列表[1,2,3,4,5]结构体{field1:value, field2:value}结构体列表[ { field1:value, field2:value, optionalfield:value }, { field1:value, field2:value }, ]需要注意结构体不同于命令与命令响应字段——后者使用name:、value:标签对来表示而前者使用内联的{field:value}语法。伪集群Pseudo-clusters测试经常需要一些并非严格基于集群的功能这类功能在 YAML 中通过**伪集群pseudo-clusters**支持。伪集群与 DUT 集群一样接受command标签来控制其行为。最常用的三类伪集群操作1) 建立与 DUT 的连接——几乎是每个测试的第一步- label: Establish a connection to the DUT cluster: DelayCommands command: WaitForCommissionee arguments: values: - name: nodeId value: nodeId2) 等待用户动作- label: Do a simple user prompt message. Expect y to pass. cluster: LogCommands command: UserPrompt arguments: values: - name: message value: Please enter y for success - name: expectedValue value: y3) 等待一段时间- label: Wait for 5S cluster: DelayCommands command: WaitForMs arguments: values: - name: ms value: 5000伪集群完整清单根据 yaml_pseudocluster.md由脚本generate_pseudo_cluster_doc_tables.py自动生成当前可用的伪集群及其命令如下伪集群命令主要参数CommissionerCommandsPairWithCode(nodeId, payload, discoverOnce 可选)、Unpair(nodeId)、GetCommissionerNodeId、GetCommissionerRootCertificate、IssueNocChain(Elements, nodeId) 及其对应*ResponseDelayCommandsWaitForCommissioning、WaitForCommissionee(nodeId, expireExistingSession 可选)、WaitForMs(ms)、WaitForMessage(registerKey, message)DiscoveryCommandsFindCommissionable、FindCommissionableByShortDiscriminator、FindCommissionableByLongDiscriminator、FindCommissionableByCommissioningMode、FindCommissionableByVendorId、FindCommissionableByDeviceType、FindCommissioner系列及FindResponseEqualityCommandsBooleanEquals(Value1, Value2)、SignedNumberEquals、UnsignedNumberEquals、EqualityResponse(Equals)LogCommandsLog(message)、UserPrompt(message, expectedValue 可选)SystemCommandsStart、Stop、Reboot、FactoryResetregisterKey 均可选、CreateOtaImage、CompareFiles、CreateFile、DeleteFile伪集群的完整参数与类型定义见 yaml_pseudocluster.md。此外仓库还内置了扩展伪集群目录默认scripts/tests/chipyaml/extensions其中包含 example_cluster.py 与 wildcard_response_extractor_cluster.py可用--additional_pseudo_clusters_directory指向自定义扩展目录。配置变量与 saveAs部分标签可以使用变量这些变量要么在config:区声明要么从其它步骤中保存而来。config中声明的变量可以在本地命令行或测试台的配置文件中覆盖。在 config 区声明变量使用期望的变量名作为标签并提供type与defaultValue子标签config: nodeId: 0x12344321 cluster: Unit Testing endpoint: 1 myArg1: type: int8u defaultValue: 5真实用例可参考 TestConfigVariables.yaml它在config中声明了arg1与returnValueWithArg1两个变量并在后续步骤中引用。从响应中保存变量- label: Send Test Add Arguments Command command: TestAddArguments arguments: values: - name: arg1 value: 3 - name: arg2 value: 17 response: values: - name: returnValue saveAs: TestAddArgumentDefaultValue value: 20在后续步骤中使用变量- label: Send Test Add Arguments Command command: TestAddArguments arguments: values: - name: arg1 value: 3 - name: arg2 value: 17 response: values: - name: returnValue value: TestAddArgumentDefaultValue哪些标签支持变量均已标注在 yaml_schema.md 中如nodeId、endpoint、groupId、dataVersion、minRevision、maxRevision、arguments.values.value、response.value、constraints.minValue/maxValue/notValue/python等均标记为支持变量。另外配置变量可用于在测试中实现 PIXIT 值Partially Implemented / X-matter Test Items即在测试时按环境注入的可配置项这是认证测试中非常实用的模式。门控机制PICS、runIf/TestEqualities 与 minRevision/maxRevisionPICS 门控PICS标签可用于基于 PICS 文件中的值对测试步骤进行无条件门控并支持标准的布尔运算!、||、、()。- label: Step 2: TH reads the OnOff attribute from the DUT PICS: OO.S.A0000 command: readAttribute attribute: OnOff将PICS标签置于文件顶层则可在测试台中对整个测试进行门控。注意整体测试门控目前在本地运行器与 CI 中尚未实现。runIf 与 TestEqualities有些测试步骤需要依据测试过程中产生的值来门控此时 PICS 无法胜任应改用runIf标签——它要求一个布尔值。若需要把数值转换成布尔值可以使用TestEqualities 伪集群即EqualityCommands。完整示例见 TestEqualities.yaml- label: Compute the result of comparing Arg1Value to 20003 and save the result as a variable for later use cluster: EqualityCommands command: UnsignedNumberEquals arguments: values: - name: Value1 value: Arg1Value - name: Value2 value: expectedValue response: - values: - name: Equals value: true saveAs: IsExpectedValue随后用保存的布尔变量门控步骤- label: Use runIf to skip this step runIf: IsUnexpectedValue cluster: EqualityCommands command: BooleanEquals arguments: values: - name: Value1 value: true - name: Value2 value: false该文件中的注释指出如果runIf为假则跳过步骤反之若执行了该步骤则会因为期望值true与实际结果不匹配而报错——这正是用来验证门控逻辑是否生效的技巧。minRevision / maxRevision除PICS与runIf外还有minRevision与maxRevision标签它们使用步骤中cluster的ClusterRevision属性决定步骤是否因仅适用于旧版或新版而跳过若集群ClusterRevision minRevision存在时或 maxRevision存在时该步骤被跳过。下面示例仅在ClusterRevision 3 时才检查指定属性值- label: Verify the minimum-to-support Max Paths Per Invoke value command: readAttribute attribute: MaxPathsPerInvoke minRevision: 3 # Attribute was added in revision 3, so this step applies # to revision 3. response: constraints: minValue: 1设置步骤超时与其它步骤选项timeout参数可用于每个测试步骤设置运行器在报告失败前等待该步骤完成的时间- label: A step with explicit timeout command: readAttribute attribute: OnOff timeout: 5000注意此超时不同于订阅subscription报告超时后者目前无法在 YAML 中调整。除timeout外测试步骤还支持timedInteractionTimeoutMs、busyWaitMs、wait、minInterval/maxInterval、keepSubscriptions、dataVersion、fabricFiltered、disabled、saveResponseAs等选项完整说明见 yaml_schema.md。运行 YAML 测试YAML 脚本由Python 运行器解析程序读取文件后把标签翻译成 chip-tool 命令并通过 socket 发送给运行在**交互模式interactive mode**下的 chip-tool。环境准备由于 YAML 运行器基于 Python使用任何 YAML 运行器脚本前都必须先编译并安装 chip Python 包。首先激活 Matter 环境二选一. ./scripts/bootstrap.sh或. ./scripts/activate.shbootstrap.sh用于首次环境搭建后续可改用更快的activate.sh。接着构建 Python wheels 并创建虚拟环境./scripts/build_python.sh -i out/python_env source out/python_env/bin/activate然后编译 chip-tool./scripts/build/build_examples.py --target linux-x64-chip-tool build注意请根据你的系统选择合适的目标平台target。配网 DUTCommissioning所有 YAML 测试都假定DUT 已预先配网完成。DUT 应使用 chip-tool 配网并在运行测试时使用同一个 KVS 文件。默认情况下测试使用节点 ID0x12344321该默认值同样定义在 scripts/tests/chiptest/test_definition.py 的TEST_NODE_ID 0x12344321。最简单的方式就是用这个节点 ID 配网或者也可以在命令行修改目标节点 ID。使用 chip-tool 的 pairing 命令配网例如./out/linux-x64-chip-tool/chip-tool pairing code 0x12344321 MT:-24J0AFN00KA0648G00其中0x12344321是节点 ID测试默认值MT:-24J0AFN00KA0648G00是配网二维码。使用 chiptool.py 运行测试chiptool.py 可用于对已配网的 DUT 运行测试./scripts/tests/chipyaml/chiptool.py tests Test_TC_OO_2_1 --server_path ./out/linux-x64-chip-tool/chip-tool注意请替换为合适的测试名与 chip-tool 路径。列出所有可用测试./scripts/tests/chipyaml/chiptool.py list配置变量可在脚本名后以--分隔传入./scripts/tests/chipyaml/chiptool.py tests Test_TC_OO_2_1 --server_path ./out/linux-x64-chip-tool/chip-tool -- nodeId 0x12344321每个测试都会定义默认目标端点根节点Root Node集群测试默认针对 endpoint 0其余大多数集群测试默认针对 endpoint 1。可以通过endpoint配置变量修改测试端点。从 chiptool.py 的源码看该脚本还支持以下实用选项--server_path指定要执行的 WebSocket 服务端路径通常是 chip-tool--server_name未提供server_path时按该名称在 SDK 目录树中搜索二进制默认chip-tool--server_arguments传给服务端的启动参数默认interactive server--show_adapter_logs显示适配器附加日志--trace_file/--trace_decode将追踪输出保存到文件并可解码为人类可读格式--delay-in-ms在测试套件每个步骤之间插入延迟默认 0--continueOnFailure首错后不停止继续执行整个测试套件默认 False--specifications_paths集群定义文件路径默认src/app/zap-templates/zcl/data-model/chip/*.xml--PICS使用的 PICS 文件路径默认src/app/tests/suites/certification/ci-pics-values--additional_pseudo_clusters_directory附加伪集群目录默认scripts/tests/chipyaml/extensions。恢复出厂Factory ResetDUT在主机上可通过删除 KVS 文件模拟恢复出厂。如果启动应用时未指定 KVS 文件位置KVS 文件默认位于/tmp文件名为chip_kvs。在 CI 中运行添加到认证目录src/app/tests/suites/certification/下的 YAML 测试会被自动运行对应的 PICS 文件为 src/app/tests/suites/certification/ci-pics-values如果不想让某个测试例如仍在开发中的进入 CI将其加入scripts/tests/chiptest/__init__.py中的_GetInDevelopmentTests即可。更多关于示例应用搭建、PICS 与 PIXIT 值在 CI 中的配置方法参见 CI testing。定义 CI 测试参数CI 块YAML 测试默认针对all-clusters应用运行。如果需要对不同应用或多组自定义参数运行同一测试可在 YAML 文件中加入CI条目它是一个包含name、app与args可选的列表CI: - name: This is displayed in logs # application name MUST be a supported placeholder app: all-clusters - name: Some other names app: rvc # Optional arguments, a list args: [--vendor-name, Testing] - name: Test against lit-icd app app: lit-icd # List can be split in separate lines args: - --vendor-name - test123应用名必须是受支持的占位符CI 运行时会替换为完整应用路径。真实示例见 Test_TC_OO_2_1.yaml 顶部的CI块它同时针对all-clusters与all-deviceson-off-light、on-off-plug-in-unit、mounted-on-off-control三种设备形态运行。当前支持的应用占位符包括完整列表见 scripts/tests/chiptest/test_definition.pyall-clustersbridgeclosureenergy-gatewayevsewater-heaterfabric-synclit-icdlockmicrowave-ovennetwork-managerota-requestorrvctv在测试台TH中运行Matter 认证测试通常也可在官方测试台Test HarnessTH环境中运行测试台会对 YAML 测试进行可视化展示与逐步骤交互。原文档指出目前尚无指向最新 TH 文档的永久链接如需在 TH 中运行请以官方测试台部署文档为准并结合本文的 YAML 编写规范组织测试文件。总结与进一步阅读Matter 的 YAML 测试体系把可读的测试描述与可执行的测试逻辑分离编写者只需按照 yaml_schema.md 的规范组织步骤运行器chiptool.py负责将其翻译为 chip-tool 命令。掌握本文中的命令发送、属性读写、响应约束、伪集群、变量与saveAs、PICS/runIf/minRevision门控以及本地与 CI 的运行/参数定义方式即可为任意 Matter 集群编写并落地一套可复用的自动化测试。可进一步阅读与参考YAML Schema 完整定义YAML 伪集群完整命令表TestEqualities.yamlrunIf 门控实战TestConfigVariables.yaml配置变量实战Test_TC_OO_2_1.yaml认证测试 CI 块实战CI 测试说明【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考