@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-ohos-xts-generator/references/TROUBLESHOOTING.md

@@ -0,0 +1,282 @@
+# RN 三方库 XTS 测试故障排除
+
+> **rn-ohos-xts-generator** - 常见问题解决方案
+
+## 目录
+
+- [Q1: 测试用例调用了不存在的 API](#q1-测试用例调用了不存在的-api)
+- [Q2: 事件回调测试超时](#q2-事件回调测试超时)
+- [Q3: 权限相关测试失败](#q3-权限相关测试失败)
+- [Q4: 路径相关测试失败](#q4-路径相关测试失败)
+- [Q5: TurboModule 方法未实现](#q5-turbomodule-方法未实现)
+- [Q6: 测试用例命名不符合规范](#q6-测试用例命名不符合规范)
+- [Q7: 断言方法错误](#q7-断言方法错误)
+- [Q8: Mock 未生效](#q8-mock-未生效)
+- [Q9: TypeScript 类型错误](#q9-typescript-类型错误)
+- [Q10: 测试相互影响](#q10-测试相互影响)
+- [获取帮助](#获取帮助)
+
+---
+
+## Q1: 测试用例调用了不存在的 API
+
+### 错误信息
+
+```
+TypeError: Cannot read property 'xxx' of undefined
+TypeError: xxx is not a function
+```
+
+### 原因
+
+使用了 iOS/Android 分支的 API，而非 HarmonyOS 分支的 API。
+
+### 解决方案
+
+1. 检查三方库入口文件中的 `Platform.OS === 'harmony'` 分支
+2. 确认 API 在 HarmonyOS 端是否定义
+3. 使用 HarmonyOS 版本的 API（如 `FilesDirectoryPath` 而非 `DocumentDirectoryPath`）
+
+### 预防
+
+使用 rn-ohos-xts-generator 时，确保 `.oh-xts-config.json` 中配置了 `RN_TEST_PROJECT` 路径，技能会自动探查 HarmonyOS 可用的 API。
+
+---
+
+## Q2: 事件回调测试超时
+
+### 错误信息
+
+```
+Timeout - Async callback was not invoked within the 5000ms timeout
+```
+
+### 原因
+
+HarmonyOS 端的 `emitDeviceEvent` 可能不稳定，事件未在预期时间内触发。
+
+### 解决方案
+
+1. 增加超时时间（如从 5000ms 增加到 10000ms）
+2. 确保事件触发条件已满足（如先调用相关方法）
+3. 考虑使用轮询作为兜底方案
+
+### 预防
+
+- 事件测试必须设置超时保护
+- 事件测试完成后必须清理监听器
+- 事件参数验证使用 `expect(value).not.toBeNull()` 而非具体值比较
+
+---
+
+## Q3: 权限相关测试失败
+
+### 错误信息
+
+```
+Error: Permission denied
+Error: please obtain microphone authorization first
+```
+
+### 原因
+
+未在操作前请求运行时权限。
+
+### 解决方案
+
+1. 在测试用例中先调用权限请求方法：
+   ```typescript
+   let authorized = await AudioRecorder.requestAuthorization();
+   expect(authorized).toBe(true);
+   ```
+2. 在 `module.json5` 中添加所需权限：
+   ```json
+   {
+     "requestPermissions": [
+       { "name": "ohos.permission.MICROPHONE" }
+     ]
+   }
+   ```
+
+### 预防
+
+rn-ohos-xts-generator 会自动为涉及权限的 API 生成权限测试用例。
+
+---
+
+## Q4: 路径相关测试失败
+
+### 错误信息
+
+```
+TypeError: Cannot read property 'DocumentDirectoryPath' of undefined
+```
+
+### 原因
+
+使用了 iOS/Android 的路径常量，HarmonyOS 不支持。
+
+### 解决方案
+
+| iOS/Android | HarmonyOS |
+|------------|-----------|
+| `DocumentDirectoryPath` | `FilesDirectoryPath` |
+| `MainBundlePath` | `BundlePath`（如有） |
+| `LibraryDirectoryPath` | 不支持 |
+| `ExternalDirectoryPath` | 不支持 |
+
+---
+
+## Q5: TurboModule 方法未实现
+
+### 错误信息
+
+```
+Error: not implemented
+```
+
+### 原因
+
+ArkTS 端的方法实现为 `throw new Error('not implemented')`。
+
+### 解决方案
+
+1. 探查 ArkTS 实现文件确认方法实现状态
+2. 跳过未实现方法的测试
+3. 在三方库配置中标记未实现的方法
+
+---
+
+## Q6: 测试用例命名不符合规范
+
+### 错误信息
+
+```
+@tc.name format error
+```
+
+### 规范
+
+- `@tc.name` 必须使用 `should...when...` 格式
+- `@tc.name` 必须与 `it()` 第一个参数完全一致
+- `@tc.number` 格式：`SUB_RNOH_[库名]_[API]_[类型]_[序号]`
+
+---
+
+## Q7: 断言方法错误
+
+### 错误信息
+
+```
+TypeError: expect(...).assertNotNull is not a function
+```
+
+### 原因
+
+使用了 Hypium 断言方法，本技能使用的是 Jest 测试框架。
+
+### 解决方案
+
+```typescript
+// ❌ 错误（Hypium 断言）
+expect(value).assertNotNull();
+expect(value).assertEqual('expected');
+
+// ✅ 正确（Jest 断言）
+expect(value).toBeDefined();
+expect(value).toBe('expected');
+```
+
+---
+
+## Q8: Mock 未生效
+
+### 错误信息
+
+```
+Cannot find module '@react-native-ohos/[库名]'
+TypeError: xxx.prepareRecordingAtPath is not a function
+```
+
+### 原因
+
+- `jest.mock()` 中的模块名与实际导入不一致
+- `jest.mock()` 位置错误
+
+### 解决方案
+
+1. 确保 `jest.mock()` 中的模块名与 `import` 完全一致
+2. Jest 会自动提升 `jest.mock()` 调用到文件顶部，但如果使用变量则不会
+3. 检查 `jest.config.js` 中的 `moduleNameMapper` 配置
+
+```typescript
+// ❌ 错误：引用外部变量
+const mockValue = true;
+jest.mock('@react-native-ohos/react-native-audio', () => ({
+  AudioRecorder: { prepareRecordingAtPath: jest.fn().mockReturnValue(mockValue) },
+}));
+
+// ✅ 正确：使用内联值
+jest.mock('@react-native-ohos/react-native-audio', () => ({
+  AudioRecorder: { prepareRecordingAtPath: jest.fn().mockReturnValue(true) },
+}));
+```
+
+---
+
+## Q9: TypeScript 类型错误
+
+### 错误信息
+
+```
+Property 'mockReturnValue' does not exist on type '(path: string, options: RecordingOptions) => boolean'
+```
+
+### 原因
+
+TypeScript 类型系统不知道 Mock 函数的类型。
+
+### 解决方案
+
+```typescript
+// 使用 as jest.Mock 类型断言
+(AudioRecorder.prepareRecordingAtPath as jest.Mock).mockReturnValue(true);
+(AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(true);
+```
+
+---
+
+## Q10: 测试相互影响
+
+### 错误信息
+
+- 测试单独运行通过，但批量运行失败
+- `Expected: 1, Received: 2`（调用次数不对）
+
+### 原因
+
+Mock 状态未在测试之间清理。
+
+### 解决方案
+
+```typescript
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+afterEach(() => {
+  AudioRecorder.onProgress = undefined;
+  AudioRecorder.onFinishRecording = undefined;
+});
+```
+
+---
+
+## 获取帮助
+
+如果以上方案无法解决问题，请提供以下信息：
+
+1. 三方库名称和版本
+2. 完整的错误信息
+3. 相关的测试用例代码
+4. HarmonyOS 实现文件内容

package/vendor/Server/Skills/rn-ohos-xts-generator/references/USAGE_GUIDE.md

@@ -0,0 +1,251 @@
+# 使用方式详解
+
+> **rn-ohos-xts-generator** - RN 鸿蒙化三方库 XTS 测试用例生成器
+
+## 快速导航
+
+- [使用方式对比](#使用方式对比)
+- [方式1：完整生成](#方式1完整生成推荐)
+- [方式2：文档驱动生成](#方式2文档驱动生成)
+- [方式3：覆盖率驱动](#方式3覆盖率驱动)
+- [方式4：单 API 测试](#方式4单-api-测试)
+- [常见使用场景](#常见使用场景)
+- [常见问题](#常见问题)
+
+---
+
+## 使用方式对比
+
+| 使用方式 | 适用场景 | 输入 | 输出 |
+|---------|---------|------|------|
+| **方式1：完整生成** | 新库首次生成 | 库名 | 完整测试套件 + 设计文档 |
+| **方式2：文档驱动生成** | 无源码环境 | 接口规格说明文档 | 完整测试套件 + 设计文档 |
+| **方式3：覆盖率驱动** | 补充缺失测试 | 覆盖率报告 | 补充测试用例 |
+| **方式4：单 API 测试** | 针对性测试 | 库名 + API 名 | 指定 API 的测试用例 |
+
+### 选择建议
+
+- **新库首次测试** → 方式1（完整生成）
+- **无源码环境** → 方式2（文档驱动生成）
+- **已有测试需补充** → 方式3（覆盖率驱动）
+- **修复特定问题** → 方式4（单 API 测试）
+
+---
+
+## 方式1：完整生成（推荐）
+
+### 适用场景
+
+- ✅ 新库首次生成 XTS 测试
+- ✅ 需要完整的测试覆盖
+- ✅ 需要测试设计文档
+
+### 使用格式
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/[库名] 生成 XTS 测试用例
+```
+
+### 使用示例
+
+**示例1：为 react-native-audio 生成测试**
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/react-native-audio 生成 XTS 测试用例
+```
+
+### 执行流程
+
+1. 源码探查（JS 入口、TurboModule Spec、ArkTS 实现）
+2. 平台兼容性分析
+3. 覆盖率分析（如有现有测试）
+4. 测试用例生成
+5. 测试设计文档生成
+6. 格式化和验证
+
+### 输出
+
+```
+{RN_TEST_PROJECT}/
+├── __tests__/
+│   ├── [库名简写]Test.test.ts
+│   ├── [库名简写]EventTest.test.ts
+│   ├── [库名简写]PermTest.test.ts
+│   └── [库名简写]UtilsTest.test.ts
+├── __mocks__/
+│   └── @react-native-ohos/
+│       └── [库名]/
+│           └── index.ts
+├── jest.config.js
+├── jest.setup.js
+├── package.json
+└── [库名].test.design.md
+```
+
+---
+
+## 方式2：文档驱动生成
+
+### 适用场景
+
+- ✅ 无源码环境（无 `oh_modules`/`node_modules`）
+- ✅ 有接口规格说明文档
+- ✅ 需要完整的测试覆盖
+
+### 使用格式
+
+```markdown
+请使用 rn-ohos-xts-generator 基于接口规格说明文档为 @react-native-ohos/[库名] 生成 XTS 测试用例
+
+接口规格说明文档路径：[文档路径或直接粘贴文档内容]
+```
+
+### 使用示例
+
+```markdown
+请使用 rn-ohos-xts-generator 基于接口规格说明文档为 @react-native-ohos/react-native-audio 生成 XTS 测试用例
+
+接口规格说明文档路径：/path/to/react-native-audio-api-spec.md
+```
+
+### 执行流程
+
+1. 文档解析（提取 API 列表、方法签名、事件定义）
+2. Mock 模块生成
+3. 测试用例生成
+4. 测试设计文档生成
+5. 格式化和验证
+
+### 输出
+
+```
+{用户指定目录}/[库名]-xts/
+├── __tests__/
+│   ├── [库名简写]Test.test.ts
+│   ├── [库名简写]EventTest.test.ts
+│   └── [库名简写]UtilsTest.test.ts
+├── __mocks__/
+│   └── @react-native-ohos/
+│       └── [库名]/
+│           └── index.ts
+├── jest.config.js
+├── jest.setup.js
+├── package.json
+└── [库名].test.design.md
+```
+
+---
+
+## 方式3：覆盖率驱动
+
+### 适用场景
+
+- ✅ 已有部分测试用例
+- ✅ 需要补充缺失的测试
+- ✅ 基于覆盖率报告定向生成
+
+### 使用格式
+
+```markdown
+请使用 rn-ohos-xts-generator 基于覆盖率报告为 @react-native-ohos/[库名] 补充测试用例
+
+覆盖率报告：
+[粘贴覆盖率报告或描述缺失的 API]
+```
+
+### 使用示例
+
+```markdown
+请使用 rn-ohos-xts-generator 基于覆盖率报告为 @react-native-ohos/react-native-audio 补充测试用例
+
+覆盖率报告：
+- pauseRecording: 无测试用例
+- resumeRecording: 无测试用例
+- onProgress 事件: 无测试用例
+- onFinishRecording 事件: 无测试用例
+```
+
+---
+
+## 方式4：单 API 测试
+
+### 适用场景
+
+- ✅ 为特定 API 生成测试
+- ✅ 修复特定问题后补充测试
+- ✅ 快速验证
+
+### 使用格式
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/[库名] 的 [API名] 生成测试用例
+```
+
+### 使用示例
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/react-native-audio 的 pauseRecording 生成测试用例
+```
+
+---
+
+## 常见使用场景
+
+### 场景1：新三方库首次 XTS 测试
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/react-native-webview 生成 XTS 测试用例
+```
+
+### 场景2：无源码环境，基于文档生成
+
+```markdown
+请使用 rn-ohos-xts-generator 基于接口规格说明文档为 @react-native-ohos/react-native-linear-gradient 生成 XTS 测试用例
+
+接口规格说明文档路径：/path/to/react-native-linear-gradient-api-spec.md
+```
+
+### 场景3：补充缺失测试
+
+```markdown
+请使用 rn-ohos-xts-generator 为 @react-native-ohos/react-native-audio 补充以下 API 的测试：
+- pauseRecording
+- resumeRecording
+- onProgress 事件
+```
+
+### 场景4：分析测试覆盖率
+
+```markdown
+请使用 rn-ohos-xts-generator 分析 @react-native-ohos/react-native-audio 的 XTS 测试覆盖率
+```
+
+---
+
+## 常见问题
+
+### Q1: 生成的测试用例调用了不存在的 API
+
+**原因**：使用了 iOS/Android 分支的 API
+
+**解决**：确保 `.oh-xts-config.json` 中配置了 `RN_TEST_PROJECT` 路径，技能会自动探查 HarmonyOS 可用的 API。
+
+### Q2: 事件测试超时
+
+**原因**：HarmonyOS 端 `emitDeviceEvent` 可能不稳定
+
+**解决**：在 Jest 测试中使用 `jest.fn()` 直接模拟事件回调，避免依赖原生事件触发。
+
+### Q3: 权限相关测试失败
+
+**原因**：未请求运行时权限
+
+**解决**：技能会自动为涉及权限的 API 生成权限请求测试，使用 `mockResolvedValue` 模拟权限结果。
+
+### Q4: 如何为新三方库添加配置
+
+在 `references/` 下创建以 `{library-name}_CONFIG.md` 命名的配置文件。参考 `COMMON_CONFIG.md` 中的模板。
+
+### Q5: 无源码环境如何生成测试
+
+使用文档驱动模式（方式2），提供接口规格说明文档即可生成测试用例，无需配置 `RN_TEST_PROJECT`。