@ohos-cpf/3rdloop 0.0.2 → 0.0.3

package/vendor/Server/Skills/arkts-library-xts-doc/references/TESTABILITY_GUIDE.md

@@ -1,182 +1,182 @@
-# 可测试性判断指南
-
-> 本文档提供接口可测试性判断的详细标准、分类示例和不可测试原因分析。
-
----
-
-## 1. 可测试性判断标准
-
-### 1.1 ✅ 可生成XTS用例的接口特征
-
-1. **纯函数**：输入相同参数，输出结果可预测、可重复
-2. **无UI操作**：不涉及UI组件的创建、渲染、交互
-3. **结果可验证**：可通过返回值、状态变化、回调结果等判断功能正确性
-4. **无外部依赖限制**：不依赖不可控的外部因素（如网络请求需Mock、传感器需模拟器支持）
-
-### 1.2 ❌ 不可生成XTS用例的接口特征
-
-1. **涉及UI操作**：如创建组件、触发UI事件、渲染图形界面
-2. **依赖外部不可控因素**：如实时网络请求、硬件传感器、系统广播
-3. **结果不可验证**：如回调未定义、异步操作无返回值、副作用不可观测
-4. **纯展示型接口**：如仅用于展示信息、不执行具体功能
-
-### 1.3 ⚠️ 可测试（需额外条件）
-
-某些接口本身逻辑可测试，但依赖外部资源或特定条件：
-
-| 条件类型 | 示例 | 处理方式 |
-|---------|------|----------|
-| 需Mock网络 | `fetchData(url)` | 在用例描述中标注"需要Mock网络请求" |
-| 需异步等待 | `debounce(func, wait)` | 在用例中设置合理等待时间 |
-| 需前置状态 | `execute()` 需先 `init()` | 在用例中说明前置调用步骤 |
-
----
-
-## 2. 接口分类示例
-
-```
-接口分类示例：
-┌─────────────────────────────────────────────────────┐
-│ 接口名称          │ 可测试性 │ 原因说明                │
-├─────────────────────────────────────────────────────┤
-│ calculate(x, y)   │ ✅ 可测试 │ 纯函数，返回计算结果     │
-│ renderUI()        │ ❌ 不可测 │ 涉及 UI 操作            │
-│ fetchData(url)    │ ⚠️ 可测试 │ 需 Mock 网络请求后验证   │
-│ logMessage(msg)   │ ❌ 不可测 │ 仅日志输出，不可验证      │
-│ setConfig(cfg)    │ ✅ 可测试 │ 配置后可通过 getConfig 验证│
-└─────────────────────────────────────────────────────┘
-```
-
----
-
-## 3. 不可测试接口原因分类
-
-### 3.1 UI相关
-
-涉及UI操作、组件创建、界面渲染的接口无法通过执行结果直接验证。
-
-| 接口模式 | 不可测试原因 |
-|---------|-------------|
-| `@Component struct` 标记的UI组件 | 涉及UI组件创建和渲染 |
-| `renderUI()` / `drawCanvas()` | 渲染结果需视觉验证 |
-| `showDialog()` / `showToast()` | UI弹窗需界面交互验证 |
-
-### 3.2 输出型
-
-仅产生日志输出、无返回值、无状态变化的接口。
-
-| 接口模式 | 不可测试原因 |
-|---------|-------------|
-| `logMessage(msg: string): void` | 仅日志输出，无返回值和状态变化 |
-| `printDebug(info: string): void` | 输出不可捕获验证 |
-
-### 3.3 外部依赖
-
-依赖不可控外部因素的接口。
-
-| 接口模式 | 不可测试原因 |
-|---------|-------------|
-| `onEvent(callback)` | 回调触发依赖外部事件，不可控 |
-| `readSensor()` | 依赖硬件传感器，需模拟器支持 |
-| `subscribeBroadcast()` | 依赖系统广播，不可控 |
-
-### 3.4 回调型
-
-回调触发条件不可控或不可验证的接口。
-
-| 接口模式 | 不可测试原因 |
-|---------|-------------|
-| `onEvent(callback: Function): void` | 回调触发条件不可控 |
-| `addListener(type, handler)` | 事件触发依赖外部条件 |
-
----
-
-## 4. 常见问题处理
-
-### Q1: 如何判断接口是否可测试？
-
-核心判断依据：
-- 是否为纯函数（输入固定 → 输出可预测）
-- 是否涉及UI操作
-- 是否可通过执行结果验证功能正确性
-
-### Q2: 某接口依赖网络请求，是否可生成用例？
-
-可生成用例，但需在用例描述中注明"需要Mock网络请求或使用测试服务器"。
-
-### Q3: 多个接口如何组合到一个用例中？
-
-确保接口间存在调用依赖关系、协同完成功能流程或状态变化验证关系。
-
-### Q4: 如何设计空值/异常/边界值用例？
-
-参考本文档「七、空值与异常场景设计规范」及 [用例模板与编写规范](TEMPLATE.md) 中的模板。
-
----
-
-## 5. 接口类型测试规则
-
-| 接口类型 | 可测试性 | 说明 |
-|----------|----------|------|
-| `@Component struct` | ❌ 不可测 | UI 组件，不生成 XTS 用例 |
-| `interface` / `type` | ❌ 不可测 | 仅类型声明，无可执行逻辑 |
-| `private` / `protected` 成员 | ❌ 不可测 | 非对外 API，黑盒测试语法不可引用，不生成用例 |
-| `public static readonly` 常量 | ❌ 不可测 | 编译期固定、无行为回归，不生成用例 |
-| `lib*.so` Native 导出 | ⚠️ 慎重 | 需要 ArkTS 层的 wrapper 才能测试 |
-| 枚举（enum） | ✅ 可测 | 可通过 `import { EnumName } from 'library'` 后验证值 |
-| `setXxx()` + `getXxx()` 配对 | ✅ 可测 | setter/getter 合并为一个用例，`setConfig` → `getConfig` 验证 |
-| 纯函数 | ✅ 可测 | 输入固定 → 输出可预测 |
-| 回调派发型 | ✅ 可测 | 注入 Mock 实现验证回调透传，不再归类为「回调依赖外部事件不可测」（如 `onLeScan` / `notifyScanStarted`） |
-| 硬件依赖 void 型 | ⚠️ 可测 | 常态不抛异常 + 状态机/后续行为间接受影响；需 Mock 或真机（如 `enableBluetooth` / `scan` / `*MsgInit`） |
-| 依赖外部资源 | ⚠️ 需条件 | 在用例描述中标注 Mock 要求 |
-
----
-
-## 6. 用例设计原则
-
-1. **功能覆盖**：每个可测试接口至少有 1 个正向用例
-2. **接口关联**：一个用例可包含多个关联接口，展示协同使用方式
-3. **预期明确**：每个用例必须有明确、可验证的预期结果
-4. **描述清晰**：用例描述需帮助开发者理解功能和实现方式
-5. **空值覆盖**：每个可测试接口至少有 1 个空值/null/undefined 输入用例
-6. **异常/边界值覆盖**：每个可测试接口至少有 1 个异常参数或边界值输入用例
-7. **大数据覆盖**：对于接受数组、字符串、对象等集合类型参数的接口，至少有 1 个大数据量输入用例
-
----
-
-## 7. 多接口用例设计
-
-**何时将多个接口放在同一用例中：**
-
-- 接口之间存在明显的调用依赖关系（如 `init` → `execute` → `getResult`）
-- 接口协同完成一个完整功能流程（如 `create` → `configure` → `start`）
-- 接口之间存在状态变化关系（如 `setConfig` → `getConfig` 验证）
-
----
-
-## 8. 空值与异常场景设计规范
-
-### 8.1 空值场景（Null/Undefined/Empty）
-
-- 传入 `null` 作为参数，验证接口是否抛出异常或返回安全默认值
-- 传入 `undefined`，验证默认参数处理逻辑
-- 传入空字符串 `''`、空数组 `[]`、空对象 `{}`
-
-### 8.2 异常/边界值场景（Exception/Boundary）
-
-- 传入类型不匹配的参数，验证类型校验能力
-- 传入超限值，验证边界处理
-- 传入特殊值（`NaN`、`Infinity`），验证特殊数值处理
-
-### 8.3 大数据场景（Large Data）
-
-- 传入大数组（10000+ 元素），验证性能和正确性
-- 传入大字符串（10000+ 字符），验证长字符串处理能力
-- 验证大数据场景下不发生内存溢出、栈溢出或超时
-
----
-
-## 9. 用例编号规则
-
-- 用例序号采用三位补零格式：`001`、`002`、`003`...
-- 序号按模块分组递增，便于管理
+# 可测试性判断指南
+
+> 本文档提供接口可测试性判断的详细标准、分类示例和不可测试原因分析。
+
+---
+
+## 1. 可测试性判断标准
+
+### 1.1 ✅ 可生成XTS用例的接口特征
+
+1. **纯函数**：输入相同参数，输出结果可预测、可重复
+2. **无UI操作**：不涉及UI组件的创建、渲染、交互
+3. **结果可验证**：可通过返回值、状态变化、回调结果等判断功能正确性
+4. **无外部依赖限制**：不依赖不可控的外部因素（如网络请求需Mock、传感器需模拟器支持）
+
+### 1.2 ❌ 不可生成XTS用例的接口特征
+
+1. **涉及UI操作**：如创建组件、触发UI事件、渲染图形界面
+2. **依赖外部不可控因素**：如实时网络请求、硬件传感器、系统广播
+3. **结果不可验证**：如回调未定义、异步操作无返回值、副作用不可观测
+4. **纯展示型接口**：如仅用于展示信息、不执行具体功能
+
+### 1.3 ⚠️ 可测试（需额外条件）
+
+某些接口本身逻辑可测试，但依赖外部资源或特定条件：
+
+| 条件类型 | 示例 | 处理方式 |
+|---------|------|----------|
+| 需Mock网络 | `fetchData(url)` | 在用例描述中标注"需要Mock网络请求" |
+| 需异步等待 | `debounce(func, wait)` | 在用例中设置合理等待时间 |
+| 需前置状态 | `execute()` 需先 `init()` | 在用例中说明前置调用步骤 |
+
+---
+
+## 2. 接口分类示例
+
+```
+接口分类示例：
+┌─────────────────────────────────────────────────────┐
+│ 接口名称          │ 可测试性 │ 原因说明                │
+├─────────────────────────────────────────────────────┤
+│ calculate(x, y)   │ ✅ 可测试 │ 纯函数，返回计算结果     │
+│ renderUI()        │ ❌ 不可测 │ 涉及 UI 操作            │
+│ fetchData(url)    │ ⚠️ 可测试 │ 需 Mock 网络请求后验证   │
+│ logMessage(msg)   │ ❌ 不可测 │ 仅日志输出，不可验证      │
+│ setConfig(cfg)    │ ✅ 可测试 │ 配置后可通过 getConfig 验证│
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 不可测试接口原因分类
+
+### 3.1 UI相关
+
+涉及UI操作、组件创建、界面渲染的接口无法通过执行结果直接验证。
+
+| 接口模式 | 不可测试原因 |
+|---------|-------------|
+| `@Component struct` 标记的UI组件 | 涉及UI组件创建和渲染 |
+| `renderUI()` / `drawCanvas()` | 渲染结果需视觉验证 |
+| `showDialog()` / `showToast()` | UI弹窗需界面交互验证 |
+
+### 3.2 输出型
+
+仅产生日志输出、无返回值、无状态变化的接口。
+
+| 接口模式 | 不可测试原因 |
+|---------|-------------|
+| `logMessage(msg: string): void` | 仅日志输出，无返回值和状态变化 |
+| `printDebug(info: string): void` | 输出不可捕获验证 |
+
+### 3.3 外部依赖
+
+依赖不可控外部因素的接口。
+
+| 接口模式 | 不可测试原因 |
+|---------|-------------|
+| `onEvent(callback)` | 回调触发依赖外部事件，不可控 |
+| `readSensor()` | 依赖硬件传感器，需模拟器支持 |
+| `subscribeBroadcast()` | 依赖系统广播，不可控 |
+
+### 3.4 回调型
+
+回调触发条件不可控或不可验证的接口。
+
+| 接口模式 | 不可测试原因 |
+|---------|-------------|
+| `onEvent(callback: Function): void` | 回调触发条件不可控 |
+| `addListener(type, handler)` | 事件触发依赖外部条件 |
+
+---
+
+## 4. 常见问题处理
+
+### Q1: 如何判断接口是否可测试？
+
+核心判断依据：
+- 是否为纯函数（输入固定 → 输出可预测）
+- 是否涉及UI操作
+- 是否可通过执行结果验证功能正确性
+
+### Q2: 某接口依赖网络请求，是否可生成用例？
+
+可生成用例，但需在用例描述中注明"需要Mock网络请求或使用测试服务器"。
+
+### Q3: 多个接口如何组合到一个用例中？
+
+确保接口间存在调用依赖关系、协同完成功能流程或状态变化验证关系。
+
+### Q4: 如何设计空值/异常/边界值用例？
+
+参考本文档「七、空值与异常场景设计规范」及 [用例模板与编写规范](TEMPLATE.md) 中的模板。
+
+---
+
+## 5. 接口类型测试规则
+
+| 接口类型 | 可测试性 | 说明 |
+|----------|----------|------|
+| `@Component struct` | ❌ 不可测 | UI 组件，不生成 XTS 用例 |
+| `interface` / `type` | ❌ 不可测 | 仅类型声明，无可执行逻辑 |
+| `private` / `protected` 成员 | ❌ 不可测 | 非对外 API，黑盒测试语法不可引用，不生成用例 |
+| `public static readonly` 常量 | ❌ 不可测 | 编译期固定、无行为回归，不生成用例 |
+| `lib*.so` Native 导出 | ⚠️ 慎重 | 需要 ArkTS 层的 wrapper 才能测试 |
+| 枚举（enum） | ✅ 可测 | 可通过 `import { EnumName } from 'library'` 后验证值 |
+| `setXxx()` + `getXxx()` 配对 | ✅ 可测 | setter/getter 合并为一个用例，`setConfig` → `getConfig` 验证 |
+| 纯函数 | ✅ 可测 | 输入固定 → 输出可预测 |
+| 回调派发型 | ✅ 可测 | 注入 Mock 实现验证回调透传，不再归类为「回调依赖外部事件不可测」（如 `onLeScan` / `notifyScanStarted`） |
+| 硬件依赖 void 型 | ⚠️ 可测 | 常态不抛异常 + 状态机/后续行为间接受影响；需 Mock 或真机（如 `enableBluetooth` / `scan` / `*MsgInit`） |
+| 依赖外部资源 | ⚠️ 需条件 | 在用例描述中标注 Mock 要求 |
+
+---
+
+## 6. 用例设计原则
+
+1. **功能覆盖**：每个可测试接口至少有 1 个正向用例
+2. **接口关联**：一个用例可包含多个关联接口，展示协同使用方式
+3. **预期明确**：每个用例必须有明确、可验证的预期结果
+4. **描述清晰**：用例描述需帮助开发者理解功能和实现方式
+5. **空值覆盖**：每个可测试接口至少有 1 个空值/null/undefined 输入用例
+6. **异常/边界值覆盖**：每个可测试接口至少有 1 个异常参数或边界值输入用例
+7. **大数据覆盖**：对于接受数组、字符串、对象等集合类型参数的接口，至少有 1 个大数据量输入用例
+
+---
+
+## 7. 多接口用例设计
+
+**何时将多个接口放在同一用例中：**
+
+- 接口之间存在明显的调用依赖关系（如 `init` → `execute` → `getResult`）
+- 接口协同完成一个完整功能流程（如 `create` → `configure` → `start`）
+- 接口之间存在状态变化关系（如 `setConfig` → `getConfig` 验证）
+
+---
+
+## 8. 空值与异常场景设计规范
+
+### 8.1 空值场景（Null/Undefined/Empty）
+
+- 传入 `null` 作为参数，验证接口是否抛出异常或返回安全默认值
+- 传入 `undefined`，验证默认参数处理逻辑
+- 传入空字符串 `''`、空数组 `[]`、空对象 `{}`
+
+### 8.2 异常/边界值场景（Exception/Boundary）
+
+- 传入类型不匹配的参数，验证类型校验能力
+- 传入超限值，验证边界处理
+- 传入特殊值（`NaN`、`Infinity`），验证特殊数值处理
+
+### 8.3 大数据场景（Large Data）
+
+- 传入大数组（10000+ 元素），验证性能和正确性
+- 传入大字符串（10000+ 字符），验证长字符串处理能力
+- 验证大数据场景下不发生内存溢出、栈溢出或超时
+
+---
+
+## 9. 用例编号规则
+
+- 用例序号采用三位补零格式：`001`、`002`、`003`...
+- 序号按模块分组递增，便于管理