cnc_wams/work/working7/02-程序测试开发完善详细步骤.md

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

生成日期：2026-06-27

1. 环境准备

工作目录：

cd /home/meswork/cnc_wams

基础要求：

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

2. 手册正文抽取方法

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

mkdir -p /tmp/cnc_wams_manual_extract
libreoffice --headless --convert-to txt:Text --outdir /tmp/cnc_wams_manual_extract \
  "/home/meswork/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，不要直接凭截图或文件名推断功能。

3. 基线验证命令

3.1 静态构建

npm --prefix /home/meswork/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

npm --prefix /home/meswork/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

npm --prefix /home/meswork/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 手册流程专项证据

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

通过标准：

• 退出码为 0。
• 输出 working7_manual_flow_status=PASS。
• 生成 JSON、PDF 和截图目录：
  • /home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/working7-manual-flow-evidence-report.json
  • /home/meswork/cnc_wams/qa/web-rtcp-5axis-site-test/output/working7-manual-flow-evidence-report.pdf
  • /home/meswork/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：

cd /home/meswork/cnc_wams/web-rtcp-5axis-sim-plan/app
npm run dev

默认地址为：

http://127.0.0.1:4173

若端口占用，换空闲端口启动等价静态服务，并在 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 更新任务状态。
• 在 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 禁用	这是预期边界，不按缺陷处理。