企业官网建设流程全解析

这一模式是"清理状态、测试独立"的实战范本：不依赖外部数据库或网络，用种子数据把每个用例固定在同一初始状态，从根上消除顺序依赖导致的 flaky。

5. Playwright 原理与配置实践

5.1 核心概念

5.2 配置推荐

Dillinger 仓库的 playwright.config.ts 与推荐值几乎逐条对应，可作标准配置模板：

export default defineConfig({ testDir: "./tests/e2e", fullyParallel: true, reporter: "list", timeout: 45_000, expect: { timeout: 5_000 }, use: { baseURL, trace: "on-first-retry", screenshot: "only-on-failure", video: "retain-on-failure", }, projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }], webServer: { command: `npx next dev -H 127.0.0.1 -p ${port}`, url: baseURL, reuseExistingServer: !process.env.CI, timeout: 180_000, }, });

要点解读：

• trace: "on-first-retry"：仅在重试时录制 trace，兼顾调试能力与性能开销，对应推荐值；video: "retain-on-failure"只在失败时保留视频，是 CI 排障的关键证据；
• fullyParallel: true：文件级并行，对应 SKILL 文档中"Per file 是 Playwright 默认并行策略"；
• webServer：自动启动next dev（监听127.0.0.1:3005）并等待就绪，reuseExistingServer: !process.env.CI在本地复用已启动的 dev server、在 CI 中强制全新启动——配置注释还记录了关键经验："使用 dev 模式，因为 production build 存在预先存在的预渲染错误"；
• timeout: 45_000/expect.timeout: 5_000：为慢速断言（如异步 Markdown 渲染）预留充足等待，对应"避免硬编码等待、使用自动等待"的原则。事实上 tests/e2e/editor.spec.ts 中针对异步预览渲染的断言特意放宽到{ timeout: 10_000 }。

6. 视觉测试

6.1 何时使用

6.2 策略

• Baseline screenshots（基线截图）
• Compare on changes（变更时对比）
• Review visual diffs（人工审阅视觉差异）
• Update intentional changes（确认有意变更后更新基线）

7. API 测试原则

7.1 覆盖维度

7.2 Dillinger 中的 API 测试实证

仓库在 tests/routes 下用 Vitest（@vitest-environment node）直接调用 Next.js 路由处理函数做纯 Node 环境测试，tests/routes/export-html.route.test.ts 是教科书式示例：

it("rejects missing markdown", async () => { const response = await exportHtml( new Request("http://localhost/api/export/html", { method: "POST", body: JSON.stringify({}), }) as never ); expect(response.status).toBe(400); }); it("renders styled and plain HTML variants with stable filenames", async () => { // styled: true → 响应体包含 <style> // styled: false → 响应体不含 <style> expect(styledResponse.headers.get("Content-Disposition")).toContain( 'filename="Exported.html"' ); expect(await styledResponse.text()).toContain("<style>"); expect(await plainResponse.text()).not.toContain("<style>"); });

该测试完整覆盖了状态码（缺参返回 400）、响应结构（HTML 是否含<style>样式块）、响应头（Content-Disposition文件名稳定性）三类维度，与 SKILL 文档中"状态码 + 响应结构 + 错误消息 + 边界情况"的 API 测试原则一一对应。同类测试还包括export-markdown、export-pdf、github.route、import-html-to-markdown、upload-image等路由。

8. 测试组织结构与命名约定

8.1 文件结构

SKILL 文档推荐的标准结构：

tests/ ├── e2e/ # 完整用户流程 ├── integration/ # API、数据 ├── component/ # UI 单元 └── fixtures/ # 共享数据

Dillinger 仓库的 tests 目录与之同构（integration 层以routes/目录呈现）：

tests/ ├── e2e/ # 完整用户流程（Playwright） ├── routes/ # API 路由测试（Vitest） ├── components/ # UI 单元测试 ├── hooks/ # 自定义 hooks 测试 ├── lib/ # 核心库测试（markdown、export、import 等） └── store/ # Zustand 状态管理测试

这种"E2E 只测关键路径、API 与单元测试铺底"的布局，正是金字塔模型的落地形态。

8.2 命名约定

Dillinger 的 E2E 文件命名两者兼取：smoke.spec.ts（功能型）、settings-sidebar.spec.ts（功能型）、import-export.spec.ts（功能型）；而测试用例名则全部采用描述性句式，如"switches between documents and updates the editor and preview"、"deletes a document after confirmation"、"hides word count when disabled in settings"（见 tests/e2e/editor.spec.ts），失败时可读性极佳。

9. CI 集成

9.1 流水线步骤

1. 安装依赖（Install dependencies）
2. 安装浏览器（Install browsers）
3. 运行测试（Run tests）
4. 上传产物（Upload artifacts：traces、screenshots）

9.2 并行化策略

Dillinger 的 playwright.config.ts 通过fullyParallel: true启用文件级并行；package.json的verify脚本把 lint → typecheck → 单元测试 → E2E 串成一条可放入 CI 的完整流水线。结合配置中的trace/screenshot/video三件套，CI 失败时能自动保留 trace、截图与视频作为可下载的诊断产物，与文档推荐的流水线第 4 步"上传 artifacts"完全吻合。

10. 反模式清单

在 Dillinger 仓库中可以找到每条反模式的正面对照：

• 测行为而非实现：smoke.spec.ts用getByRole断言"Toggle sidebar""Hide preview""Open settings"等用户可见交互，从不触碰组件内部状态；
• 自动等待替代硬编码：所有断言依赖 Playwright 内置 auto-wait，异步渲染场景通过显式timeout参数而非page.waitForTimeout处理；
• 清理与隔离：addInitScript种子注入 + "仅空 localStorage 才注入"的守卫，保证用例间互不污染；
• 修复根因：playwright.config.ts注释记录了对 dev/prod 模式差异的真实根因排查结论，而非简单绕开问题。

结语

Remember: E2E tests are expensive. Use them for critical paths only.

Dillinger 仓库把 SKILL 文档中的每一条原则都落成了可运行、可复现的代码：fullyParallel的并行配置、on-first-retry的 trace、addInitScript的确定性状态种子、getByRole的行为级断言，以及 Vitest 直调路由函数的 API 测试。无论你是要给 Dillinger 增加新的 E2E 用例（参考 tests/e2e 现有 spec 的模式），还是为下一个 Web 应用搭建测试体系（以 playwright.config.ts 为起点），这套"深度审计 → 金字塔分层 → 关键路径 E2E → 边界化 API 测试 → CI 产物留证"的流程都值得直接照搬。

• 前端
• 开发工具