NavisworksTransport/doc/working/2026-08-02-integration-test-coverage-plan.md

集成测试覆盖补充计划

跟踪文档：记录集成测试的覆盖现状与待补充测试，后续按此文档跟踪完成情况。 状态：- [ ] 待办 · - [x] 完成（勾选时注明日期与提交）

---

1. 背景

• 集成测试框架：MSTest + NavisworksTestAutomationClient（HTTP 127.0.0.1:18777 ↔ 插件内 TestAutomationHttpService，请求经 UI 线程走真实业务链路）
• 运行方式：
  • 部署+启动：./build-and-deploy.bat → ./start-navisworks.bat（默认模型 Floor2_mobile_yup.nwd，英尺单位）
  • 集成测试：vstest NavisworksTransport.UnitTests.dll /TestCaseFilter:"TestCategory=NavisworksIntegration"（单测已排除此分类）
• 依赖：标准测试路径由插件自动导入（resources/auto-test-routes.xml → EnsureAutoTestRoutesImported）

2. 现有覆盖（已完成 ✅）

测试	文件	覆盖点
Ground/Hoisting/Rail 虚拟物体碰撞	VirtualCollisionAutomationTests.cs	虚拟物体 + 三类路径完整动画/碰撞流程（断言 Finished、检测记录 ID、报告存在）
Ground 自动路径规划	AutoPathGridGenerationAutomationTests.cs	AutoPlanPath + 网格验证（默认参数/Shortest/畅通场景）
JSON/XML 路径导入	PathImportValidityAutomationTests.cs	导入 → Rail 属性映射 → 长度计算（文档单位换算）→ 切换 → 动画可用性

3. 待补充测试

P0 高风险区（AGENTS.md 标注高风险：真实物体姿态链 / 动画逐帧状态）

• T01 真实物体 Ground 动画与姿态（2026-08-04，RealObjectAnimationAutomationTests）
  • 验证：select-animated-object 选真实物体 → 生成动画 → 断言物体实际位置/姿态（fragment 代表姿态、平面姿态链）
  • 实现：run-virtual-collision-test?useVirtualObject=false&animatedObjectPath=0/0/660/0（42" Diameter）
• T02 真实物体 Hoisting 动画与姿态（2026-08-04，RealObjectAnimationAutomationTests）
  • 验证：真实物体吊装路径动画（起吊/平移/下降三段姿态）
  • 实现：animatedObjectPath=0/0/769/0（25" x 25"，Hoisting 路径上）
• T03 真实物体 Rail 动画与姿态（2026-08-04，RealObjectAnimationAutomationTests）
  • 验证：真实物体空轨路径（canonical → rail pose 链、角度修正不污染 0° 基线）
  • 实现：animatedObjectPath=0/0/660/0（42" Diameter）
• T04 动画逐帧状态验证（2026-08-04，AnimationFrameProbeAutomationTests）
  • 验证：动画中途/结束时物体位置沿路径移动（起点=路径起点、逐帧插值、终点=路径终点）；Ground 平面链 yaw 正确
  • 实现：probe-animation-frames 端点（生成动画后 SeekToProgress 取跟踪位置）；Ground 起点/终点 XZ 匹配 + 高度恒定，Hoisting 吊装剖面（起吊→悬挂→下降）+ 水平平移

P1 功能面缺失

• T05 Free 自由路径动画（2026-08-04，FreePathAutomationTests）— 第 4 类路径完整流程 + 逐帧位置精确匹配路径点（物体中心=路径点，XYZ 全匹配）
• T06 碰撞结果内容验证（2026-08-04，CollisionReportAssertions）— 报告结构/路径关联/数据一致性断言，接入虚拟+真实物体测试
• T07 自动路径障碍绕行 — 构造起终点之间有障碍物的场景，断言规划路径成功绕行（blockedSampleCount==0 且路径非直线）
• T08 自动路径多策略 — run-auto-path strategy 参数（Shortest/Straightest）对比：路径长度/转弯数差异断言
• T09 网格诊断断言 — route-grid-diagnostics 端点：网格参数（cellSize、origin）、路径点所在网格可通行性
• T10 路径持久化/检测记录 — 检测记录 ID 从数据库重新加载断言（CollisionReports/DetectionRecords 表存在）

P2 需新增服务端端点

• T11 路径编辑 — 增删路径点、更新点位置（RemovePathPoint/UpdatePathPointWithConstraints/UpdatePointPosition）、正交化、去矩形环
• T12 路径导出 — ExportPath（XML/JSON 导出 → 再导入回环验证）
• T13 动画播放控制 — Pause/Resume/Stop/Reset 中途控制（当前只测自动跑完）
• T14 批量任务队列 — AddToBatchQueue 批量执行（BatchQueueManager）
• T15 路径分析 — PathAnalysisService（效率/安全评分）与 TimeLiner 集成

4. 测试服务支撑能力

端点	状态	用途
ping / status / routes / selection	✅	健康检查、状态、路径列表、选择集
select-route / select-default-route	✅	切换路径（自动测试_ 前缀自动导入）
select-animated-object	✅ 已实现	真实物体选择（T01-T03 已用）
list-model-items	✅ 已实现	枚举模型物体（DisplayName/PathId/包围盒中心/祖先链，动态解析真实物体）
run-virtual-collision-test / run-ground-collision-test	✅	虚拟/真实物体碰撞流程（useVirtualObject=false + animatedObjectPath + frameRate/durationSeconds 加速）
probe-animation-frames	✅	动画逐帧位置/yaw 探针（T04，SeekToProgress）
route-grid-diagnostics	✅ 已实现未用	网格诊断（T09 用）
export-debug-snapshot	✅ 已实现	动画调试快照（trackedState/boundingBox）
probe-animation-frames	✅ 已实现	动画逐帧位置/yaw 探针（T04 已用，SeekToProgress）
import-route-file	✅	路径导入验证
路径编辑 / 导出 / 播放控制 / 批量任务	❌ 需新增	T11-T15

5. 完成记录

日期	提交	完成项
2026-08-02	43df07c	集成测试标准路径自动导入机制（前置基础）
2026-08-02	c9c29c7	路径导入验证迁入集成测试（PathImportValidity）
2026-08-02	5bdfa82	AGENTS.md 单位原则强化（测试断言按文档单位换算）
2026-08-04	b5cfcbf	T01-T03 真实物体动画（RealObjectAnimationAutomationTests，服务端支持 useVirtualObject=false + animatedObjectPath/InstanceGuid 校验）
2026-08-04	8f477c0	T04 动画逐帧状态验证（AnimationFrameProbeAutomationTests，probe-animation-frames 端点）
2026-08-04	待提交	T05/T06 + 基础修复（Free 路径、报告内容断言、真实物体动态解析、报告残留修复、测试串行锁、启动脚本 AutoSave 清理/文件关联、动画参数加速 15fps/5s→完整集 6min→59s）