@ohos-cpf/3rdloop 0.0.1 → 0.0.3

package/vendor/Server/Skills/rnoh-cptf-demo-test/assets/TEST_TEMPLATE.md

@@ -1,216 +1,216 @@
-# CPTF 测试文件模板
-
-> Phase 3 生成测试文件时复制此模板，替换 `{占位符}`。模板来自 react-native-get-random-values 实战验证版本（18 步骤全部通过的结构）。
-
-## 1. 完整文件骨架
-
-```typescript
-/*
- * Copyright {year} {author}
- * SPDX-License-Identifier: MIT
- */
-
-import 'reflect-metadata';
-import { Test, Step, FunctionalTest, NavigationStrategyFactory } from '@cptf/framework';
-import type { UIElement } from '@cptf/framework';
-
-/**
- * {libName} (RNOH) 自动化功能测试
- *
- * 被测应用: {bundleId} (testerino 单页 Demo)
- * 覆盖能力:
- *   1. {能力分组 1}
- *   2. {能力分组 2}
- *   ...
- *
- * 实现说明:
- *   - Demo 为单页应用（无 module-list 首页、无 deep link scheme），
- *     注册自定义 'single-page' 导航策略：启动应用后直接等待 testerino
- *     面板就绪，跳过框架默认的 deep link / 点击导航。
- *   - Demo 按钮未设置 testID，全部通过按钮文本(textContains)定位；
- *     结果验证依赖点击后出现的业务文本。
- *   - {N} 个 TestCase 位于 ScrollView 中，屏幕外的按钮需智能滚动查找。
- */
-
-// ─── 单页应用导航策略 ───────────────────────────────────────────────
-NavigationStrategyFactory.registerStrategy('single-page', () => ({
-  id: 'single-page',
-  async navigateToTestScene(ctx): Promise<void> {
-    ctx.logger.debug('[single-page] 单页应用，跳过场景导航，等待 testerino 面板就绪');
-    // 等待 testerino 统计面板出现（TOTAL 计数文本），最长 15s
-    const deadline = Date.now() + 15000;
-    while (Date.now() < deadline) {
-      const panel = await ctx.ui.findByText('TOTAL');
-      if (panel) {
-        ctx.logger.debug('[single-page] testerino 面板已就绪');
-        return;
-      }
-      await ctx.ui.sleep(500);
-    }
-    ctx.logger.warn('[single-page] 未检测到 testerino 面板，继续执行');
-  },
-  async returnFromTestScene(_ctx): Promise<void> {
-    // 单页应用无需返回上级
-  },
-}));
-
-// ─── 用例定义 ───────────────────────────────────────────────────────
-@Test({
-  id: '{lib-short-name}-func',
-  name: '{libName} 功能测试',
-  module: 'functional',
-  platform: 'harmony',
-  category: '{分类}',
-  description: '覆盖 {libName} 的 {能力概述}',
-  navigationStrategy: 'single-page',
-  captureScreenshots: true,
-  waitAfterAction: 300,
-})
-class {LibName}Test extends FunctionalTest {
-  /** 滚动查找并点击指定文本按钮（屏幕外元素自动滚动定位） */
-  private async scrollAndClick(textKey: string, stepLabel: string): Promise<void> {
-    const btn = await this.ui!.scrollToFindElement(
-      { textContains: textKey, type: 'Button' },
-      { maxScrolls: 12, waitAfterScroll: 300 },
-    );
-    if (!btn) {
-      throw new Error(`未找到按钮: ${stepLabel} (关键字: ${textKey})`);
-    }
-    const ok = await this.ui!.clickElement(btn);
-    if (!ok) {
-      throw new Error(`点击按钮失败: ${stepLabel}`);
-    }
-    await this.sleep(600);
-  }
-
-  /** 断言屏幕上出现包含 expectedSub 的文本（带轮询重试） */
-  private async waitForText(expectedSub: string, timeout = 8000): Promise<UIElement | null> {
-    const deadline = Date.now() + timeout;
-    while (Date.now() < deadline) {
-      const el = await this.ui!.findByText(expectedSub);
-      if (el) return el;
-      await this.sleep(400);
-    }
-    return null;
-  }
-
-  /** 收集步骤结果并登记失败（供报告呈现） */
-  private report(passed: boolean, details: string): void {
-    this.currentStepResult = {
-      stepName: this.currentStepResult?.stepName || '校验',
-      passed,
-      details,
-    };
-    if (!passed) {
-      throw new Error(details);
-    }
-  }
-
-  // ── 1. {能力分组 1} ────────────────────────────────────────────────
-
-  @Step('{步骤描述}', { captureScreenshot: false, stepTimeout: 30000 })
-  async stepMethodName(): Promise<void> {
-    await this.scrollAndClick('{按钮 title 唯一子串}', '{按钮语义标签}');
-    // {断言策略说明：前缀文本 / 快照差集 / 值域校验}
-    const el = await this.waitForText('{结果文本前缀，源码逐字符复制}');
-    if (!el) {
-      throw new Error('点击后未出现{结果}文本');
-    }
-    const text = this.getChildText(el) || el.text || '';
-    this.report(text.includes('{期望值}'), `结果: "${text.trim()}"`);
-  }
-
-  // ... 每个 TestCase 一个 @Step
-
-  // ── 辅助: 快照差集收集无前缀结果（如裸数字） ──────────────────────
-  private lastSnapshot: Set<string> = new Set();
-
-  private async snapshotAllTexts(): Promise<Set<string>> {
-    const elements = await this.ui!.getLayout(true);
-    const texts = new Set<string>();
-    for (const el of elements) {
-      if (el.text && el.text.trim()) {
-        texts.add(el.text.trim());
-      }
-    }
-    return texts;
-  }
-
-  private async collectNumbersAfter(caseTitle: string): Promise<number[]> {
-    const after = await this.snapshotAllTexts();
-    const added: string[] = [];
-    for (const t of after) {
-      if (!this.lastSnapshot.has(t)) {
-        added.push(t);
-      }
-    }
-    this.lastSnapshot = after;
-    // 数字文本（可能为负）
-    const nums = added
-      .filter(t => /^-?\d+$/.test(t))
-      .map(t => parseInt(t, 10));
-    return nums;
-  }
-}
-
-export const testCaseExecutor = new {LibName}Test();
-```
-
-## 2. 各断言策略的 @Step 写法
-
-### 2.1 固定前缀文本断言（最常见）
-
-```typescript
-@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
-async xxx(): Promise<void> {
-  await this.scrollAndClick('{按钮子串}', '{标签}');
-  const el = await this.waitForText('错误信息');   // ← 前缀，可省略冒号
-  if (!el) throw new Error('点击后未出现错误信息文本');
-  const errText = this.getChildText(errEl) || errEl.text || '';
-  this.report(/ExpectedError/i.test(errText), `错误信息: "${errText.trim().substring(0, 120)}"`);
-}
-```
-
-### 2.2 快照差集断言（无前缀裸值）
-
-```typescript
-@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
-async xxx(): Promise<void> {
-  await this.scrollAndClick('{按钮子串}', '{标签}');
-  const nums = await this.collectNumbersAfter('{caseTitle}');
-  this.report(
-    nums.length >= 1 && nums.every(n => n >= {min} && n <= {max}),
-    `生成 ${nums.length} 个: [${nums.join(', ')}]，均在 [{min},{max}]`,
-  );
-}
-```
-
-### 2.3 demo 已知 bug 容错断言
-
-```typescript
-@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
-async xxx(): Promise<void> {
-  await this.scrollAndClick('{按钮子串}', '{标签}');
-  const errEl = await this.waitForText('错误信息');
-  if (!errEl) throw new Error('点击后未出现错误信息文本');
-  const errText = this.getChildText(errEl) || errEl.text || '';
-  // 注: demo 已知渲染 bug（'Text strings must be rendered within a <Text>'），
-  // 错误信息可能被 LogBox 覆盖，此处仅验证错误场景触发了错误输出。
-  const hasExpected = /ExpectedError/i.test(errText);
-  const hasRenderIssue = /<Text>|rendered within/i.test(errText);
-  this.report(hasExpected || hasRenderIssue, `错误信息: "${errText.trim().substring(0, 120)}"`);
-}
-```
-
-## 3. 编码规则速查
-
-| 规则 | 原因 |
-|------|------|
-| 文件首行 `import 'reflect-metadata'` | 装饰器运行时依赖 |
-| 每个 @Step 显式 `stepTimeout: 30000` | 默认 10s 不够滚动+点击+等待 |
-| 断言文本从 demo 源码逐字符复制 | 全角/半角冒号差异是头号失败根因 |
-| `captureScreenshot: false`（常规步骤） | 减少耗时；失败步骤框架自动截图 |
-| 文件末尾 `export const testCaseExecutor` | CLI 用例发现约定 |
-| 步骤名含中文+关键 API 名 | 报告可读性 |
-| scrollAndClick 后 `sleep(600)` | 等待点击生效+渲染 |
-| waitForText 轮询 400ms×20 次（8s） | 渲染时延容错 |
+# CPTF 测试文件模板
+
+> Phase 3 生成测试文件时复制此模板，替换 `{占位符}`。模板来自 react-native-get-random-values 实战验证版本（18 步骤全部通过的结构）。
+
+## 1. 完整文件骨架
+
+```typescript
+/*
+ * Copyright {year} {author}
+ * SPDX-License-Identifier: MIT
+ */
+
+import 'reflect-metadata';
+import { Test, Step, FunctionalTest, NavigationStrategyFactory } from '@cptf/framework';
+import type { UIElement } from '@cptf/framework';
+
+/**
+ * {libName} (RNOH) 自动化功能测试
+ *
+ * 被测应用: {bundleId} (testerino 单页 Demo)
+ * 覆盖能力:
+ *   1. {能力分组 1}
+ *   2. {能力分组 2}
+ *   ...
+ *
+ * 实现说明:
+ *   - Demo 为单页应用（无 module-list 首页、无 deep link scheme），
+ *     注册自定义 'single-page' 导航策略：启动应用后直接等待 testerino
+ *     面板就绪，跳过框架默认的 deep link / 点击导航。
+ *   - Demo 按钮未设置 testID，全部通过按钮文本(textContains)定位；
+ *     结果验证依赖点击后出现的业务文本。
+ *   - {N} 个 TestCase 位于 ScrollView 中，屏幕外的按钮需智能滚动查找。
+ */
+
+// ─── 单页应用导航策略 ───────────────────────────────────────────────
+NavigationStrategyFactory.registerStrategy('single-page', () => ({
+  id: 'single-page',
+  async navigateToTestScene(ctx): Promise<void> {
+    ctx.logger.debug('[single-page] 单页应用，跳过场景导航，等待 testerino 面板就绪');
+    // 等待 testerino 统计面板出现（TOTAL 计数文本），最长 15s
+    const deadline = Date.now() + 15000;
+    while (Date.now() < deadline) {
+      const panel = await ctx.ui.findByText('TOTAL');
+      if (panel) {
+        ctx.logger.debug('[single-page] testerino 面板已就绪');
+        return;
+      }
+      await ctx.ui.sleep(500);
+    }
+    ctx.logger.warn('[single-page] 未检测到 testerino 面板，继续执行');
+  },
+  async returnFromTestScene(_ctx): Promise<void> {
+    // 单页应用无需返回上级
+  },
+}));
+
+// ─── 用例定义 ───────────────────────────────────────────────────────
+@Test({
+  id: '{lib-short-name}-func',
+  name: '{libName} 功能测试',
+  module: 'functional',
+  platform: 'harmony',
+  category: '{分类}',
+  description: '覆盖 {libName} 的 {能力概述}',
+  navigationStrategy: 'single-page',
+  captureScreenshots: true,
+  waitAfterAction: 300,
+})
+class {LibName}Test extends FunctionalTest {
+  /** 滚动查找并点击指定文本按钮（屏幕外元素自动滚动定位） */
+  private async scrollAndClick(textKey: string, stepLabel: string): Promise<void> {
+    const btn = await this.ui!.scrollToFindElement(
+      { textContains: textKey, type: 'Button' },
+      { maxScrolls: 12, waitAfterScroll: 300 },
+    );
+    if (!btn) {
+      throw new Error(`未找到按钮: ${stepLabel} (关键字: ${textKey})`);
+    }
+    const ok = await this.ui!.clickElement(btn);
+    if (!ok) {
+      throw new Error(`点击按钮失败: ${stepLabel}`);
+    }
+    await this.sleep(600);
+  }
+
+  /** 断言屏幕上出现包含 expectedSub 的文本（带轮询重试） */
+  private async waitForText(expectedSub: string, timeout = 8000): Promise<UIElement | null> {
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const el = await this.ui!.findByText(expectedSub);
+      if (el) return el;
+      await this.sleep(400);
+    }
+    return null;
+  }
+
+  /** 收集步骤结果并登记失败（供报告呈现） */
+  private report(passed: boolean, details: string): void {
+    this.currentStepResult = {
+      stepName: this.currentStepResult?.stepName || '校验',
+      passed,
+      details,
+    };
+    if (!passed) {
+      throw new Error(details);
+    }
+  }
+
+  // ── 1. {能力分组 1} ────────────────────────────────────────────────
+
+  @Step('{步骤描述}', { captureScreenshot: false, stepTimeout: 30000 })
+  async stepMethodName(): Promise<void> {
+    await this.scrollAndClick('{按钮 title 唯一子串}', '{按钮语义标签}');
+    // {断言策略说明：前缀文本 / 快照差集 / 值域校验}
+    const el = await this.waitForText('{结果文本前缀，源码逐字符复制}');
+    if (!el) {
+      throw new Error('点击后未出现{结果}文本');
+    }
+    const text = this.getChildText(el) || el.text || '';
+    this.report(text.includes('{期望值}'), `结果: "${text.trim()}"`);
+  }
+
+  // ... 每个 TestCase 一个 @Step
+
+  // ── 辅助: 快照差集收集无前缀结果（如裸数字） ──────────────────────
+  private lastSnapshot: Set<string> = new Set();
+
+  private async snapshotAllTexts(): Promise<Set<string>> {
+    const elements = await this.ui!.getLayout(true);
+    const texts = new Set<string>();
+    for (const el of elements) {
+      if (el.text && el.text.trim()) {
+        texts.add(el.text.trim());
+      }
+    }
+    return texts;
+  }
+
+  private async collectNumbersAfter(caseTitle: string): Promise<number[]> {
+    const after = await this.snapshotAllTexts();
+    const added: string[] = [];
+    for (const t of after) {
+      if (!this.lastSnapshot.has(t)) {
+        added.push(t);
+      }
+    }
+    this.lastSnapshot = after;
+    // 数字文本（可能为负）
+    const nums = added
+      .filter(t => /^-?\d+$/.test(t))
+      .map(t => parseInt(t, 10));
+    return nums;
+  }
+}
+
+export const testCaseExecutor = new {LibName}Test();
+```
+
+## 2. 各断言策略的 @Step 写法
+
+### 2.1 固定前缀文本断言（最常见）
+
+```typescript
+@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
+async xxx(): Promise<void> {
+  await this.scrollAndClick('{按钮子串}', '{标签}');
+  const el = await this.waitForText('错误信息');   // ← 前缀，可省略冒号
+  if (!el) throw new Error('点击后未出现错误信息文本');
+  const errText = this.getChildText(errEl) || errEl.text || '';
+  this.report(/ExpectedError/i.test(errText), `错误信息: "${errText.trim().substring(0, 120)}"`);
+}
+```
+
+### 2.2 快照差集断言（无前缀裸值）
+
+```typescript
+@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
+async xxx(): Promise<void> {
+  await this.scrollAndClick('{按钮子串}', '{标签}');
+  const nums = await this.collectNumbersAfter('{caseTitle}');
+  this.report(
+    nums.length >= 1 && nums.every(n => n >= {min} && n <= {max}),
+    `生成 ${nums.length} 个: [${nums.join(', ')}]，均在 [{min},{max}]`,
+  );
+}
+```
+
+### 2.3 demo 已知 bug 容错断言
+
+```typescript
+@Step('{描述}', { captureScreenshot: false, stepTimeout: 30000 })
+async xxx(): Promise<void> {
+  await this.scrollAndClick('{按钮子串}', '{标签}');
+  const errEl = await this.waitForText('错误信息');
+  if (!errEl) throw new Error('点击后未出现错误信息文本');
+  const errText = this.getChildText(errEl) || errEl.text || '';
+  // 注: demo 已知渲染 bug（'Text strings must be rendered within a <Text>'），
+  // 错误信息可能被 LogBox 覆盖，此处仅验证错误场景触发了错误输出。
+  const hasExpected = /ExpectedError/i.test(errText);
+  const hasRenderIssue = /<Text>|rendered within/i.test(errText);
+  this.report(hasExpected || hasRenderIssue, `错误信息: "${errText.trim().substring(0, 120)}"`);
+}
+```
+
+## 3. 编码规则速查
+
+| 规则 | 原因 |
+|------|------|
+| 文件首行 `import 'reflect-metadata'` | 装饰器运行时依赖 |
+| 每个 @Step 显式 `stepTimeout: 30000` | 默认 10s 不够滚动+点击+等待 |
+| 断言文本从 demo 源码逐字符复制 | 全角/半角冒号差异是头号失败根因 |
+| `captureScreenshot: false`（常规步骤） | 减少耗时；失败步骤框架自动截图 |
+| 文件末尾 `export const testCaseExecutor` | CLI 用例发现约定 |
+| 步骤名含中文+关键 API 名 | 报告可读性 |
+| scrollAndClick 后 `sleep(600)` | 等待点击生效+渲染 |
+| waitForText 轮询 400ms×20 次（8s） | 渲染时延容错 |

package/vendor/Server/Skills/rnoh-cptf-demo-test/references/CPTF_SETUP.md

@@ -1,107 +1,107 @@
-# CPTF 测试工程搭建指南
-
-> Phase 2 的详细操作手册。核心解决两个问题：模块解析（link 依赖）与设备/应用配置。
-
-## 1. 前置检查
-
-```bash
-# 1. CPTF 框架源码位置（全局 pnpm link 安装）
-ls -la ~/Library/pnpm/global/5/node_modules/@cptf/framework   # 应为 symlink → 框架源码
-
-# 2. hdc 工具与设备
-hdc list targets    # 应输出设备 SN（如 026PMV25CH125405）
-
-# 3. demo hap 构建产物
-ls {demoPath}/harmony/entry/build/default/outputs/default/entry-default-signed.hap
-
-# 4. demo bundleId
-cat {demoPath}/AppScope/app.json5 | grep bundleName
-```
-
-## 2. cptf.config.json 完整配置
-
-```json
-{
-  "bundleId": "com.example.xxx",
-  "reportDir": "test-reports",
-  "reportFormat": "html",
-  "casesDir": "tests/cases",
-  "enableAlerts": true,
-  "platforms": {
-    "harmony": {
-      "toolPath": "hdc",
-      "bundleId": "com.example.xxx",
-      "appPath": "<demoPath 绝对路径>/harmony/entry/build/default/outputs/default/entry-default-signed.hap",
-      "devices": [
-        {
-          "id": "<设备SN>",
-          "screenWidth": 1280,
-          "screenHeight": 2832
-        }
-      ]
-    }
-  }
-}
-```
-
-**字段说明**：
-- `appPath` 必须是**绝对路径**（signed hap）
-- `screenWidth/screenHeight` 影响滚动与坐标计算，从 `hdc shell hidumper -s RenderService` 或设备规格获取
-- `casesDir` 相对 workspace 根；测试文件放 `tests/cases/functional/` 下自动被发现
-
-## 3. link 依赖建立（关键步骤）
-
-### 3.1 为什么不能用全局安装直接跑
-
-cptf CLI shim（`~/.pnpm/global/5/.bin/cptf`）通过 NODE_PATH 注入模块路径，其中包含 `.pnpm/node_modules` 等目录——**pnpm link 全局安装后这些目录可能不存在**。测试文件（位于独立 workspace）的 `require('@cptf/framework')` 解析失败，报：
-
-```
-Error: Cannot find module '@cptf/framework'
-```
-
-### 3.2 正确做法：workspace 本地 link
-
-`{workspaceDir}/package.json`：
-
-```json
-{
-  "name": "cptf-workspace",
-  "version": "1.0.0",
-  "private": true,
-  "description": "CPTF 测试工程: <libName> RNOH 功能测试",
-  "dependencies": {
-    "@cptf/framework": "link:<frameworkPath 绝对路径>",
-    "reflect-metadata": "link:<frameworkPath>/node_modules/reflect-metadata"
-  }
-}
-```
-
-> `reflect-metadata` 是 `@Step`/`@Test` 装饰器的运行时依赖，必须与框架内版本一致，故同样 link 框架 node_modules 内的副本。
-
-```bash
-cd {workspaceDir}
-pnpm install
-# 验证
-node -e "console.log(require.resolve('@cptf/framework'))"
-# 应输出 {workspaceDir}/node_modules/@cptf/framework/...
-```
-
-### 3.3 TS 支持
-
-框架 CLI 内置 `registerTsNode()`（ts-node transpileOnly，module: commonjs，target: ES2020，esModuleInterop），测试文件直接写 `.ts`，无需本地配置 tsconfig。
-
-## 4. 用例发现机制
-
-- CLI 扫描 `{casesDir}` 下所有 `.ts` 文件
-- 文件必须 `export const testCaseExecutor = new XxxTest()`（实例化 FunctionalTest 子类）
-- `@Test({ id: '...' })` 的 id 用于 `-t` 过滤：`cptf run -p harmony -t <id>`
-
-## 5. 常见搭建故障
-
-| 现象 | 原因 | 修复 |
-|------|------|------|
-| `Cannot find module '@cptf/framework'` | shim NODE_PATH 失效 | 按 3.2 本地 link |
-| `Cannot find module 'reflect-metadata'` | 漏配 reflect-metadata link | 补 package.json 第二个 link 依赖 |
-| 装饰器不生效（@Step 未注册） | 未 import 'reflect-metadata'（文件首行） | 测试文件第一行加 import |
-| 设备连接失败 | hdc 未授权/未插 | `hdc list targets` 检查，重新授权 |
-| hap 安装失败 | appPath 非绝对路径/未签名 | 核对 entry-default-signed.hap |
+# CPTF 测试工程搭建指南
+
+> Phase 2 的详细操作手册。核心解决两个问题：模块解析（link 依赖）与设备/应用配置。
+
+## 1. 前置检查
+
+```bash
+# 1. CPTF 框架源码位置（全局 pnpm link 安装）
+ls -la ~/Library/pnpm/global/5/node_modules/@cptf/framework   # 应为 symlink → 框架源码
+
+# 2. hdc 工具与设备
+hdc list targets    # 应输出设备 SN（如 026PMV25CH125405）
+
+# 3. demo hap 构建产物
+ls {demoPath}/harmony/entry/build/default/outputs/default/entry-default-signed.hap
+
+# 4. demo bundleId
+cat {demoPath}/AppScope/app.json5 | grep bundleName
+```
+
+## 2. cptf.config.json 完整配置
+
+```json
+{
+  "bundleId": "com.example.xxx",
+  "reportDir": "test-reports",
+  "reportFormat": "html",
+  "casesDir": "tests/cases",
+  "enableAlerts": true,
+  "platforms": {
+    "harmony": {
+      "toolPath": "hdc",
+      "bundleId": "com.example.xxx",
+      "appPath": "<demoPath 绝对路径>/harmony/entry/build/default/outputs/default/entry-default-signed.hap",
+      "devices": [
+        {
+          "id": "<设备SN>",
+          "screenWidth": 1280,
+          "screenHeight": 2832
+        }
+      ]
+    }
+  }
+}
+```
+
+**字段说明**：
+- `appPath` 必须是**绝对路径**（signed hap）
+- `screenWidth/screenHeight` 影响滚动与坐标计算，从 `hdc shell hidumper -s RenderService` 或设备规格获取
+- `casesDir` 相对 workspace 根；测试文件放 `tests/cases/functional/` 下自动被发现
+
+## 3. link 依赖建立（关键步骤）
+
+### 3.1 为什么不能用全局安装直接跑
+
+cptf CLI shim（`~/.pnpm/global/5/.bin/cptf`）通过 NODE_PATH 注入模块路径，其中包含 `.pnpm/node_modules` 等目录——**pnpm link 全局安装后这些目录可能不存在**。测试文件（位于独立 workspace）的 `require('@cptf/framework')` 解析失败，报：
+
+```
+Error: Cannot find module '@cptf/framework'
+```
+
+### 3.2 正确做法：workspace 本地 link
+
+`{workspaceDir}/package.json`：
+
+```json
+{
+  "name": "cptf-workspace",
+  "version": "1.0.0",
+  "private": true,
+  "description": "CPTF 测试工程: <libName> RNOH 功能测试",
+  "dependencies": {
+    "@cptf/framework": "link:<frameworkPath 绝对路径>",
+    "reflect-metadata": "link:<frameworkPath>/node_modules/reflect-metadata"
+  }
+}
+```
+
+> `reflect-metadata` 是 `@Step`/`@Test` 装饰器的运行时依赖，必须与框架内版本一致，故同样 link 框架 node_modules 内的副本。
+
+```bash
+cd {workspaceDir}
+pnpm install
+# 验证
+node -e "console.log(require.resolve('@cptf/framework'))"
+# 应输出 {workspaceDir}/node_modules/@cptf/framework/...
+```
+
+### 3.3 TS 支持
+
+框架 CLI 内置 `registerTsNode()`（ts-node transpileOnly，module: commonjs，target: ES2020，esModuleInterop），测试文件直接写 `.ts`，无需本地配置 tsconfig。
+
+## 4. 用例发现机制
+
+- CLI 扫描 `{casesDir}` 下所有 `.ts` 文件
+- 文件必须 `export const testCaseExecutor = new XxxTest()`（实例化 FunctionalTest 子类）
+- `@Test({ id: '...' })` 的 id 用于 `-t` 过滤：`cptf run -p harmony -t <id>`
+
+## 5. 常见搭建故障
+
+| 现象 | 原因 | 修复 |
+|------|------|------|
+| `Cannot find module '@cptf/framework'` | shim NODE_PATH 失效 | 按 3.2 本地 link |
+| `Cannot find module 'reflect-metadata'` | 漏配 reflect-metadata link | 补 package.json 第二个 link 依赖 |
+| 装饰器不生效（@Step 未注册） | 未 import 'reflect-metadata'（文件首行） | 测试文件第一行加 import |
+| 设备连接失败 | hdc 未授权/未插 | `hdc list targets` 检查，重新授权 |
+| hap 安装失败 | appPath 非绝对路径/未签名 | 核对 entry-default-signed.hap |