@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,185 @@
+# RN Jest 测试问题排查
+
+---
+
+## 一、常见问题
+
+### Q1: Mock 未生效 - 模块导入失败
+
+**错误信息**：
+```
+Cannot find module '@react-native-ohos/[库名]'
+```
+
+**原因**：
+- `jest.mock()` 中的模块名与实际导入不一致
+- `jest.config.js` 中缺少 `moduleNameMapper`
+
+**解决方案**：
+1. 确保 `jest.mock()` 中的模块名与 `import` 完全一致
+2. 在 `jest.config.js` 中配置 `moduleNameMapper`：
+   ```javascript
+   moduleNameMapper: {
+     '^@react-native-ohos/(.*)$': '<rootDir>/__mocks__/@react-native-ohos/$1',
+   }
+   ```
+3. 确保 `transformIgnorePatterns` 包含 `@react-native-ohos`
+
+---
+
+### Q2: 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);
+```
+
+---
+
+### Q3: 测试相互影响
+
+**错误信息**：
+- 测试单独运行通过，但批量运行失败
+- `Expected: 1, Received: 2`（调用次数不对）
+
+**原因**：
+- Mock 状态未在测试之间清理
+
+**解决方案**：
+```typescript
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+afterEach(() => {
+  AudioRecorder.onProgress = undefined;
+  AudioRecorder.onFinishRecording = undefined;
+});
+```
+
+---
+
+### Q4: 测试用例调用了不存在的 API
+
+**错误信息**：
+```
+TypeError: Cannot read property 'xxx' of undefined
+```
+
+**原因**：
+- 测试用例使用了 iOS/Android 分支的 API
+- HarmonyOS 端未实现该 API
+
+**解决方案**：
+1. 检查源码中 `Platform.OS === 'harmony'` 分支
+2. 确认 API 在 HarmonyOS 端已实现
+3. 移除对不支持 API 的测试
+
+---
+
+### Q5: 异步测试超时
+
+**错误信息**：
+```
+Timeout - Async callback was not invoked within the 5000 ms timeout
+```
+
+**原因**：
+- 异步 Mock 未正确设置返回值
+- Promise 未 resolve/reject
+
+**解决方案**：
+```typescript
+// 确保异步 Mock 返回 Promise
+(AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(true);
+
+// 或增加超时时间
+it('should handle slow operation', async () => {
+  // ...
+}, 10000);
+```
+
+---
+
+### Q6: jest.mock() 位置错误
+
+**错误信息**：
+```
+The module factory of `jest.mock()` is not allowed to reference any out-of-scope variables.
+```
+
+**原因**：
+- `jest.mock()` 的工厂函数中引用了外部变量
+
+**解决方案**：
+```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) },
+}));
+```
+
+---
+
+### Q7: 测试用例命名不符合规范
+
+**错误信息**：
+```
+@tc.name format error
+```
+
+**解决方案**：
+1. `@tc.name` 必须与 `it()` 第一个参数完全一致
+2. `@tc.number` 格式：`SUB_RNOH_[库名]_[API]_[类型]_[序号]`
+
+---
+
+## 二、调试技巧
+
+### 2.1 本地运行验证
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行指定文件
+npx jest __tests__/AudioRecorderTest.test.ts
+
+# 详细输出
+npx jest --verbose
+
+# 覆盖率报告
+npx jest --coverage
+```
+
+### 2.2 Mock 调试
+
+```typescript
+// 打印 Mock 调用记录
+console.log(AudioRecorder.prepareRecordingAtPath.mock.calls);
+
+// 打印最后一次调用参数
+console.log(AudioRecorder.prepareRecordingAtPath.mock.lastCall);
+```
+
+### 2.3 逐步排查
+
+1. 先确认 `jest.mock()` 正确配置
+2. 再确认 `import` 语句正确
+3. 最后确认断言方法正确

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

@@ -0,0 +1,265 @@
+# RN Jest 测试运行工作流
+
+---
+
+## 一、概述
+
+RN 三方库 XTS 测试基于 Jest 框架运行，通过 `jest.mock()` 模拟原生模块，在 Node.js 环境中执行 JavaScript/TypeScript 测试用例。
+
+---
+
+## 二、运行前准备
+
+### 2.1 确认 RN_TEST_PROJECT 路径
+
+从 `.oh-xts-config.json` 中读取 `RN_TEST_PROJECT` 路径。
+
+### 2.2 确认 Jest 依赖
+
+确保项目已安装 Jest：
+
+```bash
+# 检查 package.json 中是否有 jest 依赖
+cat {RN_TEST_PROJECT}/package.json | grep jest
+
+# 如果没有，安装 Jest
+cd {RN_TEST_PROJECT}
+npm install --save-dev jest @types/jest ts-jest typescript
+```
+
+### 2.3 最小化 package.json 配置
+
+如果输出目录是新建的独立目录（如文档驱动模式），需要创建 `package.json`：
+
+```json
+{
+  "name": "[库名]-xts",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+### 2.4 tsconfig.json 配置（TypeScript 项目需要）
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "types": ["jest"]
+  },
+  "include": ["__tests__/**/*.ts", "__mocks__/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### 2.5 确认测试文件位置
+
+```
+{输出目录}/
+├── __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
+```
+
+---
+
+## 三、jest.config.js 配置
+
+### 3.1 基础配置
+
+```javascript
+module.exports = {
+  preset: 'react-native',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest',
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(react-native|@react-native|@react-native-ohos)/)',
+  ],
+  moduleNameMapper: {
+    // 如果使用 __mocks__ 目录
+    '^@react-native-ohos/(.*)$': '<rootDir>/__mocks__/@react-native-ohos/$1',
+  },
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/**/index.ts',
+  ],
+};
+```
+
+### 3.2 jest.setup.js
+
+```javascript
+// jest.setup.js
+jest.mock('react-native', () => ({
+  Platform: { OS: 'harmony' },
+  NativeModules: {},
+  NativeEventEmitter: jest.fn().mockImplementation(() => ({
+    addListener: jest.fn(),
+    removeListeners: jest.fn(),
+  })),
+}));
+```
+
+### 3.3 package.json scripts
+
+```json
+{
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:audio": "jest --testPathPattern=Audio"
+  }
+}
+```
+
+---
+
+## 四、运行测试
+
+### 4.1 运行所有测试
+
+```bash
+cd {RN_TEST_PROJECT}
+npm test
+```
+
+### 4.2 运行指定测试文件
+
+```bash
+npx jest __tests__/AudioRecorderTest.test.ts
+```
+
+### 4.3 运行指定测试套件
+
+```bash
+npx jest --testNamePattern="AudioRecorderPrepareTest"
+```
+
+### 4.4 监听模式
+
+```bash
+npx jest --watch
+```
+
+### 4.5 生成覆盖率报告
+
+```bash
+npx jest --coverage
+```
+
+---
+
+## 五、测试输出说明
+
+### 5.1 通过
+
+```
+PASS  __tests__/AudioRecorderTest.test.ts
+  AudioRecorderPrepareTest
+    ✓ should prepare recording with valid path and options (2 ms)
+    ✓ should return false when path is empty (1 ms)
+  AudioRecorderAuthorizationTest
+    ✓ should resolve authorization to true (1 ms)
+```
+
+### 5.2 失败
+
+```
+FAIL  __tests__/AudioRecorderTest.test.ts
+  ● AudioRecorderPrepareTest › should prepare recording with valid path and options
+    expect(jest.fn()).toHaveBeenCalledWith(expected)
+    Expected: "/data/app/files/test.aac", {"AudioEncoding": "aac", "Channels": 1, "SampleRate": 22050}
+    Received: "/data/app/files/test.aac", {"AudioEncoding": "aac", "Channels": 2, "SampleRate": 22050}
+```
+
+---
+
+## 六、常见问题排查
+
+### 6.1 Mock 未生效
+
+**错误信息**：`TypeError: xxx.prepareRecordingAtPath is not a function`
+
+**解决方案**：
+1. 确保 `jest.mock()` 在 `import` 之前
+2. Jest 会自动提升 `jest.mock()` 调用，但如果使用变量则不会
+3. 检查 Mock 对象是否覆盖了所有导出
+
+### 6.2 TypeScript 类型错误
+
+**错误信息**：`Property 'mockReturnValue' does not exist on type 'xxx'`
+
+**解决方案**：
+```typescript
+// 使用 as jest.Mock 类型断言
+(AudioRecorder.prepareRecordingAtPath as jest.Mock).mockReturnValue(true);
+```
+
+### 6.3 测试相互影响
+
+**错误信息**：测试单独运行通过，但批量运行失败
+
+**解决方案**：
+1. 在 `beforeEach` 中调用 `jest.clearAllMocks()`
+2. 在 `afterEach` 中重置事件回调
+3. 不要在测试之间共享可变状态
+
+### 6.4 找不到模块
+
+**错误信息**：`Cannot find module '@react-native-ohos/react-native-audio'`
+
+**解决方案**：
+1. 检查 `jest.config.js` 中的 `moduleNameMapper`
+2. 检查 `transformIgnorePatterns` 是否包含该模块
+3. 确保 `jest.mock()` 中的模块名与实际导入一致
+
+### 6.5 异步测试超时
+
+**错误信息**：`Timeout - Async callback was not invoked within the 5000 ms timeout`
+
+**解决方案**：
+```typescript
+// 增加超时时间
+it('should handle slow async operation', async () => {
+  // ...
+}, 10000); // 10秒超时
+```

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

@@ -0,0 +1,189 @@
+# RN 三方库 XTS 测试通用配置
+
+> **适用范围**: 所有 @react-native-ohos/* 三方库
+> **版本**: 2.0.0
+> **更新日期**: 2026-03-31
+> **测试框架**: Jest
+
+---
+
+## 一、配置架构
+
+### 1.1 配置层级
+
+```
+通用配置 (_common.md)
+├─ 强制规范（不可覆盖）
+├─ 默认规范（可覆盖）
+└─ 扩展接口（三方库扩展）
+
+三方库配置 ({library-name}_CONFIG.md）
+├─ 基础信息（必须）
+├─ 三方库差异化配置（仅覆盖不同部分）
+└─ 特殊规则（仅三方库特有）
+```
+
+### 1.2 配置优先级
+
+```
+用户自定义配置 > 三方库配置 > 通用配置
+```
+
+---
+
+## 二、核心强制规范（不可覆盖）
+
+### 2.1 测试框架
+
+- **必须使用 Jest 框架**
+- 测试文件扩展名：`.test.ts` 或 `.test.tsx`
+- 使用 `jest.mock()` 模拟原生模块
+- 使用 `jest.clearAllMocks()` 在 `beforeEach` 中清理
+
+### 2.2 测试用例编号格式
+
+```
+格式: SUB_RNOH_[库名简写]_[API]_[类型]_[序号]
+
+类型标识：
+- PARAM    参数测试
+- ERROR    错误码测试
+- RETURN   返回值测试
+- BOUNDARY 边界值测试
+- EVENT    事件测试
+- PERM     权限测试
+
+示例：
+SUB_RNOH_AUDIO_PREPARE_PARAM_0001
+SUB_RNOH_AUDIO_PREPARE_ERROR_401_0001
+SUB_RNOH_AUDIO_PROGRESS_EVENT_0001
+SUB_RNOH_AUDIO_MIC_PERM_0001
+```
+
+### 2.3 命名强制规范
+
+#### it() 函数第一个参数（用例名称）
+- ✅ **必须使用 should...when... 格式**
+- 示例：`should prepare recording with valid path and options`
+
+#### @tc 注释块规范（强制）
+- `@tc.name`：必须与 `it()` 第一个参数完全一致
+- `@tc.number`：格式为 `SUB_RNOH_[库名]_[API]_[类型]_[序号]`，序号从 0001 开始
+- `@tc.desc`：格式为 `测试 [对象] 的 [方法] - [场景].`，必须以 `. ` 结尾
+- `@tc.type`：FUNCTION 或 EVENT
+- `@tc.size`：SMALLTEST / MEDIUMTEST / LARGETEST
+- `@tc.level`：LEVEL0 / LEVEL1 / LEVEL2 / LEVEL3 / LEVEL4
+
+### 2.4 平台兼容性（强制）
+
+- ✅ 只测试 `Platform.OS === 'harmony'` 分支中定义的 API
+- ❌ 禁止测试仅在 iOS/Android 分支中存在的 API
+- ✅ 路径常量使用 HarmonyOS 版本
+
+### 2.5 断言方法（强制）
+
+- ✅ 只能使用 Jest 断言方法：`toBe`, `toEqual`, `toBeTruthy`, `toBeFalsy`, `toBeDefined`, `toHaveBeenCalledWith`, `toHaveBeenCalledTimes`, `rejects.toThrow` 等
+- ❌ 不要使用 Hypium 断言方法（`assertEqual`, `assertTrue` 等）
+
+### 2.6 Mock 规范（强制）
+
+- 所有原生模块必须通过 `jest.mock()` 模拟
+- `jest.mock()` 必须在 `import` 之前
+- Mock 必须覆盖所有导出的方法和常量
+- 异步方法使用 `mockResolvedValue` / `mockRejectedValue`
+- 同步方法使用 `mockReturnValue`
+
+---
+
+## 三、默认规范（可覆盖）
+
+### 3.1 测试文件输出路径
+
+```
+{RN_TEST_PROJECT}/__tests__/
+├── [库名简写]Test.test.ts
+├── [库名简写]EventTest.test.ts
+├── [库名简写]PermTest.test.ts
+└── [库名简写]UtilsTest.test.ts
+```
+
+### 3.2 Mock 文件输出路径
+
+```
+{RN_TEST_PROJECT}/__mocks__/
+└── @react-native-ohos/
+    └── [库名]/
+        └── index.ts
+```
+
+### 3.3 测试设计文档命名
+
+```
+[库名].test.design.md
+```
+
+### 3.4 测试级别默认分配
+
+| API 类型 | 默认级别 |
+|---------|---------|
+| 核心流程 | LEVEL0 |
+| 正常参数 | LEVEL1 |
+| 返回值 | LEVEL1 |
+| 权限 | LEVEL1 |
+| 边界值 | LEVEL2 |
+| 事件 | LEVEL2 |
+| 错误码 | LEVEL3 |
+| 常量 | LEVEL3 |
+
+---
+
+## 四、三方库配置模板
+
+为特定三方库创建配置文件时，使用以下模板：
+
+```markdown
+# [库名] XTS 测试配置
+
+## 基础信息
+
+- 库名：@react-native-ohos/[库名]
+- 库名简写：[简写]
+- 版本：[版本号]
+- 源码路径：[oh_modules 路径]
+
+## API 分类
+
+### TurboModule 方法
+
+| 方法名 | 参数 | 返回值 | 类型 | Mock 策略 |
+|--------|------|--------|------|----------|
+| ... | ... | ... | 同步/异步 | mockReturnValue/mockResolvedValue |
+
+### 事件列表
+
+| 事件名 | 回调参数 | Mock 策略 |
+|--------|---------|----------|
+| ... | ... | jest.fn() |
+
+### 常量列表
+
+| 常量名 | 类型 | HarmonyOS 可用 |
+|--------|------|---------------|
+| ... | ... | ✅/❌ |
+
+## 特殊规则
+
+- [规则1]
+- [规则2]
+
+## 已知问题
+
+- [问题1]
+- [问题2]
+
+## 权限需求
+
+| 权限名 | 涉及 API |
+|--------|---------|
+| ... | ... |
+```