MkSaaS文档自动化测试
运行 MkSaaS 单元测试、浏览器流程测试和真实支付沙箱测试
MkSaaS 使用 Vitest 验证逻辑与服务边界，使用 Playwright 验证浏览器流程，并提供独立的 Stripe、Creem、Waffo 支付沙箱测试。以下命令在您的 MkSaaS 应用仓库中运行。
测试覆盖范围
| 测试类型 | 验证内容 | 命令 |
|---|---|---|
| 单元测试 | 认证邮件失败恢复、结账 Action、支付提供商与 Webhook、邮件订阅、URL 处理及 AI 响应解析 | pnpm test |
| 本地 E2E | 中英文公共页面、注册登录与验证邮件恢复、受保护和管理员路由、个人设置、API 密钥、支付 Webhook 及 AI 交互 | pnpm e2e |
| 生产构建冒烟测试 | 本地 Next.js 生产构建中的公共页面和受保护路由重定向 | pnpm e2e:production |
| 支付沙箱 | 真实托管结账、提供商 Webhook、PostgreSQL 支付记录和账单页面权益 | pnpm e2e:stripe / pnpm e2e:creem / pnpm e2e:waffo |
单元测试使用 Mock 替代外部服务。本地浏览器测试连接配置的 PostgreSQL 数据库；E2E 模式跳过真实邮件发送、注册后的自动邮件订阅和支付通知。AI 浏览器测试使用 Mock 响应。这些测试不能证明邮件实际送达、OAuth 提供商接入或真实 AI 服务可用。
准备环境
pnpm install
pnpm e2e:install浏览器与支付测试需要在未提交的 .env 中设置 DATABASE_URL，指向专用本地或测试 PostgreSQL 数据库，然后应用模板已有的迁移：
pnpm db:migrate测试运行器会启动应用服务器，但不会自动创建数据库或执行迁移。测试夹具会创建和清理 e2e-*@example.test 用户；支付测试还会写入和更新支付记录，因此应使用测试数据库。
普通 E2E 使用端口 3100 和 .next-e2e，与模板默认 3000 端口的开发服务器分开。生产冒烟测试使用 .next-production-e2e 构建并在 3201 端口运行 next start。请保持端口空闲，可用 E2E_PORT 或 PRODUCTION_E2E_PORT 覆盖默认端口。
运行测试
pnpm lint:check # 只读 Biome 检查
pnpm typecheck
pnpm test
pnpm test:coverage
pnpm check # lint:check → typecheck → test → build
pnpm e2e发布较大范围的模板升级前，运行：
pnpm verify:upgrade # check → e2e → e2e:production此命令验证本地应用，不会部署。支付沙箱测试独立运行，不包含在 verify:upgrade 中。
只运行相关测试：
pnpm test tests/unit/payment
pnpm test:watch
pnpm e2e -- tests/e2e/specs/auth.spec.ts
pnpm e2e -- tests/e2e/specs/ai-playground.spec.ts
pnpm e2e:ui支付沙箱测试
| 提供商 | 测试场景 | 默认端口 | 前置条件 |
|---|---|---|---|
| Stripe | 月付、年付、终身结账、拒付、门户切换方案、取消及终身订单退款 | 3119 | Stripe CLI、sk_test_ 密钥及匹配的沙箱 Price ID；运行器启动 Webhook 转发 |
| Creem | 月付、年付、终身结账、拒付及计划取消订阅 | 3120 | CREEM_DEBUG=true、Test Mode 密钥与产品、HTTPS 隧道、已注册的 Webhook 及签名密钥 |
| Waffo | 月付、年付、终身结账及 Webhook 驱动的权益更新 | 3118 | 沙箱商户密钥与产品、HTTPS 隧道、保留 X-Waffo-Signature 的 Test Mode Webhook |
STRIPE_ENV_FILE=/path/to/sandbox.env pnpm e2e:stripe
CREEM_ENV_FILE=/path/to/sandbox.env pnpm e2e:creem
WAFFO_ENV_FILE=/path/to/sandbox.env pnpm e2e:waffo
# 只运行一个场景
STRIPE_ENV_FILE=/path/to/sandbox.env pnpm e2e:stripe -- --grep "yearly subscription"环境变量优先级为：Shell 变量 > 显式提供商环境文件 > 项目 .env* 默认值。密钥和价格、产品 ID 必须来自同一个沙箱账户。启动器强制使用本地 URL 与 E2E 夹具配置，并在中断时清理子进程；数据库仍需配置为您的测试数据库。
Creem 和 Waffo 运行器不会自动启动隧道或注册 Webhook。隧道需指向自动化服务器端口，而非普通开发端口。Waffo 提供 pnpm waffo:setup，用于单独注册 Webhook。端口可通过 STRIPE_E2E_PORT、CREEM_E2E_PORT、WAFFO_E2E_PORT 覆盖，隧道也需同步调整。完整步骤见项目中的 tests/e2e/<provider>/README.md。
沙箱测试覆盖部分提供商流程，单元测试补充其他生命周期及失败场景。一次沙箱结账成功不代表所有续费、退款和失败恢复场景都已验证。
维护与排查
测试位于 tests/unit/ 和 tests/e2e/，验收流程记录在 tests/e2e/TEST-CATALOG.md。功能流程或行为契约变化时更新相关测试。应用控件使用稳定的 data-testid，断言导航、请求、权限和持久化结果。仅修改文案、样式、图标或布局时，无需修改功能测试。
失败时查看终端输出及 test-results/，使用 pnpm exec playwright show-trace <trace.zip> 打开保留的 Trace。数据库错误先检查连接和迁移记录；支付一直等待时检查 Webhook 投递、签名、提供商模式及隧道连通性。
下一步
现在您了解了如何测试 MkSaaS 项目，探索这些相关主题：