CANN cann-samples 功能测试清单契约与 CI 执行指南读懂ci_functional_test.yaml与 manifest 驱动测试体系【免费下载链接】cann-samplesCANN高性能实战演进样例与体系化调优知识库项目地址: https://gitcode.com/cann/cann-samplestests/README.md是 cann-samples 仓库中功能测试清单manifest的契约文档它定义了tests/ci_functional_test.yaml的字段结构、补充规则与维护边界并把执行入口统一指向.ci/README.md。本文以该契约文档为主体结合仓库中实际的清单文件 tests/ci_functional_test.yaml 与执行脚本.ci/run_ci_functional.sh、.ci/run_ci_functional.py完整讲清这套清单即测试体系如何为每个样例编写 setup / steps / pass_criteria如何运行单条或多条功能测试以及当前契约的适用边界。读完本文你可以独立为仓库中任意一个可自动判定的样例编写并接入功能测试清单。定位测试清单的维护规则与字段契约cann-samples 是一个包含大量.asc算子内核样例、配套scripts/gen_data.py数据生成脚本与scripts/verify_result.py校验脚本的实战样例仓库。为了保证每个样例可构建、可运行、可判定仓库在 tests/ 目录下维护了一份功能测试清单并明确划分了两层职责tests/README.md只说明测试清单的维护规则和字段契约即本文讲解的 YAML 结构.ci/README.md只说明执行入口的用途和调用方式即构建、运行、产物输出的具体命令。二者互相引用、职责互补清单负责测什么、怎么判.ci负责怎么跑、结果放哪。这一点从两份 README 的首句即可看出——tests/README.md 明确写道执行入口、构建命令、artifact 输出统一见.ci/README.md而 .ci/README.md 则反向引用 tests/README.md 说明清单维护方式。与之配套的文件包括主清单tests/ci_functional_test.yaml目前收录 3 个样例vector_add、matmul_basic、hif8_quantize执行入口Shell 包装器.ci/run_ci_functional.shPython runnermanifest 驱动执行器.ci/run_ci_functional.py。YAML 契约清单文件的字段结构tests/ci_functional_test.yaml是一个严格受限的 YAML 文档顶层字段只有两个顶层字段说明version清单契约版本号当前实际清单中为1samples样例条目列表每个条目描述一个可独立运行与判定的功能测试每个samples条目只允许包含以下四个字段不允许携带其他自定义字段条目字段类型说明id字符串样例的唯一稳定标识如hif8_quantizesetup列表前置动作如生成输入数据可为空列表[]steps列表实际执行与校验步骤pass_criteria映射可机器判断的通过条件而每个setup/steps条目统一由三个字段构成步骤字段说明name步骤名便于阅读日志与定位失败点cwd命令执行的工作目录使用仓库相对路径见下文约束cmd命令本身必须是 argv 数组四条硬性约束契约对清单写法有明确的约束违反了会导致清单不可用或不可维护cmd必须是 argv 数组不要写 shell 拼接命令。例如应写成cmd: [python3, scripts/gen_data.py]而不是cmd: python3 scripts/gen_data.py ./quantize_hif8_demo。argv 数组形式让 runner 可以直接以 exec 方式拉起进程避免 shell 转义与拼接带来的歧义也便于逐个步骤捕获 stdout / stderr 与退出码。cwd使用仓库相对路径。这意味着清单中的工作目录是相对于仓库根目录解析的而不是相对清单文件自身的位置。从实际清单可以看出cwd统一指向构建产物目录build_out/...与源码目录的层次一一对应详见下文构建产物与源码的对应。id保持稳定不要随意改名。id是 runner 选择单条样例运行时的匹配键如bash .ci/run_ci_functional.sh --sample vector_add改名会导致历史命令与产物目录的对应关系失效。不能自动判定 PASS/FAIL 的样例不要先放进清单。清单只收录有明确机器可判定的通过条件的样例凡是需要人工观察输出才能确认结果的功能不应进入ci_functional_test.yaml。通过条件pass_criteria从实际清单看支持的判定模式tests/README.md的契约正文只给出了all_steps_exit_zero: true这一种写法但当前仓库的实际清单 tests/ci_functional_test.yaml 已经使用了更多判定字段。从清单的实际用法可以推断出以下模式pass_criteria 字段语义从清单用法推断使用样例exit_code单步命令的退出码必须等于指定值exit_code: 0即要求退出码为 0vector_add、matmul_basicstdout_contains步骤输出必须包含指定字符串可多个vector_add、matmul_basicstdout_not_contains步骤输出不得包含指定字符串可多个vector_add、matmul_basicall_steps_exit_zero所有步骤退出码必须均为 0hif8_quantizefinal_stdout_contains最终最后一个步骤的输出必须包含指定字符串hif8_quantize以 tests/ci_functional_test.yaml 中的vector_add条目为例它同时使用了退出码、正向关键字与负向关键字三重判定- id: vector_add setup: [] steps: - name: run_default cwd: build_out/0_Introduction/vector_add cmd: [./vector_add] pass_criteria: exit_code: 0 stdout_contains: - Vector add completed successfully! stdout_not_contains: - Vector add failed!matmul_basic条目则展示了如何为同一个样例固化一组具体入参——它把矩阵乘法用例的维度直接写进cmd- id: matmul_basic setup: [] steps: - name: run_case_128_256_512 cwd: build_out/0_Introduction/matmul cmd: [./matmul, 128, 256, 512] pass_criteria: exit_code: 0 stdout_contains: - matmul run successfully! stdout_not_contains: - matmul run failed!这种成功关键字 失败关键字的成对写法非常实用正向关键字证明功能确实执行到了成功路径负向关键字防止程序崩溃但恰好没走到失败分支的假阳性。最小示例拆解hif8_quantize 的完整流程tests/README.md给出的最小示例是hif8_quantize它同时用到了setup、多步骤steps与all_steps_exit_zero/final_stdout_contains是理解整份契约最完整的样本- id: hif8_quantize setup: - name: gen_input cwd: build_out/1_Features/hardware_features/hif8 cmd: [python3, scripts/gen_data.py] steps: - name: run_demo cwd: build_out/1_Features/hardware_features/hif8 cmd: [./quantize_hif8_demo] - name: verify_output cwd: build_out/1_Features/hardware_features/hif8 cmd: - python3 - scripts/verify_result.py - output/output_y.bin - output/golden_y.bin pass_criteria: all_steps_exit_zero: true final_stdout_contains: - test pass这个样例对应仓库源码目录 Samples/1_Features/hardware_features/hif8其运行流程完整覆盖了三种典型动作setup 阶段生成输入数据。gen_input步骤调用scripts/gen_data.py为算子准备输入张量与 golden 参照数据steps 阶段执行算子 demo。run_demo步骤运行编译产物./quantize_hif8_demo完成 hif8 量化计算并写出output/output_y.binsteps 阶段自动化校验。verify_output步骤调用 scripts/verify_result.py以output/output_y.bin与output/golden_y.bin为参数比对计算结果并在通过时打印test pass。通过条件all_steps_exit_zero: true要求 setup 与两个 steps 全部以退出码 0 结束final_stdout_contains: [test pass]则进一步要求最后的校验脚本明确输出了通过标记——这正是不能自动判定 PASS/FAIL 的样例不要放进清单这一约束的最佳注解。构建产物与源码的对应关系清单中的cwd全部以build_out/开头这与 .ci/README.md 所述构建、安装、打包build_out的流程对应样例源码经 CMake 构建后输出到build_out/目录目录层级与源码保持一致。例如build_out/0_Introduction/vector_add← 源码 Samples/0_Introduction/vector_addbuild_out/0_Introduction/matmul← 源码 Samples/0_Introduction/matmulbuild_out/1_Features/hardware_features/hif8← 源码 Samples/1_Features/hardware_features/hif8补充清单时只做四件事tests/README.md把往清单里加一个样例收敛为四个固定动作避免维护者凭感觉扩写选定稳定的运行目录和命令确定该样例在build_out/下的工作目录以及可复现的 argv 命令把前置动作写进setup凡是运行前必须做的数据生成、环境准备一律放到setup步骤中而不是塞进cmd做 shell 拼接把执行和校验写进steps算子执行与结果比对分开成独立步骤便于定位失败发生在运行期还是校验期用pass_criteria定义可机器判断的通过条件至少给出退出码要求配合成功/失败关键字或最终输出关键字。四件事做完一个样例就可以安全地进入清单并在 CI 中自动判定。执行入口与产物输出清单本身不负责执行运行由 .ci/run_ci_functional.sh 与 .ci/run_ci_functional.py 承担。Shell 包装器.ci/run_ci_functional.sh 是一个极简的 thin wrapper脚本先切换到仓库根目录然后以环境变量提供默认值——MANIFEST_PATH默认为tests/ci_functional_test.yaml、ARTIFACTS_DIR默认为test_artifacts/ci_functional——随后调用bash .ci/build.sh完成构建再调用 Python runner 并把额外参数透传给它。常用命令构建与运行的前提是当前机器可正常使用cmake、python3、CANN 工具链和设备运行时并安装依赖pip install -r requirements.txt pip install -r .ci/requirements.txt仅构建构建、安装、打包build_outbash .ci/build.sh执行完整功能测试bash .ci/run_ci_functional.sh只跑一个 sample按清单中的id筛选bash .ci/run_ci_functional.sh --sample vector_add覆盖清单路径或产物目录MANIFEST_PATHtests/ci_functional_test.yaml \ ARTIFACTS_DIRtest_artifacts/ci_functional \ bash .ci/run_ci_functional.sh已手动完成 build/install 后跳过包装脚本直接执行 runnerpython3 .ci/run_ci_functional.py --manifest tests/ci_functional_test.yaml说明.ci/README.md中将构建入口描述为build.sh当前仓库快照的 .ci/ 目录中未包含该文件因此本文的命令部分以实际存在的run_ci_functional.sh/run_ci_functional.py为准。产物输出按 .ci/README.md 的约定功能测试输出落在默认目录test_artifacts/ci_functional/内容包括summary.json整体测试汇总结果每一步的stdout各步骤标准输出每一步的stderr各步骤错误输出每一步的退出码用于对照pass_criteria中的exit_code/all_steps_exit_zero判定。当前边界与演进方向tests/README.md在末尾明确给出了当前契约的三条边界这有助于理解该测试体系的定位当前只支持最小功能测试契约只覆盖可运行、可校验的功能性判定不追求复杂测试框架能力当前不导出 JUnit测试结果不以 JUnit XML 等标准格式对外输出消费方需要解析summary.json当前不包含性能测试性能、带宽、耗时类评测不在功能测试清单的职责范围内。这三条边界意味着需要接入性能测试或 JUnit 报告的团队应在.ci执行层另行扩展而不是往ci_functional_test.yaml里塞超出契约的字段。总结cann-samples 的测试体系建立在清单契约 manifest 驱动执行器的清晰分层之上tests/ci_functional_test.yaml用严格受限的 YAML 描述测什么、怎么判.ci/run_ci_functional.sh与.ci/run_ci_functional.py负责怎么跑、结果放哪。维护者只需遵循四条约束argv 数组、仓库相对路径、稳定 id、可自动判定、按四步法补充条目就能把任意一个具备自动化判定能力的样例接入 CI。对于希望在 CANN 算子开发中沉淀可回归、可自动验收样例的团队而言这套契约提供了一份轻量且可复制的范式。【免费下载链接】cann-samplesCANN高性能实战演进样例与体系化调优知识库项目地址: https://gitcode.com/cann/cann-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考