E2E Studio Tests 用于为 Supabase Studio 运行 Playwright 端到端测试。
一、用途 为 Supabase Studio（e2e/studio）编写并运行 Playwright 端到端测试，适用于运行 E2E 测试、编写新 E2E 测试，以及调试不稳定或失败的 Playwright 测试。
二、运行方式 测试必须在 e2e/studio 目录下运行： cd e2e/studio && pnpm run e2e 运行特定文件： cd e2e/studio && pnpm run e2e -- features/cron-jobs.spec.ts 使用 grep 过滤： cd e2e/studio && pnpm run e2e -- --grep "test name pattern" 调试用 UI 模式： cd e2e/studio && pnpm run e2e -- --ui
三、环境设置 测试会依据 web server 配置自动启动 Supabase 本地容器；自托管模式（IS_PLATFORM=false）下测试并行运行（3 个 worker）；自托管测试无需手动设置。
四、测试文件结构 测试位于 e2e/studio/features/*.spec.ts；使用自定义测试工具 import { test } from '../utils/test.js'；测试夹具提供 page、ref 等 helper。
五、常见模式 使用宽裕的超时等待元素：await expect(locator).toBeVisible({ timeout: 30000 })；对共享数据库状态的测试使用串行模式：test.describe.configure({ mode: 'serial' })。
六、编写稳健的选择器 优先级从优到劣：getByRole 配合可访问名称（最稳健，同时测试可访问性）；getByTestId（稳定、显式的测试钩子）；getByText 精确匹配（适合唯一文本）；locator 搭配 CSS（少用，更脆弱）。 应避免的模式：XPath 选择器（对 DOM 变化脆弱）；使用 locator('..') 的父级遍历（结构变化即失效）；在通用元素上使用宽泛的 filter({ hasText })（可能匹配多个元素）。 当组件缺少良好可访问名称时，在源码中补充，例如为按钮添加 aria-label="Configure API privileges"，再在测试中使用。 缩小搜索范围：将选择器限定到特定容器，避免匹配错误元素，例如先取侧面板再在其中查找 switch，或先定位唯一元素再向下限定。
七、避免竞态条件 在触发动作之前先设置 API 等待器，这是不稳定测试最常见的来源。正确做法是先创建 apiPromise，再点击按钮，最后 await apiPromise；导航前同理；当动作触发多个 API 调用时，需等待全部完成（Promise.all）。
八、等待策略 Playwright 会自动等待元素可操作，优先使用它而非手动超时。使用 expect.poll 处理动态状态变化；使用 waitForSelector 配合 state 处理元素生命周期；避免 networkidle，改用具体 API 等待。waitForTimeout 唯一可接受的用途是客户端防抖等待（如输入搜索词后等待 300ms）。禁止用 waitForTimeout 等待 UI 或网络，应改为等待具体的 UI 元素、API 响应或 toast。
九、避免点击时使用 force: true 不要强制点击隐藏元素，而是先让其可见，例如先 hover 显示按钮再点击。
十、测试结构 始终从自定义测试工具导入 test；使用 withFileOnceSetup 处理每个文件只运行一次的昂贵设置；交互前先关闭 toast，避免其遮挡按钮。
十一、断言 始终添加描述性信息以便调试；对慢操作使用显式超时。
十二、辅助函数 将可复用操作提取为领域 helper（如 e2e/studio/utils/storage-helpers.ts）；使用既有等待工具 createApiResponseWaiter、waitForApiResponse、waitForGridDataToLoad、waitForTableToLoad；用 expectClipboardValue 代替带硬编码超时的手动剪贴板读取。
十三、API 模拟 可通过 page.route 拦截并返回 mock 数据；对可选 API 调用使用软等待（soft: true、fallbackWaitMs）。
十四、清理 在 beforeAll/beforeEach 中清理测试数据；删除前先检查以优雅处理已有状态；对修改过本地存储的测试，使用 resetLocalStorage 重置。
十五、调试 查看 trace：cd e2e/studio && pnpm exec playwright show-trace <path-to-trace.zip>；查看 HTML 报告：cd e2e/studio && pnpm exec playwright show-report；错误上下文文件保存在 test-results/ 目录；本地调试时可使用 Playwright MCP 工具检查 UI。
十六、CI 与本地开发的差异 关键在于冷启动与热状态：CI（冷启动）从空白数据库开始，每次运行重置数据库并启动全新容器，pg_cron 等扩展默认不启用；使用 pnpm dev:studio-local 本地调试时，数据库可能已保留此前运行的状态（扩展已启用、存在测试数据）。本地通过但 CI 失败的测试，通常是对既有状态做了假设，常见问题包括扩展未启用、并行测试修改共享状态引发竞态、状态未就绪导致定位器匹配错误元素。测试框架在运行 pnpm run e2e 时会自动重置数据库，与 CI 行为一致；若用 pnpm dev:studio-local 配合 Playwright MCP 调试，需注意状态与 CI 不同。
十七、CI 失败调试流程 先用 pnpm run e2e -- features/<file>.spec.ts 在本地以冷启动方式运行；检查 test-results/ 中的错误上下文；若需检查 UI 状态，启动 pnpm dev:studio-local 并使用 Playwright MCP 工具；注意开发服务器中的状态在 CI 中可能并不存在。