@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rnoh-lib-test-align/references/jest-troubleshooting.md

@@ -0,0 +1,371 @@
+# Jest 单元测试排错指南
+
+RN 0.84 + React 19 环境下，为鸿蒙化组件编写 jest 单元测试时遇到的常见问题及解决方案。
+
+本文档基于 rntpc_picker 库的实战调试经验整理。
+
+## 问题 1：React 多副本导致 hooks 失效
+
+### 症状 1
+
+```text
+TypeError: Cannot read properties of null (reading 'useRef')
+```
+
+组件中调用 `React.useRef()`、`React.useMemo()` 等 hooks 时崩溃。
+
+### 根因 1
+
+鸿蒙化工程的典型目录结构：
+
+```
+rntpc_picker/               ← 库根目录
+├── node_modules/react/      ← React 副本 A
+├── js/
+│   └── PickerHarmony.harmony.js   ← 从此处解析 react → 副本 A
+└── example/                 ← 测试工程目录
+    ├── node_modules/react/  ← React 副本 B
+    └── node_modules/react-test-renderer/  ← 使用副本 B
+```
+
+`PickerHarmony.harmony.js` 位于 `js/` 目录，其 `import * as React from 'react'` 解析到 `rntpc_picker/node_modules/react`（副本 A）。
+而 `react-test-renderer`（安装在 `example/node_modules/`）使用 `example/node_modules/react`（副本 B）。
+
+两个不同的 React 实例导致 hooks dispatcher 不匹配——renderer 设置的 dispatcher 在副本 B 上，但组件调用的 hooks 在副本 A 上。
+
+### 诊断方法
+
+```bash
+# 检查 React 解析路径
+node -e "
+console.log('from example:', require.resolve('react', {paths: ['./example']}));
+console.log('from js dir:', require.resolve('react', {paths: ['./js']}));
+"
+```
+
+如果两个路径不同，即为多副本问题。
+
+### 解决方案 1
+
+在 `jest.config.js` 的 `moduleNameMapper` 中强制统一 React：
+
+```javascript
+moduleNameMapper: {
+  '^react-native$': '<rootDir>/__mocks__/react-native.js',
+  // 强制统一 React 副本
+  '^react$': '<rootDir>/node_modules/react/index.js',
+  '^react/jsx-runtime$': '<rootDir>/node_modules/react/jsx-runtime.js',
+},
+```
+
+**关键**：`<rootDir>` 是 jest 配置文件所在目录（通常是 `example/`），映射到 `example/node_modules/react`。
+
+## 问题 2：React 19 react-test-renderer 异步渲染
+
+### 症状 2
+
+Mock 组件的 `forwardRef` 回调未执行，`globalThis.__CAPTURED_PROPS__` 为 null。
+
+### 根因 2
+
+React 19 中 `react-test-renderer` 已弃用，默认异步渲染。`TestRenderer.create()` 返回时，组件的 render 函数（含 forwardRef）可能尚未执行。
+
+### 解决方案 2
+
+1. 在 `jest.setup.js` 中启用 act 环境：
+
+```javascript
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+```
+
+2. 用 `act()` 包裹 `TestRenderer.create()`：
+
+```typescript
+import TestRenderer, {act} from 'react-test-renderer';
+
+function renderComponent(element: React.ReactElement) {
+  let renderer;
+  act(() => {
+    renderer = TestRenderer.create(element);
+  });
+  return renderer;
+}
+```
+
+3. 触发事件回调时也用 `act()` 包裹：
+
+```typescript
+act(() => {
+  capturedOnChange()(mockEvent);
+});
+```
+
+## 问题 3：react-native 原生模块初始化崩溃
+
+### 症状 3
+
+```text
+Error: __fbBatchedBridgeConfig is not available
+```
+
+或类似的 native bridge 初始化错误。
+
+### 根因 3
+
+`react-native` 模块在 Node 环境中加载时尝试初始化原生桥接层，但测试环境中没有原生运行时。
+
+### 解决方案 3
+
+创建 `__mocks__/react-native.js` mock 文件，提供最小化的组件和工具函数：
+
+```javascript
+const React = require('react');
+
+const View = (props) => React.createElement('View', props, props.children);
+const Text = (props) => React.createElement('Text', props, props.children);
+const StyleSheet = { create: (styles) => styles, flatten: (style) => style };
+const Platform = { OS: 'harmony', select: (obj) => obj.harmony || obj.default };
+const processColor = (color) => color;  // 直接透传，测试中不需要真实颜色转换
+
+module.exports = {
+  View, Text, StyleSheet, Platform, processColor,
+  // 按需添加其他导出
+};
+```
+
+在 `jest.config.js` 中映射：
+
+```javascript
+moduleNameMapper: {
+  '^react-native$': '<rootDir>/__mocks__/react-native.js',
+},
+```
+
+## 问题 4：Fabric 原生组件导入链崩溃
+
+### 症状 4
+
+```text
+Error: Cannot find module 'react-native/Libraries/Utilities/codegenNativeComponent'
+```
+
+### 根因 4
+
+`*NativeComponent.js` 文件深度导入 react-native 内部模块（codegenNativeComponent 等），mock 的 react-native 不包含这些内部路径。
+
+### 解决方案 4
+
+为每个 Fabric 原生组件创建独立 mock：
+
+`__mocks__/RNCPickerNativeComponent.js`：
+
+```javascript
+const React = require('react');
+
+const Commands = {
+  setNativeSelectedIndex: jest.fn(),
+};
+
+// 使用 forwardRef 捕获 props，通过 globalThis 传递给测试
+const MockNativePicker = React.forwardRef((props, ref) => {
+  globalThis.__PICKER_CAPTURED_PROPS__ = props;
+  globalThis.__PICKER_CAPTURED_ONCHANGE__ = props.onChange;
+  React.useImperativeHandle(ref, () => ({
+    setNativeProps: jest.fn(),
+  }));
+  return React.createElement('RNCPicker', props);
+});
+
+module.exports = {
+  __esModule: true,
+  default: MockNativePicker,
+  Commands,
+};
+```
+
+在测试文件中声明 mock：
+
+```typescript
+jest.mock('../../../js/RNCPickerNativeComponent', () => {
+  return require('../../__mocks__/RNCPickerNativeComponent');
+});
+```
+
+**注意**：`jest.mock()` 会被自动提升到文件顶部（hoisting），因此必须在 `import` 组件之前声明。使用 `require()` 方式引用 mock 文件可以避免变量提升问题。
+
+## 问题 5：globalThis 变量传递 vs 模块实例不一致
+
+### 症状 5
+
+Mock 文件中设置的变量，在测试文件中读取时为 null 或 undefined。
+
+### 根因 5
+
+jest 模块缓存可能导致 mock 文件被 require 多次，产生不同的模块实例，变量不共享。
+
+### 解决方案 5
+
+使用 `globalThis` 而非模块级变量传递数据：
+
+```javascript
+// mock 文件中
+globalThis.__PICKER_CAPTURED_PROPS__ = props;
+
+// 测试文件中
+const lastProps = () => globalThis.__PICKER_CAPTURED_PROPS__;
+```
+
+在 `beforeEach` 中重置：
+
+```typescript
+beforeEach(() => {
+  globalThis.__PICKER_CAPTURED_PROPS__ = null;
+  globalThis.__PICKER_CAPTURED_ONCHANGE__ = null;
+});
+```
+
+## 问题 6：@react-native/typescript-config 阻塞 ts-jest
+
+### 症状 6
+
+```text
+error TS2614: Module '"@react-native/typescript-config"' can only be default-imported using the 'esModuleInterop' flag
+```
+
+### 根因 6
+
+RN 0.84 的 `tsconfig.json` 继承 `@react-native/typescript-config`，其 `exports` 字段导致 ts-jest 解析失败。
+
+### 解决方案 6
+
+创建独立的 `tsconfig.jest.json`，不继承 RN 的配置：
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "module": "commonjs",
+    "target": "es2017",
+    "moduleResolution": "node",
+    "types": ["react", "react-native", "jest", "node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["harmony", "node_modules"]
+}
+```
+
+在 `jest.config.js` 中指定：
+
+```javascript
+transform: {
+  '^.+\\.(ts|tsx)$': ['ts-jest', {
+    tsconfig: 'tsconfig.jest.json',
+    isolatedModules: true,
+  }],
+},
+```
+
+## 问题 7：jest 扫描 harmony/oh_modules 目录
+
+### 症状 7
+
+jest 启动时扫描 `harmony/oh_modules/` 下的大量文件，导致超时或内存溢出。
+
+### 解决方案 7
+
+在 `jest.config.js` 中用 `testMatch` 精确限定测试文件：
+
+```javascript
+testMatch: ['<rootDir>/src/__tests__/*.test.tsx'],
+```
+
+同时确保 `tsconfig.jest.json` 的 `exclude` 包含 `harmony` 目录。
+
+## 问题 8：NativeEventEmitter.addListener 返回值缺少 remove 方法
+
+### 症状 8
+
+```text
+TypeError: this._nativeEventSubscription.remove is not a function
+```
+
+在 TurboModule 库（如 NetInfo）的测试中，`State.tearDown()` 调用 `this._nativeEventSubscription.remove()` 时崩溃。
+
+### 根因 8
+
+`__mocks__/react-native.js` 中的 `NativeEventEmitter` 继承 Node.js 的 `EventEmitter`，其 `addListener` 方法返回 EventEmitter 实例（boolean 值或 listener 引用），而非 RN 的 `NativeEventSubscription` 对象（`{ remove: () => void }`）。
+
+### 解决方案 8
+
+在 mock 中覆写 `addListener`，使其返回包含 `remove` 方法的对象：
+
+```javascript
+// __mocks__/react-native.js
+const { EventEmitter } = require('events');
+
+class MockNativeEventEmitter extends EventEmitter {
+  addListener(eventName, handler) {
+    const listener = super.addListener(eventName, handler);
+    // 返回 NativeEventSubscription 兼容对象
+    return {
+      remove: () => super.removeListener(eventName, handler),
+    };
+  }
+}
+
+module.exports = {
+  // ... 其他导出
+  NativeEventEmitter: MockNativeEventEmitter,
+  NativeModules: {
+    // 按需提供 mock 的原生模块
+  },
+};
+```
+
+**关键**：所有 TurboModule 库（非 Fabric 组件库）的测试都需要此 mock。TurboModule 库不需要 mock `codegenNativeComponent`，但必须正确 mock `NativeEventEmitter`。
+
+## 完整配置模板
+
+### jest.config.js
+
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['<rootDir>/src/__tests__/*.test.tsx'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  transform: {
+    '^.+\\.(ts|tsx)$': ['ts-jest', {
+      tsconfig: 'tsconfig.jest.json',
+      isolatedModules: true,
+    }],
+    '^.+\\.(js|jsx)$': 'babel-jest',
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(react-native|@react-native|@react-native-picker|@react-native-oh)/)',
+  ],
+  setupFiles: ['<rootDir>/jest.setup.js'],
+  moduleNameMapper: {
+    '^react-native$': '<rootDir>/__mocks__/react-native.js',
+    '^react$': '<rootDir>/node_modules/react/index.js',
+    '^react/jsx-runtime$': '<rootDir>/node_modules/react/jsx-runtime.js',
+  },
+};
+```
+
+### jest.setup.js
+
+```javascript
+global.__DEV__ = true;
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+```
+
+### `__mocks__/react-native.js`
+
+提供 `View`、`Text`、`StyleSheet`、`Platform`（OS='harmony'）、`processColor`（透传）等最小导出。
+
+### `__mocks__/FabricComponent.js`
+
+用 `React.forwardRef` 捕获 props，通过 `globalThis` 传递。导出 `{ __esModule: true, default: MockComponent, Commands: {...} }`。

package/vendor/Server/Skills/rnoh-lib-test-align/references/port-test-demo-guide.md

@@ -0,0 +1,212 @@
+# port-test-demo.sh 使用指南
+
+## 脚本概述
+
+从 RN 三方库 git 仓库中提取测试 demo / 用例代码，移植到 RNOH 模板工程的 `src/index.tsx` 中。
+
+脚本位于本 skill 的 `scripts/` 目录下，可直接运行。
+
+## 参数说明
+
+### 必选参数
+
+| 参数 | 说明 |
+|------|------|
+| `--git-url <url>` | git 仓库 URL |
+| `--branch <branch>` | git 分支名或版本标签 |
+
+### 可选参数
+
+| 参数 | 说明 |
+|------|------|
+| `--template-dir <path>` | 模板工程目录，不指定则自动检测 |
+| `--demo-dirs <dir1,dir2,...>` | 手动指定 demo 目录名（逗号分隔，跳过自动检测） |
+| `--legacy-peer-deps` | npm install 时使用 `--legacy-peer-deps` |
+| `--force` | npm install 时使用 `--force` |
+| `--skip-npm-install` | 跳过依赖安装步骤 |
+| `--skip-index-merge` | 跳过 index.tsx 合并步骤（只拷贝文件不修改入口） |
+| `--verbose` | 显示详细调试信息 |
+| `--dry-run` | 只检测不实际拷贝 |
+
+## 工作流程
+
+### 1. git clone 仓库
+
+浅克隆（`--depth=1`）到当前目录下的 `TestGet/` 目录中。
+
+### 2. 自动检测 demo 目录
+
+按以下顺序检测：
+
+- 已知目录名：`example`、`demo`、`Example`、`Demo`、`test`、`tests`、`Test`、`Tests`、`spec`、`specs`、`__tests__`、`e2e`、`cypress`
+- monorepo 结构：`packages/*/example`、`packages/*/demo`
+
+### 3. 依赖安装
+
+解析 demo 的 package.json：
+- 将三方库依赖安装到模板工程
+- `workspace:` 协议依赖自动转换为 `file:` 本地依赖
+- 支持通过 `--legacy-peer-deps` 或 `--force` 处理 peer 冲突
+
+### 4. 支撑文件拷贝
+
+将 demo 的 assets、animations 等资源文件拷贝到模板工程 `src/` 顶层，保持原有相对路径。
+
+使用 `rsync` 进行文件拷贝，自动跳过 `node_modules`、`.git` 等目录。
+
+### 5. 入口代码合并
+
+将 demo 的入口文件（`App.tsx` / `index.tsx` 等）内容直接写入 `src/index.tsx`，过滤 `AppRegistry` 注册代码。
+
+## 自动检测模板工程目录
+
+脚本按以下顺序查找模板工程：
+
+1. `--template-dir` 指定的路径
+2. 当前工作目录（如果包含 `package.json` 和 `src/index.tsx`）
+3. `RN3rdTemplate/0.77/` 或 `RN3rdTemplate/0.82/`（相对于脚本位置）
+4. 向上查找（最多 5 层）
+
+## 使用示例
+
+### 基本用法
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/lottie-react-native/lottie-react-native \
+  --branch v7.4.0
+```
+
+### 指定模板目录
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/lottie-react-native/lottie-react-native \
+  --branch v7.4.0 \
+  --template-dir /Users/lalhan/Desktop/RNOH/RN3rdTemplate/0.84
+```
+
+### 手动指定 demo 目录
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/xxx/mono-repo \
+  --branch main \
+  --demo-dirs packages/core/example
+```
+
+### dry-run 模式
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/lottie-react-native/lottie-react-native \
+  --branch v7.4.0 \
+  --dry-run
+```
+
+### 跳过 npm install
+
+```bash
+./scripts/port-test-demo.sh \
+  --git-url https://github.com/lottie-react-native/lottie-react-native \
+  --branch v7.4.0 \
+  --skip-npm-install
+```
+
+## 文件拷贝策略
+
+### 拷贝的文件
+
+- demo 目录下的所有 `.ts`、`.tsx`、`.js`、`.jsx` 文件
+- assets 资源文件（图片、动画 JSON、字体等）
+- 配置文件（如需要）
+
+### 排除的文件
+
+- `node_modules/`
+- `.git/`
+- `.DS_Store`
+- `*.log`
+
+### 目录结构映射
+
+```
+上游仓库:
+example/
+├── App.tsx              ← 入口文件
+├── src/
+│   ├── components/
+│   │   └── Example.tsx
+│   └── assets/
+│       └── animation.json
+└── package.json
+
+模板工程 (移植后):
+src/
+├── index.tsx            ← App.tsx 内容写入此处
+├── components/
+│   └── Example.tsx      ← 保持原目录结构
+└── assets/
+    └── animation.json   ← 资源文件保持相对路径
+```
+
+## 入口文件合并策略
+
+### 合并规则
+
+1. 读取 demo 入口文件内容
+2. 过滤掉 `AppRegistry.registerComponent` 调用
+3. 过滤掉 `import` 中的 `react-native` 的 `AppRegistry`
+4. 将剩余内容直接写入 `src/index.tsx`
+5. 保留模板工程原有的 `AppRegistry.registerComponent` 调用
+
+### 多入口文件处理
+
+如果 demo 有多个入口文件（如 `App.tsx` + `examples/` 目录）：
+- 主入口文件内容写入 `src/index.tsx`
+- 其他文件保持原目录结构拷贝到 `src/` 下
+
+## 依赖安装策略
+
+### workspace 协议转换
+
+```json
+// 上游 demo package.json
+"dependencies": {
+  "lottie-react-native": "workspace:*"
+}
+
+// 转换后 (安装到模板工程)
+"dependencies": {
+  "lottie-react-native": "file:../update_harmony_lib/target-repo"
+}
+```
+
+### file 协议依赖
+
+如果 demo 依赖了本地路径的其他包：
+- 自动检测 `file:` 协议依赖
+- 尝试在克隆的仓库中找到对应路径
+- 转换为相对于模板工程的路径
+
+## 常见问题
+
+### Q: 脚本提示"未找到 demo 目录"
+
+**A**: 使用 `--demo-dirs` 手动指定目录名。先用 `--dry-run` 查看仓库结构。
+
+### Q: 依赖安装失败
+
+**A**: 尝试 `--legacy-peer-deps` 或 `--force`。如果仍失败，使用 `--skip-npm-install` 跳过，手动安装。
+
+### Q: 资源文件路径不对
+
+**A**: 检查 `rsync` 拷贝的目录结构是否与测试代码中的引用路径一致。可能需要手动调整路径或创建符号链接。
+
+### Q: index.tsx 合并后编译错误
+
+**A**: 使用 `--skip-index-merge` 跳过自动合并，手动将 demo 入口文件内容复制到 `src/index.tsx` 中。
+
+### Q: 子目录中的 index.tsx 聚合入口被跳过
+
+**A**: `port-test-demo.sh` 在拷贝支撑文件时，会将所有名为 `index.tsx` 的文件加入 `SKIP_FILES` 列表（因为主入口文件也叫 `index.tsx`）。这导致上游 `testCases/index.tsx` 等子目录中的聚合入口文件被跳过未拷贝。移植完成后需手动检查是否存在被跳过的聚合入口，并手动创建或拷贝。