TypeHero 端到端测试实战指南:基于 Playwright 的 E2E 测试编写与运行流程
TypeHero 端到端测试实战指南:基于 Playwright 的 E2E 测试编写与运行流程
TypeHero 是一个面向 TypeScript 开发者的挑战与协作社区平台,其核心交互(挑战解答、评论、分享)都发生在真实浏览器环境中,因此采用 Playwright 构建端到端(E2E)测试套件,以保证应用按预期工作。本文以仓库决策文档 docs/procedures/000-run-e2e-tests.md 为骨架,结合 apps/web/playwright.config.ts 等实际配置与测试源码,完整讲解在 TypeHero 中编写、运行 E2E 测试的规范流程,读完你将掌握从新建测试文件、管理认证状态到本地运行与 UI 调试的完整链路。
背景:为什么 TypeHero 选择 Playwright
TypeHero 的 E2E 测试选型决策记录于仓库内的 docs/procedures/000-run-e2e-tests.md。决策文档明确指出:TypeHero 采用 Playwright 作为 E2E 测试框架,因为 Playwright 能够为现代 Web 应用提供可靠、端到端的测试能力——它支持真实的浏览器内核(Chromium 等)、自动等待、网络拦截与追踪(trace)等特性,非常适合验证 TypeHero 这种高度依赖编辑器交互、评论区和分享链接的复杂前端应用。
在该决策中,编写测试被约束为三条基本步骤:
- 进入
apps/web/tests/e2e目录; - 以测试名称新建文件,例如
my-test.test.ts; - 运行
npx playwright test执行测试。
从当前仓库看,这条决策已经落地为完整的工程实践:apps/web/tests/e2e 目录下不仅有按"认证 / 未认证"划分的测试文件,还有配套的认证种子脚本、常量定义与辅助工具,构成了一个可维护、可复用的 E2E 测试体系。
测试目录结构与命名约定
所有 E2E 测试都集中在 apps/web/tests/e2e 下,Playwright 通过配置文件中的 testDir: './tests/e2e' 指定了这一目录。当前仓库中的实际组织方式如下:
authenticated/comment.test.ts:登录态下的评论创建、编辑、删除与分享测试;unauthenticated/challenge.test.ts:未登录态下的挑战页、重置编辑器等测试;unauthenticated/explore.test.ts:探索页测试;unauthenticated/home.test.ts:首页渲染与 WCAG 无障碍扫描测试;auth.setup.ts:认证状态种子脚本,负责生成未登录 / 已登录两类 storageState;constant.ts:测试共享的常量(测试用户信息、无障碍扫描标签);helpers.ts:跨平台快捷键与代码片段包装等辅助函数。
命名约定上,文档建议新建文件时使用 .test.ts 后缀,例如 my-test.test.ts。而结合配置文件可以发现更细致的约定:authenticated 与 unauthenticated 两个 project 分别通过 testMatch: /.*\.authenticated\.ts/ 和 testMatch: /.*\.unauthenticated\.ts/ 匹配文件,也就是说 Playwright 是根据文件名后缀(.authenticated.ts / .unauthenticated.ts)来决定测试归属的,同时 setup project 匹配 .*\.setup\.ts。这意味着命名后缀不仅是可读性约定,还直接影响测试运行时的项目分配与认证状态注入。
从零编写第一个 E2E 测试
按照决策文档的步骤,编写测试只需三步:
- 进入
apps/web/tests/e2e; - 新建
my-test.test.ts(如属于登录态场景可命名为my-test.authenticated.ts,未登录场景用my-test.unauthenticated.ts); - 运行
npx playwright test。
仓库中现成的测试可以作为最佳模板。例如 apps/web/tests/e2e/unauthenticated/challenge.test.ts 展示了"挑战页"的完整断言流程:先通过 prisma 清理该挑战的评论、解答与提交数据以保证用例可重复,再使用 page.goto('/challenge/pick') 导航,随后用 page.getByRole(...) 与 expect(...).toBeVisible() 逐项验证 UI 状态——包括 "Comments" 按钮、空评论占位文案、空解答与空提交提示,以及未填写内容时 "Submit" 按钮的禁用态。
import { test, expect } from '@playwright/test';
import { prisma } from '@repo/db';
test.use({ storageState: 'playwright/.auth/unauthenticated.json' });
test('challenge page', async ({ page }) => {
const challengeId = 4;
// 清理历史数据,保证测试可重复执行
await prisma.comment.deleteMany({ where: { rootChallengeId: challengeId, parentId: { not: null } } });
await prisma.comment.deleteMany({ where: { rootChallengeId: challengeId } });
await prisma.sharedSolution.deleteMany({ where: { challengeId } });
await prisma.submission.deleteMany({ where: { challengeId } });
await page.goto('/challenge/pick');
await expect(page.getByRole('heading', { name: 'Pick' })).toBeVisible();
await expect(
page.getByText('Implement the built-in Pick<T, K> generic without using it.'),
).toBeVisible();
// ... 更多交互与断言
});
同一个文件中的 "reset challenge" 测试则展示了 Monaco 编辑器的操控方式:用 page.getByLabel('Editor content').first().fill('') 清空编辑器,点击 button[name="reset"] 后经确认弹窗恢复初始代码 type MyPick<T, K> = any,验证了"重置挑战"这一用户路径。
运行测试:命令行与三种实用模式
决策文档给出的默认运行命令是:
npx playwright test
在 TypeHero 中,该命令在 apps/web/package.json 中封装为 test:e2e 脚本(对应 playwright test),因此也可以在工作区根目录通过 pnpm --filter web test:e2e 或在 apps/web 下直接运行 pnpm test:e2e。
除默认的终端输出外,TypeHero 还提供了三种针对不同场景的运行方式(均定义于 apps/web/package.json):
- 终端默认模式:
npx playwright test,测试结果直接打印在终端,适合本地快速回归与 CI 使用; - UI 模式:
pnpm test:e2e:ui(对应playwright test --ui --ui-port=8080)。决策文档专门提到:默认测试输出是终端文本,若要看到可视化输出,可启用 UI 模式——Playwright 的 UI 模式会在浏览器面板中逐步回放每个测试动作、查看页面快照与网络请求,便于肉眼观察和定位问题; - 调试模式:
pnpm test:e2e:inspector(对应playwright test $1 --debug),传入测试文件名即可启动 Playwright Inspector 进行逐行调试,例如pnpm test:e2e:inspector my-test。
此外,运行 E2E 测试还需要应用本身处于可访问状态。仓库的 apps/web/playwright.config.ts 通过 webServer 配置自动完成:它执行 pnpm start(即 dotenv -e ../../.env next start,以生产构建方式启动 Next.js 应用),并轮询 http://localhost:3000 直到可用;在本地环境设置 reuseExistingServer: !process.env.CI,意味着本地运行时如果 3000 端口已有服务则直接复用,而 CI 中强制由 Playwright 自行拉起服务。
测试配置深度解析
决策文档对测试"怎么写、怎么跑"做了规定,而真正决定测试如何执行的细节都在 apps/web/playwright.config.ts 中。理解这份配置,是写出与项目约定一致的测试的前提:
| 配置项 | 当前仓库取值 | 含义 |
|---|---|---|
testDir |
./tests/e2e |
测试文件搜索目录,与决策文档指定的目录一致 |
timeout |
15 * 1000(15 秒) |
单个测试的超时上限 |
expect.timeout |
5 * 1000(5 秒) |
单个断言等待元素的最长时间 |
fullyParallel |
false |
关闭文件级并行,避免共享数据库状态互相干扰 |
forbidOnly |
Boolean(process.env.CI) |
CI 中禁止提交 .only 测试 |
retries |
CI 为 2,本地为 0 |
CI 中失败重试 2 次,本地不重试 |
workers |
CI 为 1,本地不限制 |
CI 中单 worker 串行执行 |
reporter |
[['html', { open: 'never' }]] |
生成 HTML 报告但不自动打开浏览器 |
use.baseURL |
http://localhost:3000 |
测试中相对路径 page.goto('/xxx') 的基础地址 |
use.trace |
CI 为 on-first-retry,本地为 retain-on-failure |
失败/重试时保留 trace 追踪文件 |
webServer |
pnpm start + URL 探测 |
自动启动并等待应用就绪 |
四个 project 的分工
配置中最值得注意的是四个 project 的协作关系:
authenticated:匹配*.authenticated.ts,即登录态测试;unauthenticated:匹配*.unauthenticated.ts,即未登录测试;setup:匹配*.setup.ts,仅运行认证种子脚本;chromium:使用devices['Desktop Chrome']桌面浏览器配置,加载storageState: 'playwright/.auth/user.json'(登录态快照),并声明dependencies: ['setup']——即先运行 setup 生成登录状态,再执行实际测试。
同时 chromium 项目还通过 contextOptions.permissions 预授权了 clipboard-read 与 clipboard-write,这是评论分享测试(见下文)能够直接读取剪贴板的原因。
认证状态:从数据库种到浏览器
认证是 TypeHero E2E 测试的关键设计。由于评论、提交等功能需要登录,测试必须能够稳定地"伪造"一个登录用户。方案在 apps/web/tests/e2e/auth.setup.ts 中实现,思路是直接操作数据库 + 写入浏览器 Cookie:
- 用
prisma.user.upsert按固定邮箱(user@typehero.dev,定义于 apps/web/tests/e2e/constant.ts)创建测试用户,同时连带创建 sessions、roles 与 GitHub oauth accounts 关联记录,session 过期时间设为一个月后; - 通过
page.context().addCookies向浏览器写入next-auth.session-tokenCookie,使 NextAuth 认为该用户已登录; - 将未登录/已登录两种状态分别导出为
playwright/.auth/unauthenticated.json与playwright/.auth/user.json,供各测试通过test.use({ storageState: ... })注入。
测试用户及其 session 的固定值集中在 apps/web/tests/e2e/constant.ts:
export const USER = {
id: 'e31340ff-f0cd-42c6-a2db-119352a55455',
email: 'user@typehero.dev',
sessionToken: 'd4d6a53d-b2e0-42c7-a4b3-2d246ce2f54a',
};
跨平台辅助函数
E2E 测试常涉及键盘快捷键,而 macOS 与 Windows/Linux 的修饰键不同。apps/web/tests/e2e/helpers.ts 针对这一点提供了平台自适应封装:ctrlC / ctrlV 会根据 os.platform() 判断使用 Meta(macOS)还是 Control(其他平台)修饰键;wrapTypescriptCode 则用于把代码片段包装成 Markdown 代码块文本,方便填入富文本评论输入框。
export async function ctrlV(page: Page): Promise<void> {
const isMac = os.platform() === 'darwin';
const modifier = isMac ? 'Meta' : 'Control';
await page.keyboard.press(`${modifier}+KeyV`);
}
export const wrapTypescriptCode = (text: string) => {
return `\n\`\`\`ts\n${text}\n\`\`\``;
};
从源码看测试的实际业务场景
为了让"如何写测试"不流于空泛,下面用仓库中的真实测试说明三类典型场景的写法。
场景一:登录态下的评论 CRUD
apps/web/tests/e2e/authenticated/comment.test.ts 覆盖了评论的完整生命周期。其技巧点包括:
- 用
Math.floor(Math.random() * 1000)生成随机后缀,避免测试数据冲突; - 用
test.beforeEach统一导航到/challenge/pick并打开 "Comments" 面板; - 用
div[id^=comment]的 CSS 前缀定位到具体评论块,再在块内通过getByRole找到 "Edit this comment"、"Delete this comment"、"Create a reply" 等按钮; - 通过
*:focus选择器定位当前聚焦的输入框并填充内容,绕开多输入框歧义; - 分享测试利用剪贴板授权,模拟用户点击 "Share this comment" 后执行
ctrlV粘贴,断言 URL 中携带评论 ID,并验证深链/challenge/simple-vue/comments/{id}能正确展示评论。
场景二:未登录态与编辑器重置
apps/web/tests/e2e/unauthenticated/challenge.test.ts 已在前面示例中展开,它同时演示了"测试前置数据清理"这一重要实践:由于测试会真实读写数据库(通过 @repo/db 暴露的 Prisma 客户端),运行前删除该挑战的评论、解答、提交记录,能保证每次运行结果一致、可重复。
场景三:无障碍(a11y)自动化扫描
apps/web/tests/e2e/unauthenticated/home.test.ts 展示了将 E2E 与无障碍检测结合的做法:使用 @axe-core/playwright 的 AxeBuilder,配合 apps/web/tests/e2e/constant.ts 中定义的无障碍标签组:
export const A11YTAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'];
分别对首页的浅色与深色两种主题运行 AxeBuilder({ page }).withTags(A11YTAGS).analyze(),若发现 WCAG A/AA 级违规则抛出 apps/web/playwright/utils/a11yLogger.ts 中的 A11yError,最终断言 violations 为空数组。这是 TypeHero 把"可访问性"纳入 E2E 回归防线的一个具体实现。
决策后果:可靠测试套件带来的保障
决策文档在 "Consequences" 一节中总结了该方案的收益:这套基于 Playwright 的 E2E 测试体系,将为应用提供可靠的回归保障,确保应用始终按预期工作。结合仓库现状可以进一步印证这一结论:
- 测试按认证/未认证分层,配合 storageState 与数据库种子,既覆盖了核心用户路径,又保持用例可重复、可并行可控(
fullyParallel: false+ CI 单 worker); - 丰富的断言与调试能力(HTML 报告、trace、UI 模式、Inspector)让失败定位从"看日志"升级为"看回放";
- 无障碍扫描、剪贴板权限、跨平台快捷键等细节处理,说明该套件并非简单的冒烟测试,而是能承担起守护 TypeHero 核心功能质量的完整体系。
结语:把"按步骤写测试"变成工程习惯
回顾决策文档的三步流程——进入 apps/web/tests/e2e、创建 my-test.test.ts、运行 npx playwright test——它依然是最简洁的入门路径。但真正让测试可靠的是仓库中这些配套工程:后缀命名的 project 分流、setup 项目的认证状态生成、Prisma 数据清理、辅助函数封装与无障碍扫描。建议新贡献者在编写测试前,先通读 apps/web/playwright.config.ts 与 tests/e2e 目录下的现有用例,参照 authenticated / unauthenticated 两种模板起步;需要调试时,优先使用 --ui 的 UI 模式观察可视化回放,或借助 --debug 进入 Inspector 逐行检查,即可快速验证新增用例的每一步交互是否符合预期。