@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,195 @@
+# RN 三方库测试用例生成策略
+
+---
+
+## 一、模块概述
+
+测试用例生成器根据 RN 三方库源码解析结果，按照 API 类型（TurboModule 方法、事件回调、NativeComponent、常量）自动生成符合 XTS 规范的测试用例。
+
+---
+
+## 二、TurboModule 方法测试生成
+
+### 2.1 同步方法测试规则
+
+| 参数类型 | 必须测试的场景 | 生成的测试用例数 |
+|---------|---------------|----------------|
+| **string** | 正常值、空字符串、特殊字符 | 3-4 个 |
+| **number** | 正数、负数、0、边界值 | 4-5 个 |
+| **boolean** | true、false | 2 个 |
+| **枚举** | 每个枚举值、无效值 | 枚举值+1 个 |
+| **对象** | 正常对象、空对象、缺少属性 | 3-4 个 |
+| **可选参数** | 传入、不传 | 2 个 |
+
+### 2.2 异步方法测试规则
+
+| 场景 | 测试内容 | 测试用例数 |
+|------|---------|-----------|
+| 正常返回 | Promise resolve | 1 个 |
+| 错误返回 | Promise reject | 1-2 个 |
+| 超时 | 长时间等待 | 1 个 |
+
+### 2.3 状态方法测试规则
+
+对于返回状态信息的方法（如 `isRecording()`）：
+
+| 场景 | 测试内容 |
+|------|---------|
+| 初始状态 | 调用前验证初始值 |
+| 状态转换 | 操作后验证状态变化 |
+| 多次转换 | 连续操作后验证最终状态 |
+
+---
+
+## 三、事件测试生成策略
+
+### 3.1 事件测试规则
+
+| 场景 | 测试内容 | 测试用例数 |
+|------|---------|-----------|
+| 事件触发 | 验证事件是否被触发 | 1 个 |
+| 事件参数 | 验证回调数据正确性 | 1-2 个 |
+| 事件时序 | 验证事件触发顺序 | 1 个 |
+| 事件清理 | 验证移除监听器后不再触发 | 1 个 |
+
+### 3.2 事件测试模板要点
+
+- ✅ 必须设置超时保护（5-10 秒）
+- ✅ 使用 `done: Function` 回调标记异步完成
+- ✅ `afterEach` 中清理监听器
+- ✅ 事件参数使用 `expect(value).not.toBeNull()` 而非具体值比较
+- ❌ 不要假设事件在固定时间内触发
+
+---
+
+## 四、NativeComponent 测试生成策略
+
+### 4.1 属性测试规则
+
+| 属性类型 | 测试场景 | 测试用例数 |
+|---------|---------|-----------|
+| string | 正常值、空字符串、特殊字符 | 3 个 |
+| number | 正数、0、负数、边界值 | 4 个 |
+| boolean | true、false | 2 个 |
+| enum | 每个枚举值 | 枚举值 个 |
+| callback | 正常函数、null | 2 个 |
+
+### 4.2 事件测试规则
+
+| 场景 | 测试内容 |
+|------|---------|
+| 事件触发 | 验证组件事件是否被触发 |
+| 事件参数 | 验证事件回调参数 |
+
+---
+
+## 五、常量/枚举测试生成策略
+
+### 5.1 路径常量测试
+
+```typescript
+it('should export non-empty FilesDirectoryPath', () => {
+  expect(AudioUtils.FilesDirectoryPath).toBeDefined();
+  expect(typeof AudioUtils.FilesDirectoryPath).toBe('string');
+  expect(AudioUtils.FilesDirectoryPath.length).toBeGreaterThan(0);
+});
+```
+
+### 5.2 枚举值测试
+
+```typescript
+it('should export correct AudioEncoder AAC value', () => {
+  expect(AudioEncoder.AAC).toBe('aac');
+});
+
+it('should export all AudioEncoder values', () => {
+  const encodings = Object.values(AudioEncoder);
+  expect(encodings.length).toBeGreaterThan(0);
+});
+```
+
+---
+
+## 六、权限测试生成策略
+
+### 6.1 权限请求测试
+
+```typescript
+it('should request microphone authorization successfully', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(true);
+  const result = await AudioRecorder.requestAuthorization();
+  expect(result).toBe(true);
+  expect(AudioRecorder.requestAuthorization).toHaveBeenCalledTimes(1);
+});
+```
+
+### 6.2 权限状态检查
+
+```typescript
+it('should check authorization status', async () => {
+  (AudioRecorder.checkAuthorizationStatus as jest.Mock).mockResolvedValue(true);
+  const status = await AudioRecorder.checkAuthorizationStatus();
+  expect(typeof status).toBe('boolean');
+});
+```
+
+### 6.3 无权限操作测试
+
+```typescript
+it('should throw error when starting recording without permission', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(false);
+  const authorized = await AudioRecorder.requestAuthorization();
+  expect(authorized).toBe(false);
+});
+```
+
+---
+
+## 七、测试用例数量估算
+
+### 7.1 估算公式
+
+```
+总测试用例数 = Σ(每个 API 的测试用例数)
+
+TurboModule 同步方法: 3-6 个/方法
+TurboModule 异步方法: 2-3 个/方法
+事件回调: 2-4 个/事件
+NativeComponent 属性: 2-3 个/属性
+常量: 1-2 个/常量
+权限: 1-2 个/权限
+```
+
+### 7.2 估算示例
+
+```
+react-native-audio:
+- prepareRecordingAtPath (同步, 2参数): 5 个
+- startRecording (同步, 0参数): 2 个
+- stopRecording (同步, 0参数): 2 个
+- pauseRecording (同步, 0参数): 2 个
+- resumeRecording (同步, 0参数): 2 个
+- isRecording (同步, 0参数): 3 个
+- requestAuthorization (异步): 2 个
+- onProgress (事件): 3 个
+- onFinishRecording (事件): 3 个
+- AudioUtils 常量 (3个): 3 个
+- 权限测试: 2 个
+总计: 约 29 个测试用例
+```
+
+---
+
+## 八、生成优先级
+
+### 8.1 优先级排序
+
+| 优先级 | 测试类型 | 理由 |
+|--------|---------|------|
+| P0 | 核心流程测试 | 验证库的基本功能 |
+| P1 | 正常参数测试 | 验证 API 的正确行为 |
+| P1 | 返回值测试 | 验证返回数据的正确性 |
+| P2 | 事件测试 | 验证事件回调机制 |
+| P2 | 边界值测试 | 验证边界条件处理 |
+| P3 | 错误码测试 | 验证错误处理机制 |
+| P3 | 常量验证 | 验证导出的常量值 |

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

@@ -0,0 +1,249 @@
+# HarmonyOS 实现探查器
+
+---
+
+## 一、模块概述
+
+HarmonyOS 实现探查器负责探查 `oh_modules` 下的 ArkTS 实现文件，确认三方库在 HarmonyOS 端的实际实现情况，包括已实现方法、未实现方法、事件名称等。
+
+---
+
+## 二、探查目标
+
+### 2.1 探查目录结构
+
+典型的 `@react-native-ohos/*` 库在 `oh_modules` 下的结构：
+
+```
+oh_modules/@react-native-ohos/[库名]/
+├── harmony/                          # HarmonyOS 特有目录
+│   ├── Index.ets                     # ArkTS 组件入口（如有 NativeComponent）
+│   ├── package.ts                    # ArkTS Package 注册
+│   └── src/main/
+│       ├── ets/
+│       │   ├── [ModuleName]Package.ts # TurboModule Package
+│       │   └── [ModuleName]TurboModule.ts  # TurboModule 实现
+│       ├── cpp/
+│       │   ├── CMakeLists.txt        # C++ 构建配置
+│       │   └── [ModuleName]Module.cpp # C++ 原生实现
+│       └── module.json5              # 模块配置
+├── src/
+│   ├── index.ts / index.js           # JS/TS 入口
+│   └── Native[ModuleName].ts         # TurboModule Spec
+├── index.ts / index.js               # 顶层入口
+└── package.json
+```
+
+### 2.2 必须探查的文件
+
+| 文件 | 探查目的 | 关键信息 |
+|------|---------|---------|
+| `index.ts` / `index.js` | JS 入口 | 导出的 API、Platform 分支 |
+| `src/Native*.ts` | TurboModule Spec | 方法签名、参数类型 |
+| `harmony/Index.ets` | ArkTS 组件 | NativeComponent 定义 |
+| `harmony/package.ts` | Package 注册 | Package 类名 |
+| `harmony/src/main/ets/*.ts` | ArkTS 实现 | 实际实现的方法 |
+| `harmony/src/main/cpp/*.cpp` | C++ 实现 | 底层实现细节 |
+| `harmony/src/main/cpp/CMakeLists.txt` | 构建配置 | 依赖库、源文件列表 |
+
+---
+
+## 三、方法实现确认
+
+### 3.1 探查方法
+
+在 ArkTS 实现文件中搜索每个方法的实现：
+
+```typescript
+// 已实现的方法
+startRecording(): void {
+  // 实际实现代码
+  this.nativeModule.startRecording();
+}
+
+// 未实现的方法（需要跳过测试）
+someMethod(): void {
+  throw new Error('not implemented');
+}
+```
+
+### 3.2 实现状态分类
+
+| 状态 | 标识 | 测试策略 |
+|------|------|---------|
+| 已完整实现 | 有实际代码，无 throw | 正常生成测试 |
+| 部分实现 | 有代码但有 TODO/FIXME | 生成测试但标记为 LEVEL3 |
+| 未实现 | `throw new Error('not implemented')` | 跳过，不生成测试 |
+| 空实现 | 方法体为空 | 生成测试但预期可能失败 |
+
+### 3.3 探查输出
+
+```
+=== HarmonyOS 实现状态 ===
+
+[已实现方法]
+✅ prepareRecordingAtPath - 完整实现
+✅ startRecording - 完整实现
+✅ stopRecording - 完整实现
+✅ pauseRecording - 完整实现
+✅ resumeRecording - 完整实现
+✅ isRecording - 完整实现
+✅ requestAuthorization - 完整实现
+
+[未实现方法]
+❌ checkAuthorizationStatus - throw new Error('not implemented')
+
+[事件实现]
+✅ emitDeviceEvent('recordingProgress', ...) - 已实现
+✅ emitDeviceEvent('recordingFinished', ...) - 已实现
+```
+
+---
+
+## 四、NativeComponent 探查
+
+### 4.1 探查 Index.ets
+
+```typescript
+// harmony/Index.ets
+export * from './src/main/ets/RNCWebView';
+
+// harmony/src/main/ets/RNCWebView.ets
+@ComponentV2
+export struct RNCWebView {
+  @Prop source: string = '';
+  @Prop javaScriptEnabled: boolean = true;
+  // ...
+}
+```
+
+### 4.2 组件信息提取
+
+| 提取项 | 说明 |
+|--------|------|
+| 组件名 | `RNCWebView` |
+| 导出方式 | `export struct` |
+| 属性列表 | source, javaScriptEnabled, ... |
+| 事件列表 | onLoad, onError, ... |
+| 类型常量 | `WebViewConstants` |
+
+### 4.3 组件探查输出
+
+```
+=== NativeComponent 信息 ===
+
+[组件名] RNCWebView
+[导出路径] harmony/src/main/ets/RNCWebView.ets
+[属性]
+  - source: string (默认: '')
+  - javaScriptEnabled: boolean (默认: true)
+  - injectedJavaScript: string (默认: '')
+[事件]
+  - onLoad: () => void
+  - onError: (error: ErrorEvent) => void
+  - onMessage: (event: MessageEvent) => void
+```
+
+---
+
+## 五、CMakeLists.txt 探查
+
+### 5.1 探查目的
+
+确认三方库的 C++ 依赖和源文件，用于测试工程的构建配置。
+
+### 5.2 探查内容
+
+```cmake
+# harmony/src/main/cpp/CMakeLists.txt
+target_sources(rn_audio PRIVATE
+  AudioRecorderModule.cpp
+  AudioRecorderTurboModule.cpp
+)
+
+target_link_libraries(rn_audio PUBLIC
+  rnoh
+  libace_ndk.z.so
+  libhilog_ndk.z.so
+)
+```
+
+### 5.3 探查输出
+
+```
+=== CMakeLists.txt 信息 ===
+
+[源文件] AudioRecorderModule.cpp, AudioRecorderTurboModule.cpp
+[依赖库] rnoh, libace_ndk.z.so, libhilog_ndk.z.so
+[子目录路径] src/main/cpp
+```
+
+---
+
+## 六、Package 注册探查
+
+### 6.1 探查 package.ts
+
+```typescript
+// harmony/package.ts
+import { TurboModule } from '@rnoh/react-native-openharmony/ts';
+import { TM } from './src/main/ets/AudioRecorderTurboModule';
+
+export class AudioPackage extends TurboModule {
+  createTurboModule(ctx: TurboModuleContext): AudioRecorderTurboModule {
+    return new AudioRecorderTurboModule(ctx);
+  }
+}
+```
+
+### 6.2 探查输出
+
+```
+=== Package 注册信息 ===
+
+[Package 类名] AudioPackage
+[TurboModule 类名] AudioRecorderTurboModule
+[Package 文件路径] harmony/package.ts
+```
+
+---
+
+## 七、探查流程
+
+### 7.1 完整探查步骤
+
+```
+步骤1：定位三方库目录
+  ├─ 读取 .oh-xts-config.json 中的 RN_TEST_PROJECT
+  ├─ 检查 oh_modules/@react-native-ohos/[库名]/
+  └─ 备选：检查 node_modules/@react-native-ohos/[库名]/
+
+步骤2：解析 JS/TS 入口
+  ├─ 读取 index.ts / index.js
+  ├─ 提取导出的 API
+  └─ 识别 Platform.OS === 'harmony' 分支
+
+步骤3：解析 TurboModule Spec
+  ├─ 读取 src/Native*.ts
+  ├─ 提取方法签名
+  └─ 提取类型定义
+
+步骤4：探查 HarmonyOS 实现
+  ├─ 读取 harmony/src/main/ets/*.ts
+  ├─ 确认方法实现状态
+  └─ 提取 emitDeviceEvent 事件名
+
+步骤5：探查 NativeComponent（如有）
+  ├─ 读取 harmony/Index.ets
+  └─ 提取组件属性和事件
+
+步骤6：探查构建配置
+  ├─ 读取 CMakeLists.txt
+  └─ 读取 package.ts
+
+步骤7：输出综合报告
+  ├─ API 清单
+  ├─ 实现状态
+  ├─ 事件列表
+  └─ 测试优先级建议
+```

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

@@ -0,0 +1,235 @@
+# Jest 测试框架基础
+
+---
+
+## 一、Jest 框架概述
+
+Jest 是 React Native 默认的 JavaScript 测试框架，由 Facebook 开发。RN 三方库的 XTS 测试基于 Jest 框架编写，通过 `jest.mock()` 模拟原生模块，实现单元测试和集成测试。
+
+**核心特性**：
+- 零配置开箱即用（配合 `preset: 'react-native'`）
+- 内置 Mock 功能（`jest.fn()`、`jest.mock()`、`jest.spyOn()`）
+- 快照测试
+- 异步测试支持（`async/await`）
+- 覆盖率报告（`--coverage`）
+
+---
+
+## 二、断言方法列表
+
+> **重要提示**：生成脚本时请从列表中选择，**不要编造方法名**
+
+### 2.1 相等性断言
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 1 | toBe | 严格相等（===） | `expect(value).toBe(1)` |
+| 2 | toEqual | 深度相等 | `expect(obj).toEqual({a: 1})` |
+| 3 | toStrictEqual | 严格深度相等（含类实例） | `expect(obj).toStrictEqual(instance)` |
+
+### 2.2 真值断言
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 4 | toBeTruthy | 真值 | `expect(value).toBeTruthy()` |
+| 5 | toBeFalsy | 假值 | `expect(value).toBeFalsy()` |
+| 6 | toBeNull | null | `expect(value).toBeNull()` |
+| 7 | toBeUndefined | undefined | `expect(value).toBeUndefined()` |
+| 8 | toBeDefined | 非 undefined | `expect(value).toBeDefined()` |
+| 9 | toBeNaN | NaN | `expect(value).toBeNaN()` |
+
+### 2.3 数值比较
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 10 | toBeGreaterThan | 大于 | `expect(n).toBeGreaterThan(0)` |
+| 11 | toBeGreaterThanOrEqual | 大于等于 | `expect(n).toBeGreaterThanOrEqual(1)` |
+| 12 | toBeLessThan | 小于 | `expect(n).toBeLessThan(10)` |
+| 13 | toBeLessThanOrEqual | 小于等于 | `expect(n).toBeLessThanOrEqual(5)` |
+| 14 | toBeCloseTo | 接近（浮点数） | `expect(0.1+0.2).toBeCloseTo(0.3)` |
+
+### 2.4 字符串/数组/对象
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 15 | toContain | 包含（数组/字符串） | `expect(arr).toContain(item)` |
+| 16 | toHaveLength | 长度 | `expect(arr).toHaveLength(3)` |
+| 17 | toMatch | 正则匹配 | `expect(str).toMatch(/pattern/)` |
+| 18 | toMatchObject | 部分匹配对象 | `expect(obj).toMatchObject({a: 1})` |
+| 19 | toHaveProperty | 包含属性 | `expect(obj).toHaveProperty('a')` |
+
+### 2.5 函数调用验证
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 20 | toHaveBeenCalled | 被调用过 | `expect(fn).toHaveBeenCalled()` |
+| 21 | toHaveBeenCalledTimes | 调用次数 | `expect(fn).toHaveBeenCalledTimes(2)` |
+| 22 | toHaveBeenCalledWith | 以指定参数调用 | `expect(fn).toHaveBeenCalledWith(arg)` |
+| 23 | toHaveBeenLastCalledWith | 最后一次调用参数 | `expect(fn).toHaveBeenLastCalledWith(arg)` |
+
+### 2.6 异常断言
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 24 | toThrow | 抛出异常 | `expect(fn).toThrow()` |
+| 25 | toThrowError | 抛出指定错误 | `expect(fn).toThrowError('msg')` |
+| 26 | rejects.toThrow | 异步抛出异常 | `await expect(promise).rejects.toThrow()` |
+| 27 | resolves.toBe | 异步解析为 | `await expect(promise).resolves.toBe(value)` |
+
+### 2.7 取反
+
+| No. | API | 功能说明 | 示例 |
+|:---|:---|:---|:---|
+| 28 | not | 断言取反 | `expect(value).not.toBe(null)` |
+
+---
+
+## 三、Mock 机制
+
+### 3.1 jest.mock() - 模块模拟
+
+```typescript
+// 自动模拟整个模块
+jest.mock('@react-native-ohos/react-native-audio');
+
+// 自定义模拟实现
+jest.mock('@react-native-ohos/react-native-audio', () => ({
+  AudioRecorder: {
+    prepareRecordingAtPath: jest.fn().mockReturnValue(true),
+    startRecording: jest.fn(),
+    stopRecording: jest.fn(),
+  },
+  AudioUtils: {
+    FilesDirectoryPath: '/data/app/files',
+  },
+}));
+```
+
+### 3.2 jest.fn() - Mock 函数
+
+```typescript
+// 创建 Mock 函数
+const mockFn = jest.fn();
+
+// 带默认返回值
+const mockFn = jest.fn().mockReturnValue(true);
+
+// 带默认 Promise 返回值
+const mockFn = jest.fn().mockResolvedValue({ status: 'OK' });
+
+// 带默认 Promise 拒绝值
+const mockFn = jest.fn().mockRejectedValue(new Error('failed'));
+
+// 带自定义实现
+const mockFn = jest.fn().mockImplementation((path, options) => {
+  return path.endsWith('.aac');
+});
+```
+
+### 3.3 Mock 状态管理
+
+```typescript
+beforeEach(() => {
+  jest.clearAllMocks();  // 清除所有 Mock 调用记录和实现
+});
+
+afterEach(() => {
+  jest.restoreAllMocks();  // 恢复所有 Mock
+});
+```
+
+### 3.4 Mock 属性赋值
+
+```typescript
+// Mock 回调属性
+AudioRecorder.onProgress = jest.fn();
+AudioRecorder.onFinished = jest.fn();
+
+// 模拟触发回调
+AudioRecorder.onProgress({ currentTime: 1.5 });
+expect(AudioRecorder.onProgress).toHaveBeenCalledWith({ currentTime: 1.5 });
+```
+
+---
+
+## 四、导入语句规范
+
+### 4.1 标准导入（RN 三方库测试）
+
+```typescript
+// jest.mock() 必须在 import 之前
+jest.mock('@react-native-ohos/react-native-audio', () => ({
+  AudioRecorder: { ... },
+  AudioUtils: { ... },
+}));
+
+import { AudioRecorder, AudioUtils } from '@react-native-ohos/react-native-audio';
+```
+
+### 4.2 导入合并
+
+同一包名的导入必须合并：
+
+```typescript
+// ✅ 正确
+import { AudioRecorder, AudioUtils } from '@react-native-ohos/react-native-audio';
+
+// ❌ 错误
+import { AudioRecorder } from '@react-native-ohos/react-native-audio';
+import { AudioUtils } from '@react-native-ohos/react-native-audio';
+```
+
+---
+
+## 五、RN 三方库测试常用断言模式
+
+### 5.1 TurboModule 方法调用验证
+
+```typescript
+it('should call prepareRecordingAtPath with correct args', () => {
+  AudioRecorder.prepareRecordingAtPath('/path/test.aac', { SampleRate: 22050 });
+  expect(AudioRecorder.prepareRecordingAtPath).toHaveBeenCalledWith('/path/test.aac', { SampleRate: 22050 });
+  expect(AudioRecorder.prepareRecordingAtPath).toHaveBeenCalledTimes(1);
+});
+```
+
+### 5.2 异步方法返回值验证
+
+```typescript
+it('should resolve authorization to true', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockResolvedValue(true);
+  const result = await AudioRecorder.requestAuthorization();
+  expect(result).toBe(true);
+});
+```
+
+### 5.3 异步方法错误验证
+
+```typescript
+it('should reject when authorization denied', async () => {
+  (AudioRecorder.requestAuthorization as jest.Mock).mockRejectedValue(new Error('denied'));
+  await expect(AudioRecorder.requestAuthorization()).rejects.toThrow('denied');
+});
+```
+
+### 5.4 事件回调验证
+
+```typescript
+it('should invoke onProgress callback with correct data', () => {
+  const mockProgress = jest.fn();
+  AudioRecorder.onProgress = mockProgress;
+  mockProgress({ currentTime: 1.5 });
+  expect(mockProgress).toHaveBeenCalledWith({ currentTime: 1.5 });
+  expect(mockProgress).toHaveBeenCalledTimes(1);
+});
+```
+
+### 5.5 常量值验证
+
+```typescript
+it('should export FilesDirectoryPath', () => {
+  expect(AudioUtils.FilesDirectoryPath).toBeDefined();
+  expect(typeof AudioUtils.FilesDirectoryPath).toBe('string');
+  expect(AudioUtils.FilesDirectoryPath.length).toBeGreaterThan(0);
+});
+```