算子测试计划与结果模板
本模板用于在新增算子、修改接口、优化实现或修复缺陷时记录测试范围和执行结果。它关注正确性、边界、异常输入、兼容性和回归风险；性能数据应采用独立且同口径的 benchmark 记录。
使用规则
- 在开发前填写“测试范围”和“用例设计”，用于确认本次变更需要覆盖什么。
- 在提交 PR 前填写“执行环境”“执行结果”和“未覆盖风险”。
- 每个用例应能够映射到一个接口约束、代码分支、缺陷或回归风险。
- 正确性结果必须说明参考实现和比较标准。精确算子不要只使用
allclose，近似算子不要只写“结果一致”。 - 没有 NPU 环境时可填写静态检查或
dry_run，但不能把未执行用例标记为通过。 - 不在文档中粘贴大段日志、设备地址、账号、令牌、私有数据或内部链接。
模板正文
# `<operator_name>` 测试计划与结果
## 变更摘要
- 关联 PR / Issue：`<链接或编号>`
- 变更类型：`<新增算子 / 接口变更 / 实现优化 / 缺陷修复 / 文档补测>`
- 影响范围：`<op_host / tiling / op_kernel / wrapper / example / build>`
- 主要风险：`<接口兼容、shape 边界、dtype、数值精度、多核、workspace 等>`
## 被测接口
| 项目 | 内容 |
| --- | --- |
| 算子名称 | `<operator_name>` |
| 调用方式 | `<ACLNN / PyTorch Extension / 直调 / 其他>` |
| 输入 | `<名称、顺序和必选/可选>` |
| 输出 | `<名称、顺序和必选/可选>` |
| 属性 | `<名称、类型、默认值和值域>` |
| 参考实现 | `<PyTorch / NumPy / CPU 实现 / 数学定义>` |
## 测试范围
### 测试因子
| 因子 | 取值或分组 | 选择依据 |
| --- | --- | --- |
| dtype | `<例如 FP16 / FP32 / INT32>` | `<接口支持集合>` |
| shape / rank | `<典型、小边界、大边界、动态 shape>` | `<接口约束或巡检 workload>` |
| format / layout | `<ND / NCHW / 其他>` | `<注册定义>` |
| 属性组合 | `<默认值、边界值、开关组合>` | `<分支覆盖>` |
| 数据分布 | `<随机、全相同、已排序、重复值、稀疏、极值>` | `<算法特性>` |
| 特殊值 | `<0、负数、NaN、Inf、最大/最小值；不适用则删除>` | `<数值风险>` |
| 调用入口 | `<Python / ACLNN C++ / 其他>` | `<公开接口>` |
### 不在本次范围
- `<明确列出不支持、未实现或由其他 PR 验证的内容>`
## 正确性标准
| 输出 | 参考结果 | 比较方式 | 阈值或规则 |
| --- | --- | --- | --- |
| `<output>` | `<reference>` | `<exact / atol+rtol / 指标>` | `<具体值或公式>` |
补充规则：
- 随机输入固定 seed：`<seed>`。
- 有效输出区间：`<例如 output[:unique_count]>`。
- 可选输出关闭时的期望行为：`<不存在 / 空 Tensor / 内容未定义>`。
- 多输出关系：`<例如 output[inverse[i]] == input[i]>`。
- 梯度验证：`<解析参考 / autograd / 数值差分 / 不适用>`。
## 用例设计
### 基础正确性
| ID | dtype | shape | 属性 | 数据特征 | 检查点 | 预期 |
| --- | --- | --- | --- | --- | --- | --- |
| FUNC-001 | `<dtype>` | `<shape>` | `<attrs>` | `<distribution>` | `<outputs>` | `<expected>` |
### 边界用例
| ID | 边界 | 输入 | 检查点 | 预期 |
| --- | --- | --- | --- | --- |
| BOUND-001 | `<最小合法 shape>` | `<input>` | `<output / status>` | `<expected>` |
| BOUND-002 | `<分块、对齐或多核边界>` | `<input>` | `<output / status>` | `<expected>` |
建议按算子情况考虑：
- 最小合法元素数或 batch。
- tile、block、workspace 或对齐边界的前一项、边界值和后一项。
- 单核与多核切换点。
- 动态 shape 的最小值、典型值和最大声明值。
- 可选输出或属性的所有有效组合。
### 异常输入
| ID | 非法条件 | 输入 | 期望错误 | 判定方式 |
| --- | --- | --- | --- | --- |
| NEG-001 | `<不支持 dtype / rank / shape / 属性>` | `<input>` | `<错误码或明确失败>` | `<日志、返回值或异常类型>` |
不要把崩溃、卡死或静默错误当作可接受的异常处理。
### 回归用例
| ID | 来源 | 防止回归的问题 | 输入 | 检查点 |
| --- | --- | --- | --- | --- |
| REG-001 | `<Issue / 历史缺陷 / 关键场景>` | `<bug description>` | `<input>` | `<expected>` |
### 电力巡检场景用例
| ID | 场景 | workload 表征 | 输入规模 | 业务相关检查点 |
| --- | --- | --- | --- | --- |
| SCENE-001 | `<视觉 / 点云 / 语音 / 通用支撑>` | `<数据特征>` | `<shape>` | `<只写可验证行为>` |
业务场景用例用于确认输入规模和数据特征，不用于替代端到端业务效果验证。
## 执行环境
| 项目 | 内容 |
| --- | --- |
| 芯片 / 设备 | `<model>` |
| CANN | `<version>` |
| 驱动 / 固件 | `<version>` |
| Python | `<version 或不适用>` |
| PyTorch / torch_npu | `<version 或不适用>` |
| 编译器 | `<version>` |
| Commit | `<sha>` |
## 执行命令
标明工作目录：
```bash
cd <working-directory>
<build command>
<test command>
```
## 执行结果
| 用例 ID | 状态 | 关键结果 | 证据位置 | 备注 |
| --- | --- | --- | --- | --- |
| FUNC-001 | `<PASS / FAIL / BLOCKED / NOT_RUN>` | `<误差、输出或错误码>` | `<日志文件或命令输出摘要>` | `<notes>` |
状态定义：
- `PASS`：已实际执行并满足预期。
- `FAIL`：已执行但不满足预期。
- `BLOCKED`：受环境、依赖或硬件条件阻塞。
- `NOT_RUN`：未执行，必须说明原因。
## 失败分析
| 用例 ID | 现象 | 初步定位 | 处理计划 | 是否阻塞合入 |
| --- | --- | --- | --- | --- |
| `<ID>` | `<symptom>` | `<evidence-based diagnosis>` | `<fix / follow-up>` | `<yes / no>` |
## 覆盖摘要
| 维度 | 已覆盖 | 未覆盖 |
| --- | --- | --- |
| dtype | `<list>` | `<list>` |
| shape / rank | `<list>` | `<list>` |
| 属性组合 | `<list>` | `<list>` |
| 调用入口 | `<list>` | `<list>` |
| 正确性 / 梯度 | `<list>` | `<list>` |
| 异常输入 | `<list>` | `<list>` |
## 未覆盖风险
- `<未覆盖项、原因、可能影响和后续计划>`
## 结论
- 总用例数：`<count>`
- PASS：`<count>`
- FAIL：`<count>`
- BLOCKED：`<count>`
- NOT_RUN：`<count>`
- 合入建议：`<通过 / 修复后通过 / 暂不建议合入>`
提交前检查
- 测试因子来自真实接口约束，不是任意枚举。
- 用例覆盖基础、边界、异常输入和回归风险。
- 每个 PASS 都有实际执行命令和可复核结果。
- 参考实现、随机种子、有效输出区间和误差标准已记录。
- BLOCKED、NOT_RUN 和未覆盖风险没有被隐藏。
- 测试结果中不包含敏感信息、私有数据或不可访问的本地路径。