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 自动路径障碍绕行（2026-08-04，AutoPathObstacleDetourAutomationTests）— 构造跨越大半模型的起终点（直线 11.0m），断言规划路径 blocked=0 且长度 11.57m > 直线距离（成功绕行）
• T08 自动路径多策略（2026-08-04，同测试类）— Shortest/Straightest 策略参数回传正确 + 均规划出有效路径
• T09 网格诊断断言（2026-08-04，RouteGridDiagnosticsAutomationTests）— 网格参数/路径点覆盖/段数量一致性（可通行性为诊断信息不作硬断言）
• T10 路径持久化/检测记录（2026-08-04，DetectionRecordPersistenceAutomationTests）— 检测记录从数据库重载：关联路径、动画参数（15fps/5s）、虚拟物体模式一致

P2 需新增服务端端点

• T11 路径编辑（2026-08-04，PathEditingAutomationTests）— 删除路径点/更新位置/正交化/去环（RemovePathPoint 仅处理 3D 标记，真删点走 PathRoute.RemovePoint）
• T12 路径导出（2026-08-04，ExportImportRoundTripAutomationTests）— XML/JSON 导出→导入回环属性一致
• T13 动画播放控制（2026-08-04，AnimationPlaybackControlAutomationTests）— prepare→start→pause 验证→resume→finished
• T14 批量任务队列（2026-08-04，BatchQueueAutomationTests）— 队列添加/计数递增（轻量版，不执行批量动画）
• T15 路径分析（2026-08-04，PathAnalysisAutomationTests）— 评分结构验证；顺带修复产品 bug（CollisionResults 表已废弃导致路径分析 no such table）

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）
detection-record	✅ 已实现	检测记录持久化查询（T10）
run-auto-path / analyze-auto-path-grid / route-grid-diagnostics	✅	自动路径（strategy）+ 网格诊断（T07/T08/T09）
export-debug-snapshot	✅ 已实现	动画调试快照（trackedState/boundingBox）
import-route-file	✅	路径导入验证
export-route-file	✅ 已实现	路径导出（T12）
edit-route	✅ 已实现	路径编辑 remove-point/update-point/orthogonalize/remove-loops（T11）
animation-playback-control	✅ 已实现	播放控制序列（T13）
batch-queue-add	✅ 已实现	批量队列添加（T14）
analyze-path	✅ 已实现	路径分析评分（T15）
其余待扩展	—	批量执行、TimeLiner 集成等后续迭代补充

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	44214ba	T05/T06 + 基础修复（Free 路径、报告断言、动态解析、串行锁、脚本、加速 15fps/5s）
2026-08-04	待提交	T07-T10（障碍绕行、多策略、网格诊断、持久化）+ GetDetectionRecordById + detection-record 端点；P0+P1 完成，18/18
2026-08-04	待提交	T11-T15（路径编辑/导出/播放控制/批量队列/路径分析）+ 服务端 5 端点 + 产品 bug 修复（PathDatabase CollisionResults→CollisionReports、RemovePoint 链路）；P0+P1+P2 全部完成，集成测试 24/24，完整集 74.6s