TypeHero 端到端测试实战指南:基于 Playwright 的 E2E 测试编写与运行流程

原创2026-10-07 10:45:351,933 阅读
文章标签:教育前端后端

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 这种高度依赖编辑器交互、评论区和分享链接的复杂前端应用。

在该决策中,编写测试被约束为三条基本步骤:

  1. 进入 apps/web/tests/e2e 目录;
  2. 以测试名称新建文件,例如 my-test.test.ts;
  3. 运行 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 测试

按照决策文档的步骤,编写测试只需三步:

  1. 进入 apps/web/tests/e2e;
  2. 新建 my-test.test.ts(如属于登录态场景可命名为 my-test.authenticated.ts,未登录场景用 my-test.unauthenticated.ts);
  3. 运行 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:

  1. 用 prisma.user.upsert 按固定邮箱(user@typehero.dev,定义于 apps/web/tests/e2e/constant.ts)创建测试用户,同时连带创建 sessions、roles 与 GitHub oauth accounts 关联记录,session 过期时间设为一个月后;
  2. 通过 page.context().addCookies 向浏览器写入 next-auth.session-token Cookie,使 NextAuth 认为该用户已登录;
  3. 将未登录/已登录两种状态分别导出为 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 逐行检查,即可快速验证新增用例的每一步交互是否符合预期。

登录后查看全文
typehero