BTST Testing 是 Better Stack（btst）项目中关于测试的实践指南，涵盖单元测试（Vitest）与端到端测试（Playwright）两类测试的编写与运行方式。
一、用途 该技能用于指导在 btst 代码库中编写和运行测试，确保插件、CLI 工具以及代码生成输出得到验证。单元测试聚焦于 getters、mutations 等逻辑，E2E 测试则验证 CLI 代码生成（codegen）在真实框架项目中的实际表现。
二、单元测试（Vitest） 位置与命名：
- packages/stack/src/plugins/{name}/tests/ 下包含 getters.test.ts、mutations.test.ts、plugin.test.ts
- packages/cli/src/utils/tests/ 下为 {util}.test.ts
运行命令：
- packages/stack（watch 模式）：cd packages/stack && pnpm test
- packages/cli（运行一次）：cd packages/cli && pnpm test
使用内存适配器测试 getters/mutations 的模式： 通过 createMemoryAdapter + defineDb 为每个测试创建隔离的内存数据库。示例代码使用 vitest 的 describe/it/expect/beforeEach，从 @btst/adapter-memory 引入 createMemoryAdapter，从 @btst/db 引入 defineDb 与 DBAdapter 类型，结合插件 schema 与 getters 进行测试。beforeEach 中调用 createTestAdapter() 保证每个测试使用全新数据库。对于测试环境中不存在的外部模块（如 @vercel/blob/server），使用 vi.mock 进行模拟。
三、E2E 测试（Playwright） E2E 配置位于 e2e/playwright.codegen.config.ts，命令为 pnpm codegen:e2e。它会启动 codegen-projects/ 下的应用（端口 3006–3008），测试 CLI 代码生成输出，以准确反映真实 btst init 用户所获得的结果。codegen 项目通过 scripts/codegen/setup-*.sh 从零构建。
位置与命名：测试位于 e2e/tests/，命名约定为 smoke.{feature}.spec.ts，例如 smoke.chat.spec.ts、smoke.blog.spec.ts。
搭建 codegen 项目（运行 codegen E2E 前必需）：codegen-projects/ 目录不提交到仓库，需从零构建：
- 搭建特定框架：bash scripts/codegen/setup-nextjs.sh、setup-react-router.sh、setup-tanstack.sh
- 一次性搭建全部框架：bash scripts/codegen/setup.sh
- 清理：bash scripts/codegen/cleanup.sh nextjs（或 react-router、tanstack） 完整细节参见 scripts/codegen/README.md 中关于 E2E overlay 文件系统与更新工作流的说明。
运行命令（在 e2e 目录下）：
- 运行全部 codegen E2E 测试：pnpm codegen:e2e
- 指定框架：pnpm codegen:e2e:nextjs、pnpm codegen:e2e:tanstack、pnpm codegen:e2e:react-router
- 指定测试文件：pnpm codegen:e2e:nextjs -- tests/smoke.blog.spec.ts
Playwright 项目与端口：nextjs:codegen 使用 3006，tanstack:codegen 使用 3007，react-router:codegen 使用 3008。设置 BTST_FRAMEWORK=nextjs|tanstack|react-router 可只启动一个服务器。
测试运行间的内存状态：内存适配器在服务器进程生命周期内保持数据存活。若对已运行的服务器重新运行测试，之前的测试数据仍会存在并可能导致失败。重置方法：杀掉服务器并让 reuseExistingServer: true 重启，或使用 start:e2e 重新构建：kill $(lsof -ti:3006) 后执行 pnpm -F nextjs run start:e2e（重新构建 .next 并全新启动）。
API 密钥守卫模式：需要外部 API（如 OpenAI）的功能在密钥缺失时必须优雅跳过。在 test.beforeEach 中检查 API 密钥，调用 test.skip() 而非抛出异常，并在 spec 文件顶部注释中记录所需环境变量。
环境变量：环境变量由 playwright.codegen.config.ts 自动从 codegen-projects/nextjs/.env 加载。在 CI 中，codegen 工作流（.github/workflows/codegen-e2e.yml）从零构建 codegen 项目，并从 secrets 传入 OPENAI_API_KEY。
四、适用场景 适用于 btst 项目的开发者编写插件单元测试、CLI 工具测试，以及验证代码生成在 Next.js、TanStack、React Router 等框架下的端到端行为。
五、限制 资料未提供测试覆盖率要求、性能基准、其他测试框架支持或收费相关信息。