测试

这套模板的测试目标是守住最容易改坏、也最影响用户信任的地方：配置、路由、权限边界、登录注册、支付入口、上传安全、共享包和公开页面。

项目当前有三层测试：

• Web / Package 单元测试：快速验证配置、路由、文案、API 边界和共享包逻辑。
• 浏览器 E2E：用 Playwright 打开真实页面，监听页面错误，验证公开流程、匿名保护边界和必要的登录态流程。
• 生产 smoke：先 build，再用生产 Node server 启动页面，确认生产产物、CSP、静态资源、健康检查和登录路由都能工作。

推荐测试流程

日常开发按风险分层执行：

vpr @01mvp/web#test
vpr @01mvp/api#test
vpr @01mvp/auth#test

vpr @01mvp/product#test:e2e:public

vpr @01mvp/product#db:migrate
vpr @01mvp/product#test:e2e:auth

vpr @01mvp/product#test:e2e

vpr @01mvp/product#test:e2e:production

PLAYWRIGHT_BASE_URL=https://staging.example.com vpr @01mvp/product#test:e2e:production

运行命令

vpr @01mvp/web#test

vpr @01mvp/api#test
vpr @01mvp/auth#test

vpr @01mvp/web#test --coverage

vpr @01mvp/product#build

vpr @01mvp/product#test:e2e:public
vpr @01mvp/product#test:e2e:auth
vpr @01mvp/product#test:e2e

vpr @01mvp/product#test:e2e:production

vpr @01mvp/product#type-check
vpr @01mvp/product#test

当前覆盖范围

这几个层级是互补的：Vitest 跑得快，适合守住模板结构和共享包；浏览器 E2E 适合确认页面真的能打开、点击后真的能跳转；生产 smoke 用来抓 dev server 里看不到的构建和运行时问题。

Web 测试示例

import { readFileSync } from "node:fs";
import { describe, expect, it } from "vite-plus/test";

describe("route parity", () => {
  it("keeps dashboard route represented", () => {
    const source = readFileSync("src/routeTree.gen.ts", "utf8");
    expect(source).toContain("/dashboard");
  });
});

这类测试放在 products/01mvp/apps/web/src/__tests__/*.test.ts。不需要真实浏览器的结构、边界和纯逻辑测试，都优先放这里。

Playwright 测试示例

import { expect, test } from "@playwright/test";

test("dashboard 未登录跳转登录页", async ({ page }) => {
  await page.goto("/dashboard", { waitUntil: "networkidle" });
  await expect(page).toHaveURL(/\/auth\/login/);
  expect(new URL(page.url()).searchParams.get("redirect")).toBe("/dashboard");
});

这类测试放在 products/01mvp/apps/web/__e2e__/**/*.spec.ts。本地调试可以进入 products/01mvp/apps/web 后运行：

vp exec playwright test --debug

当前 E2E 默认使用隔离端口 7010，避免误用你手动启动在 7001 的开发服务。如果要指定地址，可以设置：

PLAYWRIGHT_BASE_URL=http://localhost:7001 vpr @01mvp/product#test:e2e:public

移动端用 .mobile.spec.ts 文件，登录态用 .auth.spec.ts 文件，生产 smoke 用 .production.spec.ts 文件。

登录态 E2E 的认证状态

需要登录态的 E2E 推荐使用 Playwright setup project：

1. auth-setup 项目运行 vpr @01mvp/product#db:seed 准备测试管理员。
2. auth-setup 通过登录页完成一次真实邮箱密码登录。
3. 登录成功后把 storageState 保存到 test-results/.auth/admin.json。
4. authenticated-chromium 项目通过 storageState 启动，直接访问 /dashboard、/dashboard/security、/admin 等页面。

db:seed 不需要改名。它负责准备数据库数据；Playwright 的 auth-setup 负责准备浏览器登录态。认证状态文件包含 cookie 和会话信息，不能提交到 Git；当前写入已忽略的 test-results/.auth/，只作为本次测试产物。

如果要让 auth E2E 使用指定数据库，可以传入：

PLAYWRIGHT_DATABASE_URL=postgresql://jackiexiao@localhost:5432/01mvp vpr @01mvp/product#test:e2e:auth

如果目标是可丢弃的远程开发库，必须显式放行：

PLAYWRIGHT_DB_SEED_ALLOW_REMOTE=true \
PLAYWRIGHT_DATABASE_URL=postgresql://postgres:[email protected]:5432/01mvp-start \
PLAYWRIGHT_BASE_URL=https://staging.example.com \
vpr @01mvp/product#test:e2e:auth

如果仓库里同时有 OneSay，OneSay 的本地浏览器测试走 Wrangler D1：Playwright 会先执行 @onesay/db 的本地 D1 migration，再用 Wrangler dev 启动应用，auth-setup 会把测试管理员写入 Wrangler 的本地 D1 状态，不会调用 Postgres seed。

生产 smoke 的目标环境

vpr @01mvp/product#test:e2e:production 默认会执行本地产品 build 和 start，然后访问 http://localhost:7011。这类测试用于确认生产构建产物能启动、SSR 正常、CSP nonce 正常、静态资源能访问、/api/health 正常、登录路由可用。

如果设置了 PLAYWRIGHT_BASE_URL，Playwright 不会启动本地服务，而是直接访问这个地址：

PLAYWRIGHT_BASE_URL=https://example.com vpr @01mvp/product#test:e2e:production

真实生产 smoke 应保持只读、低风险：检查首页、登录页、健康检查、静态资源和未登录保护边界即可。需要写数据或管理员权限的流程放在本地、CI 临时库或预发环境。

什么时候补测试

下面这些改动建议同步补测试：

• 新增 Hono route、oRPC procedure、TanStack route guard 或鉴权中间件
• 修改支付、积分、权限、上传、登录注册、数据库 schema
• 调整 packages/* 中会被多个 app 复用的逻辑
• 修改公开文档路由、定价页、登录页、设置页、后台页
• 修复线上 bug（先写能复现问题的测试，再改实现）

登录注册属于必须重点保护的流程。至少要覆盖：

• /auth/login 能打开，页面没有 runtime error。
• /api/rpc/auth/capabilities 正常返回，Google / GitHub 按钮按配置可见。
• 手机号登录、邮箱登录、注册入口能进入对应表单。
• 未登录访问 /dashboard、/ai、/admin 会跳到登录页，并保留安全的 redirect。
• 移动端菜单能打开，并能进入登录页。

测试放哪里

默认原则：越靠近底层逻辑，测试越小；越靠近用户流程，测试越像真实浏览器操作。