# 02 程序测试开发完善详细步骤

生成日期：2026-06-27

## 1. 环境准备

工作目录：

```bash
cd /home/mes123456/cnc_wams
```

基础要求：

- Node/npm 可用。
- Chrome/Chromium 可用，浏览器 smoke 会自动查找 `chromium`、`chromium-browser`、`google-chrome` 或 `google-chrome-stable`。
- 不需要真实 LinuxCNC 实时内核；测试目标是 Web 仿真和 WASM/source-derived 边界。

## 2. 手册正文抽取方法

操作手册是 docx。需要复核手册内容时，可临时转文本：

```bash
mkdir -p /tmp/cnc_wams_manual_extract
libreoffice --headless --convert-to txt:Text --outdir /tmp/cnc_wams_manual_extract \
  "/home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/docs/Web-RTCP五轴数控系统仿真界面操作手册.docx"
sed -n '1,260p' /tmp/cnc_wams_manual_extract/Web-RTCP五轴数控系统仿真界面操作手册.txt
```

抽取后按章节映射到 [04-任务矩阵.md](04-任务矩阵.md)，不要直接凭截图或文件名推断功能。

## 3. 基线验证命令

### 3.1 静态构建

```bash
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/app run build
```

通过标准：

- 退出码为 0。
- 输出包含 `gmoccapy_static_build=ok`。
- `app/dist/index.html` 和 `app/dist/src/main.js` 存在。

### 3.2 Node smoke

```bash
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/app run smoke:node
```

通过标准：

- 退出码为 0。
- 输出至少包含这些标记：
  - `linuxcnc_kinematics_runtime_smoke=ok`
  - `linuxcnc_interpreter_runtime_smoke=ok`
  - `linuxcnc_ini_runtime_smoke=ok`
  - `run_preconditions_ini_profile_smoke=ok`
  - `run_feedback_status_loop_smoke=ok`
  - `run_ready_sequence_smoke=ok`
  - `linuxcnc_task_hal_runtime_smoke=ok`
  - `full_linuxcnc_5axis_source_node_smoke=ok`
  - `machine_file_staging_smoke=ok`
  - `five_axis_session_smoke=ok`
  - `rtcp_store_smoke=ok`
  - `gmoccapy_xyzab_profile_smoke=ok`
  - `gmoccapy_hal_model_smoke=ok`
  - `gmoccapy_xyzab_gates_smoke=ok`
  - `linear_unit_conversion_smoke=ok`

### 3.3 浏览器 smoke

```bash
npm --prefix /home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/app run smoke
```

通过标准：

- 退出码为 0。
- 输出包含 `gmoccapy_shell_smoke=ok` 和 `gmoccapy_dist_smoke=ok`。
- 若失败，先记录 Chrome 路径、缺失浏览器、canvas/WebGL、端口启动或 DOM 断言失败原因，不直接改业务代码。

### 3.4 working7 手册流程专项证据

```bash
npm --prefix /home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test run evidence:working7
```

通过标准：

- 退出码为 0。
- 输出 `working7_manual_flow_status=PASS`。
- 生成 JSON、PDF 和截图目录：
  - `/home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test/output/working7-manual-flow-evidence-report.json`
  - `/home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test/output/working7-manual-flow-evidence-report.pdf`
  - `/home/mes123456/cnc_wams/qa/web-rtcp-5axis-site-test/output/working7-manual-flow-evidence`
- 报告检查项覆盖主界面/canvas、POWER/HOME、AUTO/MANUAL、MANUAL JOG、MDI 提交、倍率/HAL 输入、主轴/冷却、Save/Restore 和诊断。

## 4. 按手册执行的人工测试方法

人工测试用于补充截图、PDF 或问题复现证据。建议用本地静态服务打开 app：

```bash
cd /home/mes123456/cnc_wams/web-rtcp-5axis-sim-plan/app
npm run dev
```

默认地址为：

```text
http://127.0.0.1:4173
```

若端口占用，换空闲端口启动等价静态服务，并在 [05-验收证据.md](05-验收证据.md) 记录实际 URL。

### 4.1 主界面区域

操作：

1. 打开页面，等待 `[data-shell="gmoccapy-5axis"]` 出现。
2. 检查这些区域：`titlebar`、`preview`、`dro`、`gcode`、`status-sidebar`、`info-tabs`、`override`、`spindle-coolant`、`bottom-controls`。
3. 检查 canvas 的 dataset：`threeReady=true`、`threeFrameApi=web-rtcp-5axis-motion-frame`、`threeSceneMode=program-preview-and-tool-execution`。

验收：

- 9 个区域存在。
- 预览非空，canvas ready。
- `window.webRtcp5AxisSimulation.getState()` 可读取状态。

### 4.2 开机、回零和模式切换

操作：

1. 首屏确认 MANUAL 默认 active，POWER 未开启。
2. 点击 POWER。
3. 点击 Home。
4. 点击 AUTO。
5. 点击 MANUAL。

验收：

- POWER 后 `machine.powerOn=true`。
- Home 后 `machine.allHomed=true`。
- AUTO 后 `machine.mode=auto`，右侧 AUTO 为绿色、MANUAL 为灰色。
- MANUAL 后 `machine.mode=manual`，右侧 MANUAL 为绿色、AUTO 为灰色。
- 未满足条件时按钮 title 或 Operator 信息说明 gate 原因。

### 4.3 AUTO 自动运行

操作：

1. 选择 `xyzac-trt` 或 `xyzbc-trt`。
2. 选择 LinuxCNC 5-axis source 程序。
3. 点击 Run Ready。
4. 点击 Run，等待当前 G-code 行推进。
5. 分别测试 Pause、Resume、Step、Stop。

验收：

- Run Ready 后 `powerOn=true`、`allHomed=true`、`mode=auto`。
- Run 后 `programExecutionSourceMode=linuxcnc-task-motion-hal-wasm` 或对应 source-derived runtime。
- 当前 G-code 行绿色高亮，已执行行变灰。
- Stop 后 `runState` 为 `stopped`、`complete` 或 `idle`，`machine.interpState=idle`。

### 4.4 MANUAL 点动

操作：

1. POWER + Home 后点击 MANUAL。
2. 点击 JOG 或直接点击 X+/X-/Y+/Y-。
3. 记录点动前后 DRO 和 `axisPose`。

验收：

- 仅在 manual + idle + power on 条件下允许点动。
- 对应轴坐标发生变化。
- 被阻止时提示 power、mode 或 interpreter 非 idle 的原因。

### 4.5 MDI

操作：

1. POWER + Home 后点击 MDI。
2. 在 MDI 输入框输入：`G90 X12.5 Y-4 Z1.25 F900`。
3. 点击 MDI 区 Run 或底部 MDI。
4. 读取 DRO、`axisPose` 和 MDI 历史。

验收：

- `machine.mode=mdi`。
- 执行后目标坐标被写入或按 profile 限位夹紧。
- MDI 历史出现刚执行命令。

### 4.6 RTCP、IDENTITY 和 TCP

操作：

1. 在 `xyzac-trt` 或 `xyzbc-trt` profile 下切换 IDENTITY/TCP。
2. 运行包含 M428/M429 的 LinuxCNC source 程序。
3. 切换到 `gmoccapy-xyzab`，检查 TCP 按钮禁用原因。

验收：

- TCP profile 下 RTCP badge 可显示 on，DRO 中 TCP 坐标和刀轴向量更新。
- M428/M429 可驱动 `kinsType` 和 RTCP 状态变化。
- `gmoccapy-xyzab` 因 reference-only/trivkins 不允许 TCP proof。

### 4.7 倍率、主轴、冷却和 HAL 输入

操作：

1. 测试 Rapid Override 的 +、-、100。
2. 测试 Feed Rate 的 +、-、100。
3. 测试 Limits、Block、M1。
4. 上电后测试 Flood、Mist、FWD、STOP、REV 和主轴倍率。

验收：

- 倍率值按按钮变化，100 可恢复默认。
- HAL 输入同步到 `gmoccapyGui` 或对应诊断状态。
- 未上电时主轴/冷却被阻止，上电后可切换。

### 4.8 程序来源、Stage、Reload、Save/Restore

操作：

1. 使用 Open 加载本地 `.ngc` 程序。
2. 使用 LinuxCNC 5-axis source 选择内置程序。
3. 点击 Stage 刷新 machine files。
4. 点击 Reload。
5. 点击 Save Session，改变 profile/坐标/模式后点击 Restore Session。

验收：

- 程序来源和当前文件名可见。
- Stage 状态为 staged，并能看到 machine-file 数量。
- Reload 后运行状态复位。
- Restore 后恢复保存时的 profile、坐标、模式、程序和 RTCP 状态。
- 若 OPFS 不可用，显示 memory-fallback 且行为可解释。

### 4.9 诊断信息

操作：

1. 逐个查看 Task policy、INI、Task/HAL、Full boundary、gmoccapy/HAL 信息。
2. 对照当前 profile 和运行状态读取诊断内容。

验收：

- Task policy 显示 gate、task state、task mode、interp state 和可执行命令。
- INI 显示坐标、关节、限位和 kinematics。
- Task/HAL 显示 runtime readiness、cycle、HAL sync 和 runtime feedback。
- Full boundary 能说明是否满足完整 LinuxCNC 程序执行边界。
- gmoccapy/HAL 能区分 native NML/HAL 参考和 Web store/runtime 映射。

## 5. 新增自动化脚本规则

后续需要把人工步骤固化为自动化时，按以下位置扩展：

| 类型 | 位置 | 规则 |
| --- | --- | --- |
| Node 单元/集成 | `web-rtcp-5axis-sim-plan/tests/node` | 优先验证 store、runtime、policy、session、profile 边界，不依赖 DOM。 |
| 浏览器 smoke | `web-rtcp-5axis-sim-plan/tests/browser` | 验证 DOM、颜色、canvas、按钮、public API 和 dist 页面。 |
| QA 截图/PDF | `qa/web-rtcp-5axis-site-test` | 生成 job_id、report_id、JSON、PDF、截图，写入 `output`。 |

新增脚本后必须：

- 更新 `app/package.json` 中对应 smoke 命令或新增明确命令。
- 在 [04-任务矩阵.md](04-任务矩阵.md) 更新任务状态。
- 在 [05-验收证据.md](05-验收证据.md) 记录命令、输出、路径和报告编号。

## 6. 异常处理

| 异常 | 处理 |
| --- | --- |
| 浏览器 smoke 找不到 Chromium | 安装或设置 `CHROMIUM=/path/to/browser`，记录路径。 |
| canvas/WebGL 失败 | 记录 `canvas.dataset`、Chrome 参数和 fallback 原因。 |
| AUTO 不变绿 | 检查 `SET_MODE` 是否保留 machine state，检查 power/home/interp idle gate。 |
| RUN blocked | 读取 button title、Operator 信息和 Task policy 诊断，不直接绕过 gate。 |
| Save Session memory-fallback | 判断是否 HTTPS/OPFS 安全上下文问题，memory fallback 可作为测试环境可接受状态。 |
| `gmoccapy-xyzab` TCP 禁用 | 这是预期边界，不按缺陷处理。 |