1. 为什么 Playwright + Claude Code 值得你花一个下午跑通
如果你正在做 Web 前端或全栈项目，大概率听过 E2E 测试这个词，也大概率被 Selenium 那套等待、驱动、元素定位折磨过。Playwright 是微软开源的浏览器自动化框架，一套 API 同时驱动 Chromium、Firefox、WebKit，自带自动等待、网络拦截、Trace 回放，写起来比 Selenium 顺手很多。Claude Code 是 Anthropic 推出的命令行编程助手，它和普通聊天式 AI 最大的区别是能读取你项目里的真实文件结构、依赖版本、目录约定，再基于这些上下文生成代码。
把这两个东西放一起，能解决一个很具体的痛点：写 E2E 测试最烦的不是断言逻辑，而是样板代码——打开页面、定位元素、处理等待、组织 Page Object。这些恰好是 AI 有上下文时最擅长补全的部分。而 Playwright 的语义化 API（getByRole、getByTestId、expect(locator).toBeVisible()）又让生成出来的代码可读性足够高，你 Review 起来不费劲。
这篇文章面向的是需要快速落地 E2E 测试的开发者，尤其是校招测开方向、想拿一个完整项目讲清楚"我怎么用 AI 提效"的同学。我会从零开始，把 Claude Code 的配置、Playwright 的脚本模板、通过 TaoToken 统一通道接入的验证步骤全部走一遍，最后给你一份能直接抄的排错清单。全程不需要你已经有测试框架基础，跟着敲就行。
需要先说明一点：AI 生成测试代码的质量，取决于你给它的约束有多清楚。指望一句"帮我写个登录测试"就拿到能跑的脚本，基本会失望。所以下面的流程里，我会把"怎么让 AI 理解项目"当成第一步重点讲，这一步做扎实，后面省的时间是成倍的。
2. 前置准备：TaoToken 统一 Key 与 Claude Code 接入配置
在写第一行测试之前，先把工具链的通道打通。Claude Code 默认走 Anthropic 官方接口，但很多同学会遇到额度、网络、多模型切换的问题。TaoToken 提供的是一个统一的 API 通道，你可以在一个 Key 下调用包括 Claude 系列在内的多种模型，配置方式兼容 Anthropic 的接口协议，所以 Claude Code 可以直接对接。
先注册并拿到 Key。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，完成账号注册后进入控制台，在 API Keys 页面创建一个新 Key。这个 Key 就是后面所有配置里要填的凭证，格式通常是一串以sk-开头的字符串。创建后立刻复制保存，页面刷新后不一定能再看到完整值。
拿到 Key 之后，进入控制台确认你要用的模型 ID。TaoToken 的模型列表里会标注每个模型的调用名称，比如 Claude 系列会有对应的 model id。这个 ID 后面要写进 Claude Code 的配置里，写错了会直接报模型不存在。
接下来是 Claude Code 的安装。如果你还没装，用 npm 全局安装即可：
npm install -g @anthropic-ai/claude-code安装完成后，Claude Code 会读取环境变量或配置文件来决定请求发往哪里。我们要做的是把 Base URL 指向 TaoToken 的 API 地址，把 Key 换成刚创建的。TaoToken 的 API 根地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置时直接用它作为 base。
配置有两种方式，选一种就行。第一种是环境变量，适合临时切换：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"第二种是写进 Claude Code 的配置文件，适合长期使用。配置文件一般位于用户目录下的.claude文件夹，具体路径可以用claude config相关命令查看。写入的内容包括 base_url、api_key 和默认模型。这里要提醒一句：不同版本的 Claude Code 配置字段名可能略有差异，以你本地claude --help或官方文档为准，但核心三件套永远是 Base URL、Key、Model ID。
配置完成后，先在项目根目录跑一次claude命令，看它能不能正常启动并识别到模型。如果启动时报 401，说明 Key 没生效；如果报连接失败，检查 Base URL 是否写成了带路径的形式。这一步通了，再往下走 Playwright。
Playwright 的安装更简单，在项目里执行：
npm init playwright@latest这个命令会引导你选择 TypeScript 还是 JavaScript、测试目录放哪、要不要装浏览器。建议选 TypeScript，因为类型提示能让 AI 生成的代码更准确。安装过程会自动下载 Chromium 等浏览器二进制，网络慢的话耐心等一会。
到这里，Claude Code 和 Playwright 都就位了。下一节开始写真正能跑的配置和脚本。
3. 可复制配置：CLAUDE.md、settings 与 Playwright 脚本模板
这一节是全文最核心的部分，所有片段都可以直接复制到你的项目里改。先说 Claude Code 的配置，再说 Playwright 的脚本结构。
Claude Code 读取项目上下文的关键，是根目录下的CLAUDE.md文件。这个文件相当于给 AI 的一份项目说明书，它每次生成代码前都会读。很多人跳过这一步直接让 AI 写脚本，结果生成的代码用了错误的目录、错误的断言风格，返工成本很高。我的做法是把项目约束写清楚：
## 项目信息 - 前端：React + TypeScript + Vite - 测试框架：Playwright - 测试目录：tests/e2e/ - Base URL：http://localhost:3000 - 包管理器：pnpm ## 测试规范 - 使用 Page Object 模式，页面对象放 tests/e2e/pages/ - 优先使用>{ "model": "claude-sonnet-4-20250514", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的Key" }, "permissions": { "allow": ["Read", "Write", "Bash(npm run test:*)"], "deny": ["Bash(rm:*)"] } }这里的 model 字段填你在 TaoToken 控制台看到的模型 ID，env 里放 Base URL 和 Key，permissions 控制 Claude Code 能执行哪些操作。把Bash(npm run test:*)加进 allow，它就能帮你跑测试并读报错，这个后面排错时会很有用。注意 Key 不要提交到 Git，把 settings.json 加进 .gitignore，或者用环境变量注入。
然后是 Playwright 的脚本模板。先建一个 Page Object，把登录页的操作封装起来：
// tests/e2e/pages/LoginPage.ts import { Page, Locator, expect } from '@playwright/test'; export class LoginPage { readonly page: Page; readonly usernameInput: Locator; readonly passwordInput: Locator; readonly submitButton: Locator; readonly errorMessage: Locator; constructor(page: Page) { this.page = page; this.usernameInput = page.getByTestId('username'); this.passwordInput = page.getByTestId('password'); this.submitButton = page.getByTestId('login-submit'); this.errorMessage = page.getByTestId('login-error'); } async goto() { await this.page.goto('/login'); } async login(username: string, password: string) { await this.usernameInput.fill(username); await this.passwordInput.fill(password); await this.submitButton.click(); } async expectError(text: string) { await expect(this.errorMessage).toBeVisible(); await expect(this.errorMessage).toHaveText(text); } }再写测试用例，覆盖正常登录和异常场景：
// tests/e2e/login.spec.ts import { test, expect } from '@playwright/test'; import { LoginPage } from './pages/LoginPage'; test.describe('登录流程', () => { let loginPage: LoginPage; test.beforeEach(async ({ page }) => { loginPage = new LoginPage(page); await loginPage.goto(); }); test('正确账号密码可以登录成功', async ({ page }) => { await loginPage.login('testuser', 'correct-password'); await expect(page).toHaveURL(/\/dashboard/); await expect(page.getByTestId('welcome')).toBeVisible(); }); test('密码错误时展示错误提示', async () => { await loginPage.login('testuser', 'wrong-password'); await loginPage.expectError('用户名或密码错误'); }); test('空提交时阻止登录', async () => { await loginPage.login('', ''); await expect(loginPage.errorMessage).toBeVisible(); }); });最后是 Playwright 的配置文件，把 baseURL 和浏览器参数固定下来：
// playwright.config.ts import { defineConfig, devices } from '@playwright/test'; export default defineConfig({ testDir: './tests/e2e', timeout: 30000, retries: process.env.CI ? 2 : 0, use: { baseURL: 'http://localhost:3000', trace: 'on-first-retry', screenshot: 'only-on-failure', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, ], });这套配置下来，你的项目就有了完整的测试骨架。把 CLAUDE.md、settings.json、Page Object、spec 文件都放好，再让 Claude Code 基于这个结构补用例，生成质量会明显不一样。
4. 验证请求：跑通第一个测试用例并确认通道生效
配置写完了，现在要验证两件事：Claude Code 能不能通过 TaoToken 正常生成代码，Playwright 能不能真的把测试跑起来。这两步分开验证，出问题好定位。
先验证 Claude Code 的通道。在项目根目录打开终端，输入claude进入交互模式，然后问一个和项目相关的问题，比如"读一下 tests/e2e/login.spec.ts，告诉我这个测试覆盖了哪些场景"。如果它能正确读取文件并回答，说明 Base URL 和 Key 都生效了。如果报 401，回到上一节检查 Key 是否复制完整；如果报模型不存在，检查 settings.json 里的 model 字段是否和控制台一致。
通道确认后，让 Claude Code 帮你补一个测试用例，比如"给 LoginPage 加一个记住我勾选框的操作，并写一个测试验证勾选后刷新页面仍然保持登录态"。观察它生成的代码是否用了>npx playwright test tests/e2e/login.spec.ts --headed
--headed参数会让浏览器可见，方便你观察每一步操作。第一次跑大概率会有失败，这很正常。重点看报错信息：如果是选择器找不到，说明>Running 3 tests using 1 worker ✓ 登录流程 › 正确账号密码可以登录成功 (2.1s) ✓ 登录流程 › 密码错误时展示错误提示 (1.8s) ✓ 登录流程 › 空提交时阻止登录 (1.5s) 3 passed (5.4s)
看到 3 passed，说明从配置到脚本的整条链路通了。这时候你可以把报错信息直接丢给 Claude Code，让它参与修复。比如把 Playwright 的失败输出粘贴进去，问"这个选择器超时是什么原因，帮我改一下 LoginPage"。它读到项目文件后，通常能给出针对性的修改，而不是泛泛而谈。
还有一个验证技巧：用 Playwright 的 codegen 生成初始选择器。执行npx playwright codegen http://localhost:3000/login，它会打开浏览器并记录你的操作，自动生成定位代码。你可以把生成的代码交给 Claude Code，让它重构成 Page Object 风格。这样既保证了选择器准确，又保持了代码结构统一。
通道和脚本都验证通过后，建议把测试接入 CI。在 GitHub Actions 里加一个 workflow，每次 push 自动跑 E2E：
name: e2e on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v4 - run: pnpm install - run: npx playwright install --with-deps - run: pnpm dev & - run: npx playwright testCI 里的测试不追求 100% 稳定，flaky 是常态。目标是让核心流程每次都能过，边缘用例允许重试。Playwright 配置里的retries就是干这个的。
5. 常见报错排查：401、local proxy failed、reading choices 与 OAuth
这一节把你会真实撞到的报错列出来，对照着改。每个报错我都写清楚现象、原因和修法。
401 Unauthorized。现象是 Claude Code 启动或请求时直接返回 401。原因通常是 Key 没生效。检查顺序：第一，确认ANTHROPIC_API_KEY环境变量或 settings.json 里的 Key 是完整的，没有多余空格；第二，确认 Key 没有过期或被删除，回 TaoToken 控制台看一眼；第三，确认 Base URL 写的是 https://taotoken.net/api ，没有多写/v1之类的路径。如果环境变量和配置文件同时存在，环境变量优先级更高，检查是不是旧的 Key 覆盖了新的。
local proxy failed / connection refused。现象是请求发不出去，提示本地代理失败或连接被拒。这通常是环境里残留了代理设置，或者 Base URL 指向了本地端口。检查HTTP_PROXY、HTTPS_PROXY环境变量是否被设置成了本地地址，如果有就 unset 掉。同时确认 Base URL 是公网地址而不是http://localhost:xxxx。Claude Code 的配置里如果混入了旧的代理配置，也会导致这个问题，把 settings.json 里多余的 env 字段清掉。
reading 'choices' of undefined。这个报错一般出现在用 OpenAI 兼容格式调用时，响应结构不符合预期。原因是模型 ID 写错了，或者请求发到了不支持该模型的端点。回 TaoToken 控制台核对模型 ID 的准确拼写，注意大小写和版本号。另外确认你用的接口协议和模型匹配，Claude 系列走 Anthropic 协议，不要混用 OpenAI 的请求格式。
OAuth 相关报错。现象是提示需要登录或 token 无效。Claude Code 某些版本会尝试 OAuth 流程，如果你用的是 API Key 模式，需要在配置里明确指定认证方式，避免它走 OAuth。检查 settings.json 里是否有auth相关字段，把它设成 api_key 模式。如果还是报错，用claude config命令查看当前认证状态，必要时重置配置重新填 Key。
Playwright 选择器超时。现象是locator.click: Timeout 30000ms exceeded。原因通常是元素没渲染出来，或者选择器写错了。先用--headed模式跑，肉眼确认元素是否存在。如果元素在但定位不到，检查 data-testid 是否拼写一致。如果是动态加载的元素，用await expect(locator).toBeVisible()替代固定等待，Playwright 会自动重试直到超时。
测试之间互相污染。现象是单个跑能过，一起跑就失败。原因是用例之间有隐式依赖，比如前一个用例登录了，后一个用例默认已登录。修法是每个用例用beforeEach重置状态，或者在测试里显式登出。Playwright 默认每个测试用独立的 browser context，但如果你在测试间共享了 storageState，就要注意清理。
CI 里失败本地能过。现象是本地全绿，CI 上挂。常见原因是 CI 环境没有启动开发服务器，或者浏览器依赖没装。确认 workflow 里有npx playwright install --with-deps，并且测试前开发服务器已经起来。可以用wait-on之类的工具等端口就绪再跑测试。
把这份清单存下来，遇到报错先对照，大部分问题五分钟内能定位。剩下的交给 Claude Code，把报错原文贴给它，让它读项目文件后给修改建议，比你自己翻文档快。
6. 把这条链路用起来：从单用例到可持续的测试体系
跑通第一个用例只是起点。真正有价值的是把这条链路变成日常开发的一部分。我的做法是每加一个新功能，先让 Claude Code 读一遍相关组件代码，生成对应的 Page Object 和测试骨架，然后我补断言和边界场景。这样写测试的成本从"从零手写"降到"改 AI 的初稿"，一个中等复杂度的页面，半小时能出一版可跑的用例。
关于效率，说个实在的数字。登录这种简单流程，以前手写加调试大概两三个小时，现在生成加 Review 四十分钟左右。完整页面的 E2E，以前一两天，现在几个小时。但这不是让你少思考，测试场景怎么设计、断言覆盖到什么程度、哪些边界必须测，这些判断还是得你自己做。AI 省掉的是重复编码和查 API 的时间。
如果你想把这条链路用得更顺，建议把常用的 Playwright 片段沉淀成项目里的模板文件，让 Claude Code 每次生成时参考。比如把 Page Object 的标准写法、断言的常用组合、测试数据的组织方式都放进 CLAUDE.md 或单独的模板目录。上下文越具体，生成质量越稳定。
最后给一个可以直接开始的行动项：挑你项目里最核心的一个流程，比如登录或下单，按这篇文章的步骤走一遍。先写 CLAUDE.md，再配 TaoToken 的 Key 和 Base URL，然后用 codegen 抓选择器，让 Claude Code 重构成 Page Object，跑通后接进 CI。整个过程一个下午够了。跑通之后你会发现，E2E 测试不再是负担，而是你改代码时的安全网。
需要 Key 和接入文档的话，从 API Keys 页面创建，接入细节看文档页；想先验证模型对话效果，用模型对话页面试几句；如果打算长期用 Claude Code 做编码和 Agent 任务，Coding Plan 会更划算。通道配好，剩下的就是动手写第一个用例了。
