playwright-skill

请先阅读项目的 tests/README.md——环境变量、Docker 和脚本都在那里。

相关 FMC 技能：tanstack-router-conventions（路由/搜索）、tanstack-start-auth（会话）、tanstack-start-conventions。

---

官方文档（请获取；不要重复）

Playwright 没有官方的 llms.txt（请求已关闭）。

主题	URL
简介和编写测试	https://playwright.dev/docs/intro
定位器（getByRole 等）	https://playwright.dev/docs/locators
测试配置	https://playwright.dev/docs/test-configuration
最佳实践	https://playwright.dev/docs/best-practices
CI	https://playwright.dev/docs/ci
Agent（CLI）	https://playwright.dev/docs/getting-started-cli
TanStack 文档索引	https://tanstack.com/llms.txt
TanStack Start E2E 示例	https://github.com/TanStack/router/tree/main/e2e/react-start
地图交互（可选）	https://mapgrab.github.io/docs/getting-started/stage-two/playwright

---

三个层级（选择合适的工具）

层级	适用场景	位置
项目 E2E	测试套件、CI、回归测试	@playwright/test 位于 tests/*.spec.ts，仓库中的 playwright.config.ts
Agent 探索	交互式调试、水合、React 树、快速 UI 检查	agent-browser MCP——技能 tech-stack、技能 tech-stack → references/agent-browser-mcp.md
临时测试（本技能）	一次性脚本、外部网站、没有 MCP	通过 run.js 执行 /tmp/playwright-test-*.js
数据库架构/查询	检查表	Postgres MCP——技能 tech-stack → references/postgres-mcp.md

对于仓库内的工作，凡是应该纳入回归测试的内容，优先使用项目 E2E。

边界（Playwright 与 agent-browser）

关注点	@playwright/test（本技能）	agent-browser（tech-stack）
回归测试、CI、身份验证桩、地图测试钩子	✓	—
水合、React 树、快速 UI 调试	—	✓
地图（WebGL）	waitForMapLoad、瓦片/网络辅助工具、MapGrab	带注释的截图、eval

**tilda-geo 的 smoke / 身份验证桩 / 地图规格：**编写时请阅读 references/tilda-patterns.md（环境变量门控、smoke 套件、会话桩流程、地图步骤、路由固件）。

需要保留的探索发现 → 添加 tests/*.spec.ts 并运行 bun run e2e。

---

TanStack Start — playwright.config.ts

参考实现：tilda-geo app/playwright.config.ts。

环境变量加载

在 defineConfig 之前加载环境变量，以便 webServer 获取 DATABASE_* 等变量，加载顺序为：仓库 .env、应用 .env（可选）、.env.test（仅用于测试）。

服务层级

层级	用途	webServer.command	说明
本地 / 冒烟测试	快速反馈（TILDA 默认）	bun run dev	Vite 开发服务器，例如 http://127.0.0.1:5173
CI / 发布	类生产环境	bun run build && bun run start	按照 TanStack e2e 设置 PORT / VITE_SERVER_PORT
预览	已构建资源 + SSR 预览	bun run build && bun run preview --port …	TanStack vite preview 模式

Docker / DB： 如果应用需要 Postgres 或地图瓦片，请在 Playwright 外部启动 compose（docker compose up db tiles -d）。除非 CI 已验证可行，否则不要把 compose 命令塞进 webServer.command。

配置模板

从此技能目录复制 playwright.config.ts.template（baseURL 为 http://127.0.0.1:5173，webServer: bun run dev，使用 chromium 项目）。

---

FMC / TILDA 模式

tilda-geo（app/）中的规范路径：

关注点	位置
配置	playwright.config.ts
设置文档	tests/README.md
冒烟测试（公开路由）	tests/smoke/public-routes.spec.ts
冒烟测试（尾部斜杠）	tests/smoke/trailing-slash-redirect.spec.ts
冒烟测试（区域 beforeLoad）	tests/smoke/region-before-load.spec.ts
模拟管理员 / 角色认证	tests/pages/admin.stubbed-auth.spec.ts
区域 + 地图（真实 OAuth）	tests/pages/regions.spec.ts（RUN_OAUTH_E2E=1）
文档区域下载	tests/pages/docs-region-downloads.spec.ts
联系人资料模态框	tests/pages/contact-profile-modal.spec.ts
认证测试夹具	tests/fixtures/auth.ts
路由列表	tests/fixtures/routes.ts
控制台 / 服务端错误	tests/utils/console.ts、tests/utils/server.ts
地图等待 / 渲染辅助工具	tests/utils/maps.ts
地图网络验证	tests/utils/network.ts
动态 URL 正则转义	tests/utils/regex.ts
应用测试钩子	src/components/shared/utils/playwright.ts

VITE_PLAYWRIGHT_ENABLED

在仓库 .env 中（参见 .env.example）：

VITE_PLAYWRIGHT_ENABLED=true

仅在 E2E 测试中启用测试 ID 和地图信号，不会出现在生产 HTML 中。

应用钩子（playwright.ts）

import { createIsomorphicFn } from '@tanstack/react-start'

export function playwrightTestId(testId: string) {
  return import.meta.env.VITE_PLAYWRIGHT_ENABLED === 'true' ? testId : undefined
}

export const exposeMainMapForDebugging = createIsomorphicFn()
  .server((_map?: MaplibreMap) => {})
  .client((map?: MaplibreMap) => {
    const playwrightEnabled =
      import.meta.env.VITE_PLAYWRIGHT_ENABLED === 'true' || window.__PLAYWRIGHT_ENABLED === 'true'
    if (import.meta.env.DEV || playwrightEnabled) {
      window.__mainMap = map
    }
  })

export const firePlaywrightMapLoadedEvent = createIsomorphicFn()
  .server(() => {})
  .client(() => {
    const playwrightEnabled =
      import.meta.env.VITE_PLAYWRIGHT_ENABLED === 'true' || window.__PLAYWRIGHT_ENABLED === 'true'
    if (!playwrightEnabled) return
    window.dispatchEvent(new CustomEvent('mapLoaded'))
    window.__mapLoaded = true
  })

在地图的 onLoad 处理函数中调用这两个辅助函数：exposeMainMapForDebugging(event.target) 和 firePlaywrightMapLoadedEvent()。在开发和 Playwright 模式下，window.__mainMap 均可用；mapLoaded 事件仍仅在 Playwright 模式下触发。关于为何暴露地图及 onLoad 的接线方式，请参阅 skill react-map-gl → references/map-debug-exposure.md。测试使用 tests/utils/maps.ts（waitForMapLoad、verifyMapRendered、checkMapTilesLoaded、getMapLayerIds）。对于区域页面的瓦片/API 覆盖测试，请在 waitForMapLoad 之后使用 tests/utils/network.ts 中的 verifyMapNetworkRequests。

对于在地图画布上点击/拖动，可以考虑使用 MapGrab（曾用于旧版 Trassenscout 调查；将这些流程迁移到 Start 时采用）。

冒烟测试（迁移后）

从 Next → TanStack Start 迁移后，添加或运行冒烟测试：

1. 使用 baseURL 执行 page.goto(route)
2. 断言路径名未改变（未因崩溃而重定向）
3. 确认 expect(page.locator('main').first()).toBeVisible()
4. 执行 expectNoConsoleErrors(page)（参阅 utils）

路由列表位于 tests/fixtures/routes.ts（PUBLIC_SMOKE_ROUTES、ADMIN_ROUTES、ADMIN_REDIRECT_SMOKE_ROUTE 等）。运行：bun run e2e -- tests/smoke。

身份验证

策略	适用场景	TILDA
模拟管理员	管理页面、搜索参数 UI	createStubbedAdminSession(page, baseURL, { identityKey }) — Better Auth cookies + Prisma user
模拟用户	非管理员/模态框流程	createStubbedUserSession(page, baseURL, { identityKey })
真实 OAuth	地图 + 区域回归测试	auth-setup.spec.ts + regions.spec.ts，需设置 RUN_OAUTH_E2E=1 + .env.test 中的 TEST_OSM_*

并行安全：模拟管理员测试套件会共用数据库行，因此请使用 mode: 'serial'，并为每个路由使用嵌套的 test.describe，避免 afterEach 清理其他工作进程的会话（cleanupStubbedSessionData('ADMIN' | 'USER', identityKey)）。

**动态 URL：**根据可能包含 ? 或特殊字符的 fixture 路径构造 toHaveURL(new RegExp(...)) 时，请使用 tests/utils/regex.ts 中的 escapeRegExp(route)。

质量辅助函数

在 goto 之前挂载收集器；导航后进行断言：

• 控制台：collectConsoleErrors → 过滤 KNOWN_ACCEPTABLE_ERRORS → 遇到 error 时失败
• 服务器：collectServerErrors(page, baseURL) — 同源 5xx 错误和 requestfailed

如果出现已知的无害错误，请在 util 文件中扩展允许列表。

定位器

仅当 role/label/text 定位器不够用时，才使用 playwrightTestId('…')。

---

项目 E2E 工作流

package.json 脚本（TILDA 约定）：

"e2e": "playwright test --project=chromium"

• bun run e2e → chromium 项目（本地/CI 默认运行）
• bun run e2e -- --ui / bun run e2e -- --debug → 在 -- 后传入 Playwright 标志
• bun run e2e -- tests/smoke → 运行部分测试规范

bun add -d @playwright/test dotenv
bunx playwright install chromium
# Start DB/tiles if required (see tests/README.md)

---

临时自动化（技能运行器）

设置（一次性）：

cd ${CLAUDE_SKILL_DIR} && bun run setup

工作流：

1. 对于 localhost：先检测开发服务器：

   bun -e "require('${CLAUDE_SKILL_DIR}/lib/helpers').detectDevServers().then(s => console.log(JSON.stringify(s)))"
   

2. 将脚本写入 /tmp/playwright-test-*.js（不要将临时脚本提交到技能目录）。

3. 在顶部设置 TARGET_URL 参数。

4. 从项目目录运行（而不是技能文件夹）：bun ${CLAUDE_SKILL_DIR}/run.js /tmp/playwright-test-*.js。run.js 会根据你运行命令的目录解析相对脚本路径和 takeScreenshot 的输出路径；对于原始的 page.screenshot({ path })，请使用绝对路径。

标头（用于识别自动化流量）：

PW_HEADER_NAME=X-Automated-By PW_HEADER_VALUE=playwright-skill \
  bun ${CLAUDE_SKILL_DIR}/run.js /tmp/my-script.js

多个标头：PW_EXTRA_HEADERS='{"X-Automated-By":"playwright-skill"}'。

**默认设置：**默认以无头模式运行（Agent 无法查看窗口）；只有在人类需要观看时才使用 headless: false。

辅助函数（lib/helpers.js）：detectDevServers、createContext / getExtraHeadersFromEnv、takeScreenshot。

---