FilesLast commitLast update
3 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
4 months ago
README

@cptf/benchmark-rn

CPTF benchmark 插件 —— RN 设备侧。提供 React Native 场景下的渲染计时原生组件、测量容器 HOC、双态场景、设备侧指标上报通道。

与 @cptf/benchmark(host 侧 collector)互为兄弟;二者经 WebSocket MetricEvent 协议解耦。本包只进设备 RN bundle(Metro 打包),host 运行器不加载它。


指标说明

renderTime

业务含义:从用户点击「渲染」按钮到首批子组件首帧绘制完成的时间。衡量 React Native 列表冷启动渲染性能。

测量链路:

Button.onPress(event.nativeEvent.timestamp)
  → RenderTimer.startMarker(marker, timestamp)     // 记录起点(press 时间戳)
  → React 渲染 N 个子组件
  → <RenderTimer> 原生视图挂载
  → 原生 onDraw() 首次绘制
  → MarkerStore.endMarker(marker)                  // elapsed = uptimeMillis() - start
  → onMarkerPainted 事件回传 paintTime
  → setRenderTime(paintTime)                        // UI 显示 "Took Xms"
  → deviceMetricProvider.report('renderTime', X)    // WebSocket 上报

各平台实现:

平台 起测时钟 终测时机 原生回调 说明
HarmonyOS steady_clock (C++) onAppear → onDraw 首帧 onMarkerPainted(paintTime) MarkerStore 用 std::chrono::steady_clock,startMarker 接受 JS 传入的 timestamp(<=0 时回退 uptimeMillis())
Android SystemClock.uptimeMillis() View.onDraw() 首次绘制 OnMarkerPaintedEvent → onMarkerPainted MarkerStore.kt 用 ConcurrentHashMap,startMarker 接受 JS 传入的 Double timestamp

时钟同源性:Button.onPress 的 event.nativeEvent.timestamp 在 HarmonyOS 和 Android 上均为 uptimeMillis(系统启动后毫秒数),与原生 MarkerStore 的 uptimeMillis() 同源,差值正确。

unmountTime

业务含义:从用户点击「重置」按钮到 MeasureContainer 及其子组件完全从原生视图树移除的时间。衡量大规模列表卸载性能。

测量链路:

Button.onPress(timestamp)
  → RenderTimer.startMarker('unmount_' + marker, timestamp)  // 记录卸载起点
  → setActive(false)
  → React 卸载 MeasureContainer + N 个子组件
  → <RenderTimer> 原生视图 onDetachedFromWindow
  → MarkerStore.endMarker('unmount_' + marker)                 // elapsed
  → DeviceEventEmitter.emit('onUnmountComplete', {unmountTime})
  → setUnmountTime(unmountTime)                                // UI 显示 "Unmount took Xms"
  → deviceMetricProvider.report('unmountTime', X)               // WebSocket 上报

各平台实现:

平台 终测时机 事件机制 说明
HarmonyOS ComponentInstance::onFinalDestroy DeviceEventEmitter C++ 侧 endMarker 后通过 turbo module 发 device event
Android View.onDetachedFromWindow() RCTDeviceEventEmitter.emit Kotlin 侧 endMarker 后通过 DeviceEventManagerModule 发 device event

unmount 走 DeviceEventEmitter(全局事件),不走组件 prop。<RenderTimer> 的 codegen spec 只声明 onMarkerPainted。


指标上报协议

设备侧 deviceMetricProvider 通过 WebSocket 将指标事件推送到宿主:

[设备 RN bundle]
BenchmarkScene (双态 UI: start/reset 按钮)
  ├─ Button.onPress(nativeEvent.timestamp)
  │     → RenderTimer.startMarker(marker, timestamp)
  │
  ├─ MeasureContainer
  │    ├─ <RenderTimer onMarkerPainted>  (原生 onDraw 首帧)
  │    │     └→ deviceMetricProvider.report('renderTime', paintTime) ──┐
  │    │
  │    └─ DeviceEventEmitter('onUnmountComplete') ← 原生 onDetachedFromWindow
  │          └→ deviceMetricProvider.report('unmountTime', …) ───────┤
  │                                                                    ↓
  └─ deviceMetricProvider (WS client + pending queue + file fallback)
       → ws://127.0.0.1:18081 (hdc rport / adb reverse)
                          [宿主] MetricWebSocketServer → globalBus.emit
                               → @cptf/benchmark collectors (RenderTimeCollector / UnmountTimeCollector)

WebSocket 连接:

  • URL: ws://127.0.0.1:18081
  • HarmonyOS: host 通过 hdc rport tcp:18081 建立端口转发
  • Android: host 通过 adb reverse tcp:18081 建立端口转发
  • 设备 app 在 BenchmarkScene 挂载时调 deviceMetricProvider.connect()
  • 消息未连接时缓存在 pending 队列,连接后批量发送

事件格式:

{
  "type": "renderTime",
  "value": 437,
  "markerName": "views1500",
  "timestamp": 1783677892000,
  "deviceId": "7NXBB26324000068"
}

指标类型常量由 @cptf/benchmark/metric-types 统一定义,两端导入同一常量:

export const RENDER_TIME_METRIC_TYPE = 'renderTime';
export const UNMOUNT_TIME_METRIC_TYPE = 'unmountTime';

Host 侧 collector fallback:当 WebSocket 事件未到达时,collector 尝试从 UI 读取 benchmark-render-time / benchmark-unmount-time 元素的文本解析数值(等待 15s)。

文件回退(仅 HarmonyOS):deviceMetricProvider 同时将指标写入 /data/local/tmp/cptf-metrics.json,供 host 在 WebSocket 不可用时读取。

deviceId:从 /data/local/tmp/cptf-device-id 读取,用于多设备并行时区分事件来源。


模块

文件 职责
src/render-timer/NativeRenderTimer.ts TurboModule spec:startMarker(name, time)
src/render-timer/RenderTimerNativeComponent.ts Codegen 原生组件 spec:markerName prop + onMarkerPainted(paintTime) 事件
src/Button.tsx Pressable 按钮,onPress 回传 nativeEvent.timestamp(uptimeMillis)
src/MeasureContainer.tsx 计时容器:黑条分隔 + children + <RenderTimer>;onMarkerPainted → 显示 renderTime + WebSocket 上报
src/BenchmarkScene.tsx 双态场景:start → 渲染;reset → 卸载;监听 onUnmountComplete device event
src/device-metric-provider.ts 设备侧 WS client + pending 队列 + 文件回退 + deviceId 加载
src/scenarios.tsx BenchmarkScenario 类型定义(仅类型,场景实例在 app 侧)
src/index.tsx 统一导出
android/ Kotlin 原生实现:RenderTimerView(onDraw/onDetachedFromWindow) + RenderTimerModule(startMarker) + MarkerStore(ConcurrentHashMap)
harmony/benchmarkrn/ C++ 原生实现:RenderTimerComponentInstance + MarkerStore(steady_clock) + TurboModule

原生测量机制

起测点 = press 事件 timestamp

Button.onPress 获取 event.nativeEvent.timestamp(HarmonyOS/Android 均为 uptimeMillis),传给 RenderTimer.startMarker(marker, timestamp)。MarkerStore 存储该值,endMarker 时用 uptimeMillis() - stored 计算耗时。

时钟同源:press timestamp 和 native uptimeMillis() 使用同一系统时钟(steady_clock / SystemClock.uptimeMillis()),不受墙钟调整影响。

renderTime = native onDraw 首帧

<RenderTimer> 原生组件在首次 onDraw 时调 MarkerStore.endMarker(markerName),得到 paintTime = uptimeMillis() - startTimestamp。通过 onMarkerPainted 事件回传 JS。

  • HarmonyOS:ComponentInstance 的 onDraw 回调
  • Android:View.onDraw(Canvas) 首次调用(_alreadyLogged 标志确保只触发一次)

unmountTime = native onDetachedFromWindow

reset 按钮调 startMarker('unmount_' + marker, timestamp) 后 setActive(false)。React 卸载 MeasureContainer,<RenderTimer> 原生视图触发 onDetachedFromWindow:

  • HarmonyOS:onFinalDestroy → endMarker → device event
  • Android:onDetachedFromWindow() → endMarker → RCTDeviceEventEmitter.emit

用法

设备侧(app)

场景实例定义在 app 侧(app/tests/scenes/benchmark-scenarios.tsx),不在本包内:

// app/tests/scenes/benchmark-scenarios.tsx
import type { BenchmarkScenario } from '@cptf/benchmark-rn';

const renderView = (i: number) => (
  <View key={i} style={{ width: 100, height: 100, backgroundColor: 'red', margin: 5 }}
    importantForAccessibility="no-hide-descendants" />
);

export const VIEWS_1500: BenchmarkScenario = {
  marker: 'views1500', count: 1500, label: 'View', kind: 'view', renderItem: renderView,
};

场景组件用薄 TestScene 包装,内层放 <BenchmarkScene>:

// app/tests/scenes/benchmark-scenes.tsx
import { TestScene } from './TestScene';
import { BenchmarkScene } from '@cptf/benchmark-rn';
import { VIEWS_1500 } from './benchmark-scenarios';

export const Views1500Scene: React.FC<{ testCaseId?: string }> = (props) => (
  <TestScene sceneId="views-1500" sections={[{ id: 'views-1500-content', title: 'Views × 1500',
    render: () => <BenchmarkScene scenario={VIEWS_1500} /> }]} {...props} />
);

用例侧(host)

@Step('点击渲染按钮', { action: 'click', target: 'benchmark-start-btn' })
async startRender() { await this.ui?.sleep(8000); }

@Step('点击重置按钮触发卸载', { action: 'click', target: 'benchmark-reset-btn' })
async resetUnmount() { await this.ui?.sleep(5000); }

sleep 时长应 ≥ 场景渲染/卸载预期耗时,确保 onMarkerPainted / onUnmountComplete 事件有足够时间触发并经 WebSocket 到达 host。

本包是 src 包

main: src/index,Metro 会转译 node_modules 内软链 .tsx(设备 bundle)。无需 build。改源码后重新 bundleHarmony:release / bundleAndroid:release 即可。


扩展指南

新增场景(例:views-8000)

① app 侧加 scenario(app/tests/scenes/benchmark-scenarios.tsx):

export const VIEWS_8000: BenchmarkScenario = {
  marker: 'views8000', count: 8000, label: 'View', kind: 'view', renderItem: renderView,
};

② app 侧加场景组件(app/tests/scenes/benchmark-scenes.tsx):

export const Views8000Scene = (props) => (
  <TestScene sceneId="views-8000" sections={[{ id: 'views-8000-content', title: 'Views × 8000',
    render: () => <BenchmarkScene scenario={VIEWS_8000} /> }]} {...props} />
);

③ 重跑场景索引生成:pnpm run generateScenesIndex

④ app 侧加用例:

// app/tests/cases/performance/views-8000-render-perf.test.ts
import '@cptf/benchmark';
@Test({ id: 'views-8000-render-perf', scene: 'views-8000',
  collect: ['renderTime','unmountTime','fps','memoryPeak'], executeTimes: 5, ... })
class Views8000RenderPerfTest extends PerformanceTest {
  @Step('点击渲染按钮', { action:'click', target:'benchmark-start-btn' })
  async s(){ await this.ui?.sleep(8000); }
  @Step('点击重置按钮触发卸载', { action:'click', target:'benchmark-reset-btn' })
  async r(){ await this.ui?.sleep(5000); }
}

marker 名建议与 sceneId 数字部分一致但无连字符(views8000),sceneId 用连字符(views-8000)。


已知问题

Android 大规模场景 ATX 超时(已解决)

现象:渲染大量元素(如 5000 个 Image)后,ATX dumpWindowHierarchy 遍历辅助功能树 24000+ 节点耗时 ~5 分钟,超过 HTTP 超时。旧版 u2.jar(≤3.5.2)的 objInfo 不解析 selector 属性,始终返回空 UiSelector[](匹配根元素),无法绕过全树遍历。

根因:

  1. Android 辅助功能树包含所有节点(含 isVisibleToUser() == false 的不可见项),5000 个 Image ≈ 24000 节点
  2. 旧版 u2.jar(≤3.5.2)的 objInfo JSON-RPC 不解析 selector 属性(resourceId/description 等均被忽略)
  3. description selector 即使被正确解析,底层 UiSelector 仍需全树遍历(~15s),而 resourceId selector 用索引查找(~0.2s)

解决方案:

  1. 升级 u2.jar 到 ≥3.7.0:cptf check-env --upgrade-u2(或 pip install uiautomator2==3.7.0 + adb push u2.jar)
  2. 框架侧 objInfoByTestId 使用 resourceId selector(mask=2097152)做元素查找,底层 UiSelector 索引查找 ~0.2s,不遍历全树
  3. dumpHierarchy 仍用于全布局快照(属性读取、UI 对比),但不再用于单元素查找

验证:images-5000(本地 base64 图片)Android 端 renderTime=1775ms、unmountTime=77ms,51 秒完成,无 ATX 崩溃。

详见 @cptf/framework 的 docs/TROUBLESHOOTING.md 第 2.5 节。

本地图片 vs 网络图片场景

场景 sceneId 图片来源 renderTime 含义 跨平台可比性
IMAGES_1500 images-1500 本地 base64 PNG(239 字节) 纯解码+渲染 ✓ 可比
IMAGES_5000 images-5000 本地 base64 PNG(239 字节) 纯解码+渲染 ✓ 可比
NETWORK_IMAGES_1500 net-images-1500 picsum.photos/id/{固定ID}/100 网络+解码+渲染 ⚠️ 网络延迟不同
NETWORK_IMAGES_5000 net-images-5000 picsum.photos/id/{固定ID}/100 网络+解码+渲染 ⚠️ 网络延迟不同

本地图片用 data:image/png;base64,... 内联,所有设备看到完全相同的图片,无网络依赖,跨平台对比有效。网络图片用 picsum.photos/id/{固定ID}/100(固定 ID 保证同一张图片),但不同设备网络延迟不同,renderTime 含网络因素。

HarmonyOS memoryPeak 返回 0

现象:部分 HarmonyOS 设备 hidumper --mem <PID> 返回空,导致 memoryPeak: 0.00。

原因:PID 解析失败或 hidumper 命令在该设备上行为不同。

Android renderTime 跨迭代保留

现象:预热迭代收到的 WebSocket renderTime 事件在正式迭代的 collect() 中仍可读到。

原因:onStart() 不再重置 this.value = 0,避免预热迭代的值被清零。如果正式迭代没有新的渲染事件(如 start-btn 找不到),collect() 返回预热迭代的值。


架构

@cptf/benchmark-rn (插件·自拥 native 测量原语)
  ├── src/render-timer/           Codegen specs (NativeRenderTimer.ts, RenderTimerNativeComponent.ts)
  ├── src/                        RN device JS (MeasureContainer / BenchmarkScene / Button / device-metric-provider)
  ├── android/                    Android Kotlin (RenderTimerView / RenderTimerModule / MarkerStore)
  ├── harmony/benchmarkrn/        HarmonyOS C++ (ComponentInstance / TurboModule / MarkerStore)
  └── package.json                codegenConfig (name RenderTimerSpec, jsSrcsDir src/render-timer)

app (业务层·不含 benchmarkrn 原生代码)
  ├── tests/scenes/benchmark-scenarios.tsx   场景实例 (VIEWS_1500 等)
  ├── tests/scenes/benchmark-scenes.tsx       场景组件 (Views1500Scene 等)
  ├── harmony/entry/.../CMakeLists.txt        add_subdirectory → @cptf/benchmark-rn/harmony/benchmarkrn/...
  └── android                                 autolink 自动构建 :@cptf/benchmark-rn

构建机制:

  • HarmonyOS:codegen-harmony 读 packageJson.harmony.codegenConfig;C++ 模块自包含,经 PackageProvider.cpp 手动注册。app 的 CMake add_subdirectory 解析到插件内 cpp。
  • Android:react-native config 解析 codegenConfig,autolink 构建 :@cptf/benchmark-rn 库,自动注册 RenderTimerPackage。