open-design/docs/testing/html-preview-coverage-summary.zh-CN.md

HTML 生成与预览覆盖矩阵（含 Express 路由回归缺口）

结论

当前仓库并不是“完全没有”覆盖项目内生成 HTML 文件和 HTML 预览，而是：

• 已经有 daemon 单测、web 组件测试、Playwright E2E 三层覆盖；
• 但历史上没有把“真实 daemon + raw HTML 路由 + iframe 成功渲染”这条链路固定成足够强的硬门禁；
• 因此像 Express 4 -> 5 这种会影响通配路由、req.params、静态/raw 文件服务的底层升级，可能会绕过大量邻近测试，最终表现为“HTML 黑屏”。

相关 bad case

• PR #2311 chore(deps): upgrade express 4 -> 5 in daemon
• 用户反馈的问题形态：项目内生成的 HTML 文件无法正常渲染，预览黑屏。

这类问题的危险点在于：

1. 文件可能已经成功生成；
2. 前端 iframe 也可能已经挂载；
3. 但 iframe 请求的 /api/projects/:id/raw/*.html 路由在 Express 升级后失配、取不到内容、或返回错误响应；
4. 最终用户看到的是“黑屏”，而不是明显的接口 404 提示。

现有覆盖

1. 项目内生成 HTML 文件

E2E / 集成

• /Users/mac/open-design/open-design-home-entry/e2e/ui/real-daemon-run.test.ts

  • 真实 run 生成 .html 文件
  • 文件落盘
  • 预览 iframe 可见
  • iframe 内 heading/text 可见
  • follow-up turn 再生成 HTML
  • 失败态不留脏文件

• /Users/mac/open-design/open-design-home-entry/e2e/tests/dialog/artifact-consistency.test.ts

  • run 状态、assistant message、持久化文件、artifactManifest.renderer='html'、原始 HTML 内容一致性

daemon 单测

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/run-artifacts.test.ts

  • HTML artifact 识别、计数、成功/失败归因

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/artifact-create.test.ts

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/artifacts-cli.test.ts

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/mcp-create-artifact.test.ts

  • daemon / CLI / MCP 创建 artifact 路径

2. HTML 文件预览

web 组件测试

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/file-viewer-render-mode.test.ts

  • HTML 预览走 url-load 还是 srcdoc
  • deck / comment / edit / inspect / draw / tweaks / forceInline 等模式分流

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/PreviewModal.test.tsx

  • preview modal sandbox
  • deck srcdoc 处理

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/preview-modal-unavailable-state.test.tsx

  • 无 HTML 预览的占位状态

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/preview-modal-error-state.test.tsx

  • 预览加载错误态

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/FileViewer.test.tsx

  • URL-load iframe
  • srcdoc transport reactivation
  • 切 tab/切 source/切 view 后的 iframe 行为
  • deck / bridge / download / render-mode 相关细节

E2E / 页面恢复

• /Users/mac/open-design/open-design-home-entry/e2e/ui/app-restoration.test.ts

  • artifact tab 恢复
  • deep link 到 .html
  • 返回项目根后预览继续保持
  • later run 覆盖最新 artifact 预览
  • failed send 后 retry 恢复预览

• /Users/mac/open-design/open-design-home-entry/e2e/ui/app-design-files.test.ts

  • HTML / image / source 文件预览路径
  • image-preview.html 渲染图片资源

• /Users/mac/open-design/open-design-home-entry/e2e/ui/app-manual-edit.test.ts

  • HTML 预览 iframe 下的手动编辑与预览联动

3. raw HTML 路由与 iframe 特殊头

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/origin-validation.test.ts

  • Origin: null 的 raw-file 预览路由访问

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/server-cors.test.ts

  • srcdoc iframe 相关 CORS 头

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/plugins-preview-route.test.ts

  • HTML preview route 包裹/重写逻辑

为什么历史上没拦住 Express 4 -> 5 的黑屏

1. 当时主要验证的是 daemon 包级测试和视觉回归

在 PR #2311 里，验证重心是：

• pnpm --filter @open-design/daemon test
• pnpm guard
• pnpm typecheck

这些能抓到很多类型和路由注册问题，但不等于覆盖“真实生成后的 HTML 在浏览器 iframe 里是否成功渲染”。

2. 很多测试只覆盖了前端预览行为，不一定穿过 Express 通配路由坏路径

例如：

• FileViewer / PreviewModal / render-mode 测试

主要验证：

• 该走 url-load 还是 srcdoc
• iframe sandbox / bridge / mode 切换

但它们未必真的依赖 Express 5 下的：

• /api/projects/:id/raw/*splat
• req.params.splat
• 实际 HTML 内容读取和返回

3. 真实坏点在后端路由层，而 UI 可能还“看起来正常”

Express 5 的典型风险点：

• /* 需要改成 /*splat
• req.params[0] 要改成 req.params.splat
• wildcard 参数变成 string | string[]

如果这里改漏：

• HTML 文件仍可能成功写入项目目录；
• iframe 仍然被前端渲染出来；
• 但 iframe 请求的 raw HTML 路由失效，结果就是黑屏。

这类问题如果测试只断言：

• 有 iframe
• 有 artifact tab
• 有文件记录

就拦不住。

当前最能拦住这类事故的测试

如果把“Express 升级导致 HTML 黑屏”当成一个必须阻止的回归，现在最关键的是这几条：

P0

• /Users/mac/open-design/open-design-home-entry/e2e/ui/real-daemon-run.test.ts

  • 真 run 生成 HTML
  • iframe 内看到 heading/text

• /Users/mac/open-design/open-design-home-entry/e2e/tests/dialog/artifact-consistency.test.ts

  • 文件、manifest、assistant message、raw HTML 一致

• /Users/mac/open-design/open-design-home-entry/apps/daemon/tests/origin-validation.test.ts

  • raw HTML 路由在 iframe 场景下仍然可用

P1

• /Users/mac/open-design/open-design-home-entry/e2e/ui/app-restoration.test.ts

  • HTML 预览恢复、deep link、artifact tab 回放

• /Users/mac/open-design/open-design-home-entry/apps/web/tests/components/FileViewer.test.tsx

  • URL-load / srcdoc 路径的前端渲染决策

仍建议补的缺口

1. 更聚焦的 daemon raw-route 回归测试

建议新增一条更直白的 daemon 路由契约测试，专门锁：

• /api/projects/:id/raw/foo/bar/index.html
• 返回 200
• content-type 为 HTML
• body 内包含预期 HTML 内容
• Origin: null 下仍允许 iframe 访问

这样可以直接拦住：

• wildcard 没命中
• req.params.splat 拼接错误
• 读取 path 错误

2. E2E 明确断言“不是只有 iframe 可见，而是 iframe 内真的有内容”

所有关键 HTML 预览 E2E 都建议守住：

• page.getByTestId('artifact-preview-frame') 可见
• page.frameLocator('[data-testid="artifact-preview-frame"]').getByRole(...) 可见

而不是只看 iframe 容器存在。

3. 把 HTML 预览 smoke 放进更硬的 CI 档位

如果这类场景被视为高风险回归，建议：

• real-daemon-run 至少保留 1 条 HTML 生成 + 预览 smoke 作为阻塞 PR
• 不要只放在夜间或非阻塞套件里

建议的最小门禁集合

如果目标只是“以后别再让 Express / server 升级把 HTML 预览搞黑屏”，最小集合建议是：

1. e2e/ui/real-daemon-run.test.ts
   • 真实生成 HTML 后 iframe 内看到 heading
2. e2e/tests/dialog/artifact-consistency.test.ts
   • artifact 文件、manifest、消息、raw HTML 一致
3. 新增 daemon raw-route 契约测试
   • 明确锁 /api/projects/:id/raw/*splat

这 3 条合起来，比单纯靠视觉回归或组件测试更能直接拦住这类事故。