Pre_Seg_Server/doc/09-test-plan.md

当前测试计划

本文档把 doc/07-current-requirements-freeze.md 中的冻结需求映射到测试。测试目标是覆盖当前真实行为和明确占位行为。

测试分层

层级	工具	覆盖范围
前端单元/组件	Vitest + Testing Library	API 封装、store、组件交互、Mock/UI-only 状态
后端路由	pytest + FastAPI TestClient	Auth、Projects、Templates、AI、Export、Media 的接口契约
静态契约	TypeScript / py_compile	类型和 Python 语法

覆盖矩阵

需求	测试文件	覆盖点
R1 登录与会话	src/components/Login.test.tsx, backend/tests/test_auth.py	成功登录、失败提示、后端 401
R2 项目管理	src/lib/api.test.ts, backend/tests/test_projects.py	前端字段映射、PATCH 更新、后端 CRUD、帧列表
R3 媒体上传与拆帧	backend/tests/test_media.py, backend/tests/test_tasks.py	扩展名校验、自动建项目、关联项目、创建异步任务、标准帧序列参数、帧时间戳/源帧号、任务序列元数据、worker 注册帧、取消任务、重试任务、取消后 worker 停止
R4 工作区与帧浏览	src/components/VideoWorkspace.test.tsx, src/components/FrameTimeline.test.tsx	加载帧、无帧触发解析、缩略图/range/左右方向键切帧、播放、按项目 FPS 显示当前/总时长
R5 工具栏	src/components/ToolsPalette.test.tsx, src/components/CanvasArea.test.tsx, src/store/useStore.test.ts	工具切换、AI 跳转、矩形/圆/线/点/多边形手工 mask 绘制、点工具在已有 mask 上落点、多边形 Enter/首节点闭合、polygon 顶点拖动/删除、整块 mask 删除、区域合并/去除、内含去除 hole 渲染、合并模式隐藏编辑手柄、撤销/重做历史栈
R6 AI 推理	src/lib/api.test.ts, src/components/CanvasArea.test.tsx, src/components/AISegmentation.test.tsx, src/components/VideoWorkspace.test.tsx, src/components/ModelStatusBadge.test.tsx, backend/tests/test_ai.py, backend/tests/test_sam3_engine.py	点/框/interactive/semantic 契约、SAM 2 框选后正负点细化同一候选 mask、SAM 2 视频传播、SAM 3 语义文本前端执行路径、SAM 3 工作区框选、SAM 3 video tracker 外部桥接、SAM 3 点交互不支持提示、空文本/空结果反馈、模型选择、GPU/SAM 状态、SAM 3 外部 worker 桥接、AI 参数 options、局部裁剪推理、背景过滤、状态徽标、坐标归一化、正负点 labels、polygons 转 path、后端 fake registry
R7 标注保存	src/components/VideoWorkspace.test.tsx, src/components/CanvasArea.test.tsx, src/lib/api.test.ts, backend/tests/test_ai.py	保存标注、加载回显、更新 dirty 标注、清空删除已保存标注、GT mask 多类别导入、seed point 回显/归一化、项目不存在、帧不存在
R8 模板库	src/components/TemplateRegistry.test.tsx, src/lib/api.test.ts, backend/tests/test_templates.py	前端模板加载/新建/编辑/删除、JSON 分类导入、mapping_rules 解包/打包、后端模板 CRUD
R9 本体检查面板	src/components/OntologyInspector.test.tsx, src/components/CanvasArea.test.tsx, src/store/useStore.test.ts	模板选择、分类展示、具体分类选择、Canvas 选区同步、点击分类给已选 mask 换标签、自定义分类本地添加
R10 Dashboard 与 WebSocket	src/lib/api.test.ts, src/lib/websocket.test.ts, src/components/Dashboard.test.tsx, backend/tests/test_dashboard.py, backend/tests/test_main.py, backend/tests/test_progress_events.py, backend/tests/test_tasks.py	后端概览接口、任务表驱动队列、任务取消/重试/详情、cancelled 事件、Redis 进度事件 payload/发布、地址推导、消息订阅、队列更新、heartbeat
R11 导出	src/components/VideoWorkspace.test.tsx, src/lib/api.test.ts, backend/tests/test_export.py	COCO/PNG 按钮下载、导出前自动保存、导出路径、JSON 结构、mask ZIP、zIndex 语义融合
R12 配置	src/lib/config.test.ts	env 优先、hostname 推导、WS 推导
R13 文档与测试	doc/09-test-plan.md	测试覆盖矩阵

逐功能点追踪

需求	功能点	对应测试	当前状态
R1	登录页、默认开发凭证、token 写入、失败提示、后端 401	Login.test.tsx, test_auth.py	已覆盖
R2	项目列表/创建/选择、视频导入、DICOM 导入、后端项目和帧 CRUD	ProjectLibrary.test.tsx, api.test.ts, test_projects.py	已覆盖
R3	文件类型校验、自动/指定项目上传、视频/DICOM 拆帧任务、parse_fps/max_frames/target_width、标准帧序列 metadata、任务查询、取消、重试、worker 取消停止	test_media.py, test_tasks.py	已覆盖
R4	工作区加载帧、无帧自动解析、Canvas 底图、缩略图/range/左右方向键切帧、播放、按 FPS 显示时间	VideoWorkspace.test.tsx, FrameTimeline.test.tsx, CanvasArea.test.tsx	已覆盖
R5	工具切换、AI 跳转、矩形/圆/线/点/多边形绘制、已有 mask 上继续绘制	ToolsPalette.test.tsx, CanvasArea.test.tsx	已覆盖
R5	顶点编辑、顶点删除、整块删除、撤销/重做、区域合并、区域去除、hole even-odd 渲染	CanvasArea.test.tsx, useStore.test.ts	已覆盖
R6	SAM 2 点/框/interactive、SAM 2 视频传播、SAM 3 semantic、SAM 3 box、SAM 3 video tracker、SAM 3 不支持点交互时的前端反馈、模型选择、GPU/模型状态、参数 options、polygons 转 mask	api.test.ts, CanvasArea.test.tsx, AISegmentation.test.tsx, VideoWorkspace.test.tsx, ModelStatusBadge.test.tsx, test_ai.py, test_sam3_engine.py	已覆盖
R7	保存、查询、更新、删除标注、工作区回显、清空已保存标注、GT mask 导入和 seed point 回写	VideoWorkspace.test.tsx, CanvasArea.test.tsx, api.test.ts, test_ai.py	已覆盖
R8	模板加载、新建、编辑、删除、JSON 分类导入、mapping_rules 映射、后端 CRUD	TemplateRegistry.test.tsx, api.test.ts, test_templates.py	已覆盖
R9	模板选择、分类展示、分类选择、已选 mask 换标签、自定义本地分类、占位状态	OntologyInspector.test.tsx, CanvasArea.test.tsx, useStore.test.ts	已覆盖
R10	Dashboard 概览、队列、活动日志、WebSocket progress/complete/error/status/cancelled、取消/重试/详情、heartbeat	Dashboard.test.tsx, websocket.test.ts, test_dashboard.py, test_main.py, test_progress_events.py, test_tasks.py	已覆盖
R11	COCO/PNG ZIP 导出、导出前保存、路径和 JSON/ZIP 结构、zIndex 融合	VideoWorkspace.test.tsx, api.test.ts, test_export.py	已覆盖
R12	API/WS 地址 env 优先和 hostname 推导	config.test.ts	已覆盖
R13	文档测试矩阵与功能点追踪	doc/09-test-plan.md	已覆盖

本轮补齐记录

• R5：补充 CanvasArea.test.tsx 中圆形和线段手工绘制测试，明确验证 metadata、segmentation、bbox/area 和草稿状态。
• R6：补充 AISegmentation.test.tsx 中 SAM 3 semantic 文本推理测试，验证前端传参和返回 mask 绑定当前语义类别。
• R6：补充 SAM 3 空文本、空结果和工作区点交互不支持提示测试，避免前端静默失败。
• R6：补充 SAM 3 工作区 box prompt 测试和外部 worker box prompt 测试，验证官方 add_geometric_prompt() 正框链路。
• R6：补充 POST /api/ai/propagate 后端测试，验证 seed mask 传播结果会保存为后续帧标注并保留 class 元数据。
• R6：补充 propagateMasks() API 封装和 VideoWorkspace 传播按钮测试，验证当前选中区域会发送到后端视频传播接口。
• R6：补充 SAM 3 external video tracker 请求测试，验证主后端会把帧目录、源帧索引、seed bbox 和方向传给独立 Python helper。
• R3：补充 parseMedia() 查询参数和后端拆帧任务 payload 测试，验证 parse_fps、max_frames、target_width 会进入任务。
• R3：补充 worker 注册标准帧序列测试，验证帧 timestamp_ms、source_frame_number 和 result.frame_sequence 元数据。
• R8：补充 TemplateRegistry.test.tsx 中模板编辑、删除测试，验证前端调用真实 API 封装并更新全局 store。
• R9：补充 Canvas 选中 mask id 全局同步、本体树点击分类给已选 mask 换标签的测试，验证已保存 mask 会进入 dirty 状态。

运行命令

npm run test
npm run test:run
npm run lint
npm run build

pip install -r backend/requirements-dev.txt
pytest backend/tests
python -m py_compile backend/routers/ai.py backend/routers/templates.py backend/schemas.py

当前不做的测试

• 不启动真实 PostgreSQL、MinIO、Redis 或 SAM 模型。
• 不做真实视频大文件拆帧性能测试。
• 不用浏览器 E2E 验证视觉细节。
• 不把当前明确 Mock/UI-only 的按钮当成真实业务成功路径测试。