@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,345 @@
+# 设备运行时崩溃排错指南
+
+RN 0.84 + React 19 + RNOH 0.84 环境下，测试 demo 移植到鸿蒙设备后遇到的运行时崩溃及解决方案。
+
+本文档基于 rntpc_react-native-netinfo 库的实战调试经验整理。
+
+## 崩溃 1：Element type is invalid: got: object
+
+### 症状
+
+应用启动即崩溃，错误信息：`Element type is invalid: got: object`。
+
+### 根因
+
+`example/src/index.tsx` 中定义了 `ExampleApp` 组件类，并在文件末尾调用 `AppRegistry.registerComponent('app_name', () => ExampleApp)`，但**缺少 `export default` 导出**。
+
+`example/index.js` 中 `import App from './src/index'` 要求 `src/index.tsx` 有默认导出。缺少默认导出时，`App` 为 `undefined`，React 注册了一个 `undefined` 组件，运行时报 "Element type is invalid"。
+
+### 诊断方法
+
+```bash
+# 检查 index.tsx 是否有 export default
+grep "export default" example/src/index.tsx
+```
+
+如果没有输出，即为问题所在。
+
+### 解决方案
+
+在 `AppRegistry.registerComponent` **之前**添加默认导出：
+
+```typescript
+// example/src/index.tsx 末尾
+
+export default ExampleApp;
+
+AppRegistry.registerComponent('app_name', () => ExampleApp);
+```
+
+**注意**：`app_name` 必须与 `app.json` 中的 `"name"` 字段一致，且与 `Index.ets` 中 `RNApp` 的 `appKey` 一致。
+
+## 崩溃 2：Cannot read property 'useState' of null
+
+### 症状
+
+应用启动后白屏或崩溃，错误信息：`Cannot read property 'useState' of null`。调用栈指向调用了 `useState()` 的组件（如 NetInfoHook 中的 `useNetInfo()`）。
+
+### 根因
+
+Metro bundler 为 `react` 创建了**两个模块实例**：
+
+```
+模块 ID 49:  node_modules/react/index.js         ← example 代码使用
+模块 ID 640: ../node_modules/react/index.js       ← 库代码使用
+```
+
+两个 React 实例导致 `ReactSharedInternals.H`（hooks dispatcher）不一致：
+- 渲染器在实例 A 上设置 dispatcher
+- 组件在实例 B 上调用 `useState()`
+- 实例 B 的 `H` 为 null → 崩溃
+
+#### 为什么会有两个 react
+
+库通过 `"file:.."` 安装（symlink 到父目录），目录结构：
+
+```
+rntpc_react-native-netinfo/         ← 库根目录
+├── node_modules/react/             ← React 副本 A
+├── src/index.ts                    ← import {useState} from 'react' → 解析到副本 A
+└── example/                        ← 测试工程
+    ├── node_modules/react/         ← React 副本 B
+    └── src/index.tsx               ← import * as React from 'react' → 解析到副本 B
+```
+
+Metro 的 `nodeModulesPaths` 包含了两个目录，对不同的导入上下文解析到不同的 `react` 路径。
+
+### 诊断方法
+
+构建 dev bundle 并检查 React 模块路径：
+
+```bash
+npx react-native bundle --platform harmony --dev true \
+  --entry-file index.js --bundle-output /tmp/test-bundle-dev.js
+
+grep -oE '(node_modules|\.\./node_modules)/react/index\.js' /tmp/test-bundle-dev.js | sort | uniq -c
+```
+
+如果输出包含两个不同路径，即为多副本问题：
+
+```
+   1 node_modules/react/index.js          ← example 的
+   1 ../node_modules/react/index.js       ← 库根目录的
+```
+
+### 解决方案
+
+在 `metro.config.js` 中**包装** RNOH 的 `resolveRequest`，拦截裸 `react` 导入：
+
+```javascript
+const path = require('path');
+const {mergeConfig, getDefaultConfig} = require('@react-native/metro-config');
+const {createHarmonyMetroConfig} = require('@react-native-oh/react-native-harmony/metro.config');
+
+const projectRoot = __dirname;
+const libraryRoot = path.resolve(projectRoot, '..');
+const exampleNodeModules = path.resolve(projectRoot, 'node_modules');
+
+// 只拦截裸 'react' 导入，强制解析到 example 的 node_modules
+const SINGLETON_MODULES = new Set(['react']);
+
+// 先获取 RNOH 的 resolveRequest
+const harmonyConfig = createHarmonyMetroConfig({
+  reactNativeHarmonyPackageName: '@react-native-oh/react-native-harmony',
+});
+const rnohResolveRequest = harmonyConfig.resolver?.resolveRequest;
+
+// 包装：先拦截 react，其余委托给 RNOH
+function wrappedResolveRequest(context, moduleName, platform) {
+  if (SINGLETON_MODULES.has(moduleName)) {
+    return {
+      filePath: path.resolve(exampleNodeModules, moduleName, 'index.js'),
+      type: 'sourceFile',
+    };
+  }
+  if (rnohResolveRequest) {
+    return rnohResolveRequest(context, moduleName, platform);
+  }
+  return context.resolveRequest(context, moduleName, platform);
+}
+
+const config = {
+  watchFolders: [libraryRoot],
+  resolver: {
+    nodeModulesPaths: [
+      exampleNodeModules,
+      path.resolve(libraryRoot, 'node_modules'),
+    ],
+    resolveRequest: wrappedResolveRequest,
+  },
+  transformer: {
+    getTransformOptions: async () => ({
+      transform: {
+        experimentalImportSupport: false,
+        inlineRequires: true,
+      },
+    }),
+  },
+};
+
+module.exports = mergeConfig(
+  getDefaultConfig(__dirname),
+  harmonyConfig,
+  config,
+);
+```
+
+#### 关键约束
+
+1. **不能直接设置 `resolveRequest` 覆盖 RNOH**：`mergeConfig` 按从左到右应用，后面的 config 的 `resolveRequest` 会完全覆盖前面的。RNOH 的 `createHarmonyMetroConfig` 提供了自己的 `resolveRequest`，处理 `.harmony.js` 平台文件解析、`react-native` → `@react-native-oh/react-native-harmony` 重定向等。如果直接覆盖，harmony 平台构建会失败。
+
+2. **不要拦截 `react-native`**：RNOH 的 resolver 会将 `react-native` 重定向到 `@react-native-oh/react-native-harmony`。如果也拦截 `react-native`，会破坏这个重定向。只需拦截 `react`（裸导入）。
+
+3. **必须先获取 RNOH 的 resolveRequest 引用，再在 config 中包装**：通过 `harmonyConfig.resolver?.resolveRequest` 提取引用，在 `wrappedResolveRequest` 中调用它。
+
+#### 验证
+
+```bash
+npx react-native bundle --platform harmony --dev true \
+  --entry-file index.js --bundle-output /tmp/test-bundle-dev.js
+
+grep -oE '(node_modules|\.\./node_modules)/react/index\.js' /tmp/test-bundle-dev.js | sort | uniq -c
+```
+
+正确结果应只有 1 个：
+
+```
+   1 node_modules/react/index.js
+```
+
+## 崩溃 3：白屏无渲染（加载旧 bundle）
+
+### 症状
+
+修复 metro.config.js 后 `npm run dev` 构建成功，但设备上仍然白屏或崩溃。Metro dev server 未运行时尤其明显。
+
+### 根因
+
+鸿蒙应用启动时按优先级尝试多个 bundle 来源（见 `Index.ets` 中的 `AnyJSBundleProvider`）：
+
+1. `MetroJSBundleProvider` — 从 Metro dev server 加载（需要 Metro 运行中）
+2. `FileJSBundleProvider('/data/storage/el2/base/files/bundle.harmony.js')` — 从设备文件加载
+3. `ResourceJSBundleProvider('hermes_bundle.hbc')` — 从编译好的 Hermes 字节码加载
+4. `ResourceJSBundleProvider('bundle.harmony.js')` — 从 rawfile 资源加载
+
+如果 Metro 未运行，且 HAP 未重新构建，设备会加载**编译进 HAP 的旧 `rawfile/bundle.harmony.js`**（包含修复前的重复 React 实例）。
+
+### 诊断方法
+
+```bash
+# 检查 rawfile 中的 bundle 是否有重复 React
+grep -oE '(node_modules|\.\./node_modules)/react/index\.js' \
+  harmony/entry/src/main/resources/rawfile/bundle.harmony.js | sort | uniq -c
+```
+
+如果输出两个路径，说明 rawfile 中是旧 bundle。
+
+### 解决方案
+
+重新构建 bundle 并重新部署 HAP：
+
+```bash
+# 1. 重新构建 bundle（会更新 harmony/entry/src/main/resources/rawfile/bundle.harmony.js）
+npm run dev
+
+# 2. 在 DevEco Studio 中 Build → Run，重新编译 HAP 并安装到设备
+```
+
+**注意**：`npm run dev` 只更新源文件目录中的 `bundle.harmony.js`，DevEco Studio 构建时才会将其打包进 HAP。仅执行 `npm run dev` 不重新构建 HAP 是不够的。
+
+#### 快速验证（不重新构建 HAP）
+
+启动 Metro dev server，让设备实时加载最新 bundle：
+
+```bash
+# 设置端口转发
+hdc fport tcp:8081 tcp:8081
+
+# 启动 Metro（会自动执行 hdc rport）
+npm run start
+```
+
+在设备上重新打开应用，Metro 会提供最新的 bundle。如果应用正常渲染，说明问题已解决，接下来只需重新构建 HAP 即可。
+
+## 崩溃 4：Jest 单元测试中的 React 多副本
+
+### 症状
+
+Jest 测试中调用 hooks 时崩溃：`Cannot read properties of null (reading 'useRef')` 或 `reading 'useState'`。
+
+### 根因
+
+与崩溃 2 相同的根因——库根目录和 example 目录各有一份 `node_modules/react`。但 Jest 环境下的解决方式不同。
+
+### 解决方案
+
+在 `jest.config.js` 的 `moduleNameMapper` 中强制统一 React 路径：
+
+```javascript
+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-troubleshooting.md](jest-troubleshooting.md) 问题 1。
+
+## 崩溃 5：HAP 安装失败 — no signature file
+
+### 症状
+
+`hdc install entry-default-unsigned.hap` 返回错误：
+
+```text
+error: failed to install bundle. code:9568320 error: no signature file.
+```
+
+### 根因
+
+工程的 `build-profile.json5` 中 `signingConfigs` 为空数组 `[]` 或缺失。hvigor 构建时跳过签名步骤，生成 unsigned HAP，设备拒绝安装。
+
+### 解决方案
+
+**不要自行创建签名文件**。从平台统一签名配置文件读取并合并：
+
+**签名配置文件**：`3rdLibraryLoop/Server/` 目录下的 `.signing` 文件（相对于本 SKILL 的 references 目录为 `../../../.signing`）
+
+```bash
+# 1. 读取签名配置（路径相对于 Server 目录）
+cat ../../.signing
+
+# 2. 将 signingConfigs 数组合并到工程的 build-profile.json5
+#    将 .signing 文件中的 "signingConfigs" 数组内容
+#    写入 build-profile.json5 的 "app.signingConfigs" 字段
+#    确保 products[0].signingConfig = "default" 引用名称匹配
+
+# 3. 确认签名材料文件存在（路径来自 .signing 文件中的 certpath/profile/storeFile）
+ls -la $HOME/.ohos/config/*.cer $HOME/.ohos/config/*.p7b $HOME/.ohos/config/*.p12
+
+# 4. 清理并使用 devecocli 重新构建
+cd <project>/example/harmony
+devecocli build clean
+devecocli build --modules entry@default --build-mode debug
+
+# 5. 安装到设备
+hdc install <project>/example/harmony/entry/build/default/outputs/default/entry-default-unsigned.hap
+```
+
+**合并后的 build-profile.json5 示例**：
+
+```json5
+{
+  "app": {
+    "products": [
+      {
+        "name": 'default',
+        "signingConfig": 'default',  // 引用下面的 signingConfigs 名称
+        "compatibleSdkVersion": '5.0.0(12)',
+        "runtimeOS": 'HarmonyOS'
+      }
+    ],
+    "signingConfigs": [
+      {
+        "name": "default",
+        "type": "HarmonyOS",
+        "material": {
+          "certpath": "$HOME/.ohos/config/xxx.cer",
+          "keyAlias": "debugKey",
+          "keyPassword": "xxx",
+          "profile": "$HOME/.ohos/config/xxx.p7b",
+          "signAlg": "SHA256withECDSA",
+          "storeFile": "$HOME/.ohos/config/xxx.p12",
+          "storePassword": "xxx"
+        }
+      }
+    ]
+  },
+  // ... modules 配置保持不变
+}
+```
+
+## 检查清单
+
+修复运行时崩溃后，逐项确认：
+
+- [ ] `example/src/index.tsx` 有 `export default ExampleApp;`
+- [ ] `export default` 在 `AppRegistry.registerComponent` 之前
+- [ ] `app.json` 的 `name` 与 `Index.ets` 的 `appKey` 一致
+- [ ] `metro.config.js` 包装了 RNOH 的 `resolveRequest`（未直接覆盖）
+- [ ] dev bundle 中只有 1 个 `react/index.js` 路径
+- [ ] `npm run dev` 重新生成了 `rawfile/bundle.harmony.js`
+- [ ] `build-profile.json5` 的 `signingConfigs` 已从 `.signing` 文件合并（非空）
+- [ ] HAP 构建输出无 `Will skip sign` 警告
+- [ ] `hdc install` 成功安装 HAP 到设备
+- [ ] 设备上应用正常启动渲染，无崩溃

package/vendor/Server/Skills/rnoh-lib-test-align/references/unit-test-template.md

@@ -0,0 +1,223 @@
+# 单元测试编写指南
+
+RN 0.84 + React 19 环境下，为鸿蒙化组件编写 jest 单元测试的模板和最佳实践。
+
+本文档基于 rntpc_picker 库的实战经验整理，适用于所有 Fabric 组件的鸿蒙化测试。
+
+## 测试架构
+
+### 核心思路
+
+鸿蒙化组件（如 `PickerHarmony.harmony.js`）使用 Fabric 原生组件（如 `RNCPickerNativeComponent`）。
+在单元测试中，我们 mock 掉 Fabric 原生组件，通过 `globalThis` 捕获传入的 props，从而验证组件逻辑。
+
+```text
+测试文件                    被测组件                   Mock 原生组件
+PickerHarmony.test.tsx  →  PickerHarmony.harmony.js  →  __mocks__/RNCPickerNativeComponent.js
+                                                          ↓
+                                                     globalThis.__CAPTURED_PROPS__
+                                                          ↓
+                                                     测试断言读取
+```
+
+### Mock 原生组件模板
+
+适用于所有 `codegenNativeComponent` 生成的 Fabric 组件：
+
+```javascript
+// __mocks__/<ComponentName>NativeComponent.js
+const React = require('react');
+
+// NativeCommands mock
+const Commands = {
+  // 替换为实际的 command 名称
+  setNativeSelectedIndex: jest.fn(),
+};
+
+// forwardRef 捕获 props，通过 globalThis 传递给测试
+const MockNativeComponent = React.forwardRef((props, ref) => {
+  globalThis.__COMPONENT_CAPTURED_PROPS__ = props;
+  globalThis.__COMPONENT_CAPTURED_ONCHANGE__ = props.onChange; // 按需捕获事件回调
+  React.useImperativeHandle(ref, () => ({
+    setNativeProps: jest.fn(),
+  }));
+  return React.createElement('NativeComponent', props);
+});
+
+module.exports = {
+  __esModule: true,
+  default: MockNativeComponent,
+  Commands,
+};
+```
+
+### Mock react-native 模板
+
+```javascript
+// __mocks__/react-native.js
+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,
+  // 按需添加：Button, ScrollView, Switch, I18nManager 等
+};
+```
+
+## 测试文件模板
+
+### 基本结构
+
+```typescript
+import * as React from 'react';
+import TestRenderer, {act} from 'react-test-renderer';
+
+// 1. Mock Fabric 原生组件（jest.mock 会被自动提升到文件顶部）
+jest.mock('<相对路径>/<ComponentName>NativeComponent', () => {
+  return require('<相对路径>/__mocks__/<ComponentName>NativeComponent');
+});
+
+// 2. 导入被测组件（此时原生组件已被 mock）
+import MyComponent from '<相对路径>/<ComponentName>.harmony';
+
+const {Item} = MyComponent as any; // 如有子组件
+
+// 3. 快捷访问器
+const lastProps = (): any => globalThis.__COMPONENT_CAPTURED_PROPS__;
+const lastOnChange = (): any => globalThis.__COMPONENT_CAPTURED_ONCHANGE__;
+
+// 4. act() 包裹的渲染辅助函数（React 19 必须）
+function renderComponent(element: React.ReactElement) {
+  let renderer;
+  act(() => {
+    renderer = TestRenderer.create(element);
+  });
+  return renderer;
+}
+
+// 5. 测试用例
+describe('MyComponent', () => {
+  beforeEach(() => {
+    globalThis.__COMPONENT_CAPTURED_PROPS__ = null;
+    globalThis.__COMPONENT_CAPTURED_ONCHANGE__ = null;
+  });
+
+  // 渲染基础测试
+  describe('渲染基础测试', () => {
+    it('should render with children', () => {
+      renderComponent(<MyComponent prop1="value" />);
+      expect(lastProps()).toBeTruthy();
+    });
+
+    it('should render without crashing with empty children', () => {
+      renderComponent(<MyComponent prop1="value">{null}</MyComponent>);
+      expect(lastProps()).toBeTruthy();
+    });
+  });
+
+  // 状态计算测试
+  describe('状态计算', () => {
+    it('should calculate correct state based on prop', () => {
+      renderComponent(<MyComponent selectedValue="key1" />);
+      expect(lastProps().selectedIndex).toBe(1);
+    });
+  });
+
+  // 事件处理测试
+  describe('事件处理', () => {
+    it('should call onChange and onValueChange', () => {
+      const onChange = jest.fn();
+      const onValueChange = jest.fn();
+      renderComponent(<MyComponent onChange={onChange} onValueChange={onValueChange} />);
+
+      const mockEvent = {
+        nativeEvent: { newValue: 'key1', newIndex: 1 },
+      };
+      act(() => {
+        lastOnChange()(mockEvent);
+      });
+
+      expect(onChange).toHaveBeenCalledWith(mockEvent);
+      expect(onValueChange).toHaveBeenCalledWith('key1', 1);
+    });
+
+    it('should not crash when callbacks not provided', () => {
+      renderComponent(<MyComponent />);
+      expect(() => {
+        act(() => { lastOnChange()({ nativeEvent: {} }); });
+      }).not.toThrow();
+    });
+  });
+
+  // Prop 传递测试
+  describe('prop 传递到原生组件', () => {
+    it('should pass testID to native', () => {
+      renderComponent(<MyComponent testID="my-id" />);
+      expect(lastProps().testID).toBe('my-id');
+    });
+
+    it('should pass enabled to native', () => {
+      renderComponent(<MyComponent enabled={false} />);
+      expect(lastProps().enabled).toBe(false);
+    });
+  });
+
+  // ref 转发测试
+  describe('ref forwarding', () => {
+    it('should forward ref to native', () => {
+      const ref = React.createRef() as any;
+      renderComponent(<MyComponent ref={ref} />);
+      expect(ref.current).toBeTruthy();
+    });
+  });
+
+  // 静态属性测试
+  describe('static properties', () => {
+    it('should expose Item as static property', () => {
+      expect(MyComponent.Item).toBeDefined();
+    });
+  });
+});
+```
+
+## 测试用例设计原则
+
+### 1. 覆盖率维度
+
+| 维度 | 覆盖内容 | 示例 |
+| ---- | -------- | ---- |
+| 渲染 | 组件能正常渲染，props 正确传递 | `expect(lastProps()).toBeTruthy()` |
+| 状态计算 | useMemo/useState 计算结果正确 | `expect(lastProps().selectedIndex).toBe(1)` |
+| 数据映射 | children → items 映射正确 | `expect(lastProps().items[0]).toEqual({...})` |
+| 类型转换 | String/Number 转换正确 | `expect(lastProps().items[0].label).toBe('123')` |
+| 事件处理 | onChange/onValueChange 正确调用 | `expect(onValueChange).toHaveBeenCalledWith('key1', 1)` |
+| 边界值 | null/undefined/默认值处理 | `expect(lastProps().numberOfLines).toBe(1)` |
+| 数值处理 | round/clamp 逻辑 | `expect(lastProps().numberOfLines).toBe(3)` |
+| Prop 透传 | 所有 prop 正确传递到原生组件 | `expect(lastProps().testID).toBe('my-id')` |
+| Ref 转发 | ref 正确转发 | `expect(ref.current).toBeTruthy()` |
+| 静态属性 | 子组件作为静态属性暴露 | `expect(MyComponent.Item).toBeDefined()` |
+
+### 2. 测试优先级
+
+1. **P0 — 核心逻辑**: 状态计算（useMemo）、数据映射（children → items）
+2. **P0 — 事件处理**: onChange/onValueChange 回调验证
+3. **P1 — Prop 传递**: 所有 props 正确传递到原生组件
+4. **P1 — 边界值**: null/undefined/默认值/数值处理
+5. **P2 — Ref 转发**: ref 正确转发到原生组件
+6. **P2 — 静态属性**: 子组件（如 Item）正确暴露
+
+### 3. 不适合单元测试的内容
+
+以下内容依赖原生运行时，不适合在 jest 单元测试中覆盖，应在真机集成测试中验证：
+
+- `useLayoutEffect` 中通过 `global.nativeFabricUIManager` 调用 NativeCommands
+- `setNativeProps` 实际效果
+- `processColor` 的真实颜色转换（mock 中透传即可）
+- 原生组件的实际渲染行为
+
+在覆盖率报告中标注为「不适用（原生环境）」。