---
url: /docs/testing.md
---
# 测试与排查

## 按改动选择检查

```sh
bun test --run
bun typecheck
bun web:check
bun lint
bun format:check
bun build
bun run docs:build
```

根配置在 `vitest.config.ts`，测试靠近实际代码。接口和数据边界使用进程内数据库；React 行为测试使用浏览器模拟环境；Astro 模板另由 `web:check` 检查。

只改教程时检查格式、文档构建和浏览器内容即可，不必为可逆文案改动编写测试。修改认证、数据归属、积分或账单时，需要有意义的边界测试。

## 数据库测试

`@repo/db/testing` 的 `createTestDatabase()` 创建独立 PGlite，应用已提交迁移。每个测试文件建立自己的实例，测试间调用 `reset()`，结束时 `close()`。

```ts
import { createTestDatabase } from "@repo/db/testing";

const database = await createTestDatabase();
try {
  // 使用 database.db 插入测试身份并执行实际查询
  await database.reset();
} finally {
  await database.close();
}
```

不要向真实开发或生产库运行测试。测试应用迁移，能发现漏迁移、唯一约束和外键问题，不能改成结构推送来掩盖失败。

## 接口测试

使用路由调用器和明确上下文，覆盖成功、未登录、跨用户、跨组织、移除成员及重复事件。涉及事务、余额和唯一约束时使用真实数据库语义，避免只模拟“数据库返回成功”。

现有参考包括 `apps/api/routers/workspace.test.ts`、`billing.test.ts`、`db/schema/index.test.ts` 和账号配置测试。测试数量会随迭代变化，验收记录按当时日期保存。

## 界面测试

覆盖加载、空数据、提交失败、键盘和主题；认证成功后检查会话刷新，退出失败时保留真实登录状态。新增路由还要检查直接加载与边缘分流，不能只点击站内链接。

## 手工验收与限制

检查公开原始 HTML、工具真实输出、复制与下载、账号切换后的数据隔离。第三方登录、邮件投递、Stripe 测试支付及线上 Hyperdrive 必须分别实测；本地测试通过不自动证明这些服务完成。

失败时先定位配置、网络、路由、认证、数据库或界面状态，再运行对应的最小复现。保留必要错误和请求标识，不输出秘密或用户内容。