chrome-e2e-sdk 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,740 @@
-# Temporary Holding Version
+# chrome-e2e-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+驱动**你已经登录的那个 Chrome**。
+
+```ts
+import { Browser, expect } from 'chrome-e2e-sdk'
+
+const browser = await Browser.connect()
+const page = await browser.currentPage()
+
+await page.getByRole('button', { name: '登录' }).click()
+await page.getByLabel('密码').fill(process.env.PASSWORD!)
+await expect(page.getByText('欢迎回来')).toBeVisible()
+```
+
+不用全新浏览器 profile，不用重新登录、不用注入 Cookie、不用重写一遍你系统的
+SSO 握手。SDK 连到你屏幕上那个浏览器，然后驱动它。
+
+English version is at the bottom of this file.
+
+## 为什么需要它
+
+Playwright 和 Puppeteer 做浏览器自动化非常优秀。但它们在一个地方按设计就是
+做不好的：**那些你没法用干净 profile 登录的系统。**
+
+如果你的应用在 SSO、内网、VPN、硬件密钥后面，或者只是被公司策略禁止了自动化
+登录，那么一个全新的浏览器 profile 只会给你一个登录页。常见的绕法——storage
+state 文件、Cookie 重放、`baseURL` 凭据头——每种都会在某一类系统上失效，而且
+全都是长期维护负担。
+
+`chrome-e2e-sdk` 换一个立场：**你自己在真实浏览器里手动登录一次，测试去驱动那个
+浏览器。** 会话就是会话。
+
+这也是它包装 [`chrome-devtools-mcp`][mcp] 而不是直接用 Puppeteer 的原因。上游
+已经把"通过 DevTools 协议驱动一个已存在的 Chrome"这件事做干净了，而且有明确的
+版本化工具接口。这个 SDK 在上面加了一层 Playwright 形状的 API、一套断言和一个
+测试 runner，然后不挡路。
+
+**它并不声称浏览器自动化比 Playwright 强。** 它声称的是：有一类系统 Playwright
+够不到，而你不应该为了测它们去自己造一套 Cookie 重放的轮子。
+
+## 安装
+
+```bash
+pnpm add chrome-e2e-sdk
+```
+
+需要 **Node 23+**。`chrome-devtools-mcp` 会作为依赖装上，它的 bin 从本地
+`node_modules` 里解析，不需要全局安装任何东西。
+
+## 前置条件：开启远程调试
+
+`attach` 模式需要 Chrome 允许自动化连接。有两种方式，**推荐先用第一种**。
+
+### 方式一：在日常使用的 Chrome 里开启（Chrome 144+，推荐）
+
+1. 打开 Chrome，在地址栏输入 `chrome://inspect/#remote-debugging`
+2. 打开 **Enable remote debugging for this browser instance**（为当前浏览器实例开启远程调试）
+3. 保持这个 Chrome 正常运行
+
+这样不用重启 Chrome、不用指定 user data directory，你日常的登录态、扩展、
+Cookie 全部原样保留。SDK 默认的 `attach` 模式会自动找到它。
+
+### 方式二：用非默认 profile 手动启动
+
+Chrome 只有在用**非默认** `--user-data-dir` 启动时才会暴露调试端口。
+
+**macOS**
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Linux**
+
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Windows**
+
+```powershell
+& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
+  --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-e2e-profile"
+```
+
+然后在那个窗口里登录你想测的系统。
+
+> 这种方式用的是**另一个 profile**，不是你日常的 Chrome，所以里面没有你的登录态，
+> 需要手动登录一次。方式一没有这个问题。
+
+先关掉其他 Chrome 窗口——同一个 user data directory 同一时间只能被一个浏览器
+持有。任何能访问到这个调试端口的进程都能驱动那个浏览器，请把它当密码看待。
+
+## 两种模式
+
+| | `mode: 'attach'`（默认） | `mode: 'launch'` |
+| --- | --- | --- |
+| 谁启动 Chrome | 你 | MCP server |
+| 用你的登录态 | **是** | 仅当提供持久 `userDataDir` |
+| 需要有人在场 | 否 | 否 |
+| 适合 | 内网系统、SSO、任何有鉴权的 | CI、公开站点、隔离运行 |
+
+```ts
+// 连你已经开着的浏览器
+const browser = await Browser.connect()
+
+// 让 server 自己起 Chrome。给一个 profile 目录让登录态跨次保留——
+// 在 CI 上你会登录一次、seed 一次 localStorage，然后把 profile 提交进仓库。
+const ciBrowser = await Browser.connect({
+  mode: 'launch',
+  userDataDir: '.chrome-e2e-profile',
+  headless: true
+})
+```
+
+不给 `userDataDir` 时，`launch` 用一次性 profile：完全隔离，但也意味着任何需要
+登录的系统都测不了。
+
+> `headless` 只对 `launch` 生效。上游在连接已有浏览器时会**静默忽略**
+> `--headless`，所以 `attach` 模式下传它会直接报错，而不是假装生效。
+
+## API
+
+### 定位
+
+```ts
+await page.getByRole('button', { name: '保存' }).click()
+await page.getByText('订单详情').click()
+await page.getByLabel('手机号').fill('138xxxx0000')
+await page.locator('.table-row').first().click()
+await page.locator('form').getByLabel('邮箱').fill('a@example.com')
+```
+
+`getByLabel` 覆盖真实页面里的各种写法：`aria-label`、`<label for>`、包裹式
+label，以及把 label 元素和输入框并排渲染的组件（`.el-form-item` 这类）。
+
+### 断言
+
+```ts
+import { expect } from 'chrome-e2e-sdk'
+
+// 元素
+await expect(page.getByRole('button', { name: '保存' })).toBeVisible()
+await expect(page.getByRole('button', { name: '保存' })).toBeEnabled()
+await expect(page.getByText('已保存')).toBeVisible()
+await expect(page.locator('.row')).toHaveCount(10)
+await expect(page.getByLabel('邮箱')).toHaveValue('a@example.com')
+
+// 页面
+await expect(page).toHaveTitle('订单')
+await expect(page).toHaveURLContaining('/orders')
+await expect(page).toHaveNoConsoleErrors()
+```
+
+每个断言都会轮询到超时，然后抛出 `AssertionError`，错误信息里带上选择器、期望值
+和最后一次实际观测值。致命错误——MCP 调用失败、浏览器已关闭——会立刻原样抛出，
+不会被重试成一个误导性的超时。
+
+`expect(x).not` 可用，而且否定状态在链式调用中不会丢。
+
+### 网络
+
+```ts
+const response = await page.network.waitForResponse({
+  url: '/api/order/query',
+  resourceTypes: ['Fetch', 'XHR']
+})
+
+expect(response.status).toBe(200)
+expect(JSON.parse(response.body ?? '{}').data).toBeDefined()
+
+const request = await page.network.get(response.requestId)
+expect(request?.requestBody).toContain('page=1')
+```
+
+### 控制台
+
+```ts
+const messages = await page.consoleMessages()
+const first = messages.find((message) => message.type === 'error')
+if (first?.id !== undefined) {
+  const detail = await page.getConsoleMessage(first.id)
+  console.log(detail.args, detail.stackTrace)
+}
+
+await expect(page).toHaveConsoleError(/TypeError/)
+```
+
+### 模拟环境
+
+```ts
+await page.emulate({ networkConditions: 'Slow3G', cpuThrottlingRate: 4 })
+await page.emulate({ userAgent: 'iPhone Safari', viewport: '390x844x3,mobile,touch' })
+await page.clearEmulation()
+```
+
+### 其他
+
+```ts
+await page.screenshot({ fullPage: true })
+await page.locator('.profile-card').screenshot()
+await page.locator('input[type="file"]').setInputFiles('fixtures/avatar.png')
+await page.locator('.source').dragTo(page.locator('.target'))
+await page.waitForText(['下单成功', 'Order placed'])
+await page.fillForm([
+  { label: '邮箱', value: 'a@example.com' },
+  { label: '密码', value: process.env.PASSWORD! }
+])
+await page.localStorage.setItem('token', 'x')
+await page.localStorage.clear()
+await page.evaluate('() => document.title')
+```
+
+## 测试 runner
+
+SDK 自带一个精简 runner，依赖树里没有 Vitest 或 Jest 运行时。
+
+```ts
+import { describe, it, run, summary, expect } from 'chrome-e2e-sdk/test'
+
+describe('订单', () => {
+  it('订单列表', { retries: 1 }, async ({ page }) => {
+    await page.goto('https://internal.example.com/orders')
+
+    await expect(page).toHaveTitle('订单')
+    await expect(page.locator('.row')).toHaveCount(10)
+    await expect(page).toHaveNoConsoleErrors()
+  })
+
+  it.skip('对账', async () => {})
+})
+
+const result = await run()
+await summary(result)
+
+if (result.failed > 0) {
+  process.exitCode = 1
+}
+```
+
+每个用例拿到一个全新的标签页。失败时会记录标题、时间、错误、页面 URL、页面标题、
+console 消息和网络请求，并保存截图：
+
+```
+test-results/
+  screenshots/2026-09-30T07-40-58-618Z-订单-订单列表.png
+  summary.json
+  summary.html
+```
+
+`summary()` 同时产出两份：
+
+- `summary.json` —— 给机器用，CI 判断、脚本统计
+- `summary.html` —— 给人看的报告，`summary()` 返回的就是它的路径
+
+### HTML 报告
+
+单文件、零依赖、离线可打开（CSS 和筛选脚本全部内联），因此可以直接当 CI
+artifact 上传或下载后在浏览器里看。
+
+- 四张统计卡片 + 状态筛选（全部 / 失败 / 通过 / 跳过）
+- 点开失败行可看：断言错误、页面标题与 URL、失败截图、console 消息、网络请求
+- 自动跟随系统的深色 / 浅色
+- 深链接：`summary.html#failed` 只看失败，`#expand-all` 展开全部详情
+- 截图小于 1 MB 时内嵌为 data URI，更大的按相对路径引用，避免报告膨胀到几十 MB
+- console / network 只展示前 30 / 20 条，完整数据仍在 `summary.json` 里
+- 报告自身的文案默认中文，用例标题和浏览器输出保持原文
+
+```ts
+const result = await run()
+await summary(result)
+
+// 换输出目录
+await summary(result, { outputDir: 'artifacts/e2e' })
+
+// 报告文案改成英文
+await summary(result, { locale: 'en' })
+```
+
+也可以在构造 runner 时设成默认：
+
+```ts
+const runner = new TestRunner({ locale: 'en' })
+```
+
+> JUnit XML 尚未产出。如果你的 CI（GitLab、Jenkins、Azure DevOps）只认 JUnit
+> 报告面板，HTML 对它是不可见的。
+
+## 错误
+
+所有失败都是带错误码的 `E2EError`：`CONNECTION_ERROR`、`PAGE_NOT_FOUND`、
+`ELEMENT_NOT_FOUND`、`ELEMENT_NOT_INTERACTABLE`、`TIMEOUT`、
+`NETWORK_TIMEOUT`、`MCP_ERROR`、`ASSERTION_ERROR`、`INVALID_ARGUMENT`、
+`BROWSER_CLOSED`、`NAVIGATION_ERROR`、`SCRIPT_ERROR`、`TOOL_DISABLED`。
+
+```ts
+import { E2EError, E2EErrorCode } from 'chrome-e2e-sdk'
+
+try {
+  await page.getByText('保存').click({ timeout: 2000 })
+} catch (error) {
+  if (error instanceof E2EError && error.code === E2EErrorCode.ELEMENT_NOT_FOUND) {
+    await page.screenshot({ fullPage: true })
+  }
+}
+```
+
+## 调试
+
+```bash
+DEBUG=chrome-e2e npx tsx your-test.ts
+```
+
+## 超时
+
+默认超时是 **30 秒**，覆盖导航、元素操作、断言和网络等待。内网或 VPN 后面一个真实
+页面走到 `load` 很容易超过 5 秒，所以取值偏大。
+
+单次调用可以覆盖：
+
+```ts
+await page.goto(url, { timeout: 60000 })
+await page.getByRole('button', { name: '保存' }).click({ timeout: 5000 })
+await expect(page.getByText('已保存')).toBeVisible({ timeout: 10000 })
+```
+
+全局改：
+
+```ts
+const browser = await Browser.connect({ defaultTimeout: 60000 })
+browser.setDefaultTimeout(60000)
+```
+
+## 刻意不封装的
+
+写在这里是为了让你知道边界，而不是等你用的时候才发现：
+
+- **堆快照**（12 个 `*_heapsnapshot_*` 工具）—— 内存泄漏排查
+- **Lighthouse 与性能 trace** —— 性能审计，不属于 E2E 主链路
+- **Screencast** —— 录屏
+- **扩展、WebMCP、PWA 安装** —— 上游接口面，E2E 场景用不到
+
+## License
+
+MIT
+
+[mcp]: https://github.com/ChromeDevTools/chrome-devtools-mcp
+
+---
+
+# English
+
+Drive **the Chrome you are already logged into**.
+
+```ts
+import { Browser, expect } from 'chrome-e2e-sdk'
+
+const browser = await Browser.connect()
+const page = await browser.currentPage()
+
+await page.getByRole('button', { name: 'Login' }).click()
+await page.getByLabel('Password').fill(process.env.PASSWORD!)
+await expect(page.getByText('Welcome back')).toBeVisible()
+```
+
+No fresh browser profile. No re-login, no cookie injection, no re-implementing
+your app's SSO handshake. The SDK connects to the browser on your screen and
+drives it.
+
+## Why
+
+Playwright and Puppeteer are excellent at browser automation. They are also,
+by design, bad at one thing: **systems you cannot log into from a clean
+profile.**
+
+If your app sits behind SSO, a VPN, an internal network, a hardware key, or
+just a corporate policy that blocks automation logins, a fresh browser profile
+gets you a login page and nothing else. The usual workarounds - storage state
+files, cookie replay, `baseURL` credential headers - each break on a different
+system, and all of them are a maintenance burden.
+
+`chrome-e2e-sdk` takes a different position: **you log in by hand, once, in
+your real browser. The test drives that same browser.** The session is the
+session.
+
+This is also why it wraps [`chrome-devtools-mcp`][mcp] rather than Puppeteer
+directly. That project already solves driving an existing Chrome over the
+DevTools Protocol with a clean, versioned tool surface. This SDK puts a
+Playwright-shaped API on top of it, adds an assertion library and a test runner,
+and gets out of the way.
+
+**It does not claim to automate a browser better than Playwright.** It claims
+that there is a class of system Playwright cannot reach, and that you should
+not have to build a cookie-replay harness to test them.
+
+## Install
+
+```bash
+pnpm add chrome-e2e-sdk
+```
+
+Requires **Node 23+**. `chrome-devtools-mcp` is installed as a dependency and
+its bin is resolved from the local `node_modules`, so there is nothing to
+install globally.
+
+## Prerequisite: remote debugging
+
+`attach` mode talks to a browser that you start yourself, with the DevTools
+protocol enabled. Chrome only exposes that port when it is launched with a
+**non-default** `--user-data-dir`.
+
+**macOS**
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Linux**
+
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Windows**
+
+```powershell
+& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
+  --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-e2e-profile"
+```
+
+### Option 1: enable it in your everyday Chrome (Chrome 144+, recommended)
+
+1. Open Chrome and go to `chrome://inspect/#remote-debugging`
+2. Turn on **Enable remote debugging for this browser instance**
+3. Leave that Chrome running
+
+No restart, no separate user data directory. Your logins, extensions and cookies
+are all still there, and the default `attach` mode finds it on its own.
+
+### Option 2: launch with a non-default profile
+
+Chrome only exposes the debugging port when it starts with a **non-default**
+`--user-data-dir`.
+
+**macOS**
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Linux**
+
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-e2e-profile
+```
+
+**Windows**
+
+```powershell
+& "$env:ProgramFiles\Google\Chrome\Application\chrome.exe" `
+  --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-e2e-profile"
+```
+
+Then log in to whatever you want to test, in that window.
+
+> This is a **different profile** from your everyday Chrome, so it starts with no
+> session and you have to log in once. Option 1 does not have that problem.
+
+Close other Chrome windows first - a user data directory can only be held by one
+browser at a time. Anything that can reach that debugging port can drive that
+browser, so treat it like a password.
+
+## Two modes
+
+| | `mode: 'attach'` (default) | `mode: 'launch'` |
+| --- | --- | --- |
+| Who starts Chrome | you | the MCP server |
+| Uses your logged-in session | **yes** | only with a persistent `userDataDir` |
+| Needs a human present | no | no |
+| Good for | internal apps, SSO, anything behind auth | CI, public sites, hermetic runs |
+
+```ts
+// Attach to the browser you already have open.
+const browser = await Browser.connect()
+
+// Let the server start its own Chrome. Give it a profile directory to keep
+// logins between runs - on CI you would log in once, seed localStorage, and
+// commit the profile.
+const ciBrowser = await Browser.connect({
+  mode: 'launch',
+  userDataDir: '.chrome-e2e-profile',
+  headless: true
+})
+```
+
+Without `userDataDir`, `launch` uses a throwaway profile: fully isolated, and
+nothing behind a login can be tested.
+
+> `headless` only applies to `launch`. `chrome-devtools-mcp` ignores
+> `--headless` when it connects to an existing browser, so passing it with
+> `attach` is rejected rather than silently ignored.
+
+## API
+
+### Locators
+
+```ts
+await page.getByRole('button', { name: 'Save' }).click()
+await page.getByText('Order details').click()
+await page.getByLabel('Phone number').fill('138xxxx0000')
+await page.locator('.table-row').first().click()
+await page.locator('form').getByLabel('Email').fill('a@example.com')
+```
+
+`getByLabel` handles the shapes real pages use: `aria-label`, `<label for>`,
+wrapping labels, and components that render a label element next to the input.
+
+### Assertions
+
+```ts
+import { expect } from 'chrome-e2e-sdk'
+
+// Locator
+await expect(page.getByRole('button', { name: 'Save' })).toBeVisible()
+await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled()
+await expect(page.getByText('Saved')).toBeVisible()
+await expect(page.locator('.row')).toHaveCount(10)
+await expect(page.getByLabel('Email')).toHaveValue('a@example.com')
+
+// Page
+await expect(page).toHaveTitle('Orders')
+await expect(page).toHaveURLContaining('/orders')
+await expect(page).toHaveNoConsoleErrors()
+```
+
+Every assertion polls until the timeout and then throws an `AssertionError`
+carrying the selector, the expected value, and the last observed value. Fatal
+errors - a broken MCP call, a closed browser - are rethrown immediately rather
+than being retried into a misleading timeout.
+
+`expect(x).not` works, and the negation survives chaining.
+
+### Network
+
+```ts
+const response = await page.network.waitForResponse({
+  url: '/api/order/query',
+  resourceTypes: ['Fetch', 'XHR']
+})
+
+expect(response.status).toBe(200)
+expect(JSON.parse(response.body ?? '{}').data).toBeDefined()
+
+const request = await page.network.get(response.requestId)
+expect(request?.requestBody).toContain('page=1')
+```
+
+### Console
+
+```ts
+const messages = await page.consoleMessages()
+const first = messages.find((message) => message.type === 'error')
+if (first?.id !== undefined) {
+  const detail = await page.getConsoleMessage(first.id)
+  console.log(detail.args, detail.stackTrace)
+}
+
+await expect(page).toHaveConsoleError(/TypeError/)
+```
+
+### Emulation
+
+```ts
+await page.emulate({ networkConditions: 'Slow3G', cpuThrottlingRate: 4 })
+await page.emulate({ userAgent: 'iPhone Safari', viewport: '390x844x3,mobile,touch' })
+await page.clearEmulation()
+```
+
+### Other
+
+```ts
+await page.screenshot({ fullPage: true })
+await page.locator('.profile-card').screenshot()
+await page.locator('input[type="file"]').setInputFiles('fixtures/avatar.png')
+await page.locator('.source').dragTo(page.locator('.target'))
+await page.waitForText(['Order placed', '下单成功'])
+await page.fillForm([
+  { label: 'Email', value: 'a@example.com' },
+  { label: 'Password', value: process.env.PASSWORD! }
+])
+await page.localStorage.setItem('token', 'x')
+await page.localStorage.clear()
+await page.evaluate('() => document.title')
+```
+
+## Test runner
+
+A small runner ships with the SDK, so there is no Vitest or Jest runtime in the
+dependency tree.
+
+```ts
+import { describe, it, run, summary, expect } from 'chrome-e2e-sdk/test'
+
+describe('Orders', () => {
+  it('lists orders', { retries: 1 }, async ({ page }) => {
+    await page.goto('https://internal.example.com/orders')
+
+    await expect(page).toHaveTitle('Orders')
+    await expect(page.locator('.row')).toHaveCount(10)
+    await expect(page).toHaveNoConsoleErrors()
+  })
+
+  it.skip('reconciliation', async () => {})
+})
+
+const result = await run()
+await summary(result)
+
+if (result.failed > 0) {
+  process.exitCode = 1
+}
+```
+
+Each test gets a fresh tab. A failure records the title, time, error, page URL,
+page title, console messages and network requests, and saves a screenshot:
+
+```
+test-results/
+  screenshots/2026-09-30T07-40-58-618Z-Orders-lists-orders.png
+  summary.json
+  summary.html
+```
+
+`summary()` produces both:
+
+- `summary.json` for machines: CI gating, scripted stats
+- `summary.html` for people, and this is the path it returns
+
+### HTML report
+
+One self-contained file with no dependencies that opens offline (styles and the
+filter script are inlined), so it can be uploaded as a CI artifact and opened
+straight from the download.
+
+- Four stat cards plus a status filter (all / failed / passed / skipped)
+- Expanding a failed row shows the assertion error, page title and URL, the
+  failure screenshot, console messages and network requests
+- Follows the system light or dark preference
+- Deep links: `summary.html#failed` filters to failures, `#expand-all` opens
+  every detail
+- Screenshots under 1 MB are inlined as data URIs; larger ones are referenced by
+  relative path so the report cannot balloon to tens of megabytes
+- Console and network show the first 30 and 20 entries; the full payloads stay
+  in `summary.json`
+- The report's own labels are Chinese by default. Test titles and browser output
+  are data, not chrome, so they are always shown verbatim
+
+```ts
+const result = await run()
+await summary(result)
+
+// different output directory
+await summary(result, { outputDir: 'artifacts/e2e' })
+
+// English report chrome
+await summary(result, { locale: 'en' })
+```
+
+Or set it as the default for a runner:
+
+```ts
+const runner = new TestRunner({ locale: 'en' })
+```
+
+> JUnit XML is not produced yet. If your CI (GitLab, Jenkins, Azure DevOps) only
+> reads JUnit report panels, it will not see this HTML.
+
+## Errors
+
+Every failure is an `E2EError` with a code: `CONNECTION_ERROR`,
+`PAGE_NOT_FOUND`, `ELEMENT_NOT_FOUND`, `ELEMENT_NOT_INTERACTABLE`, `TIMEOUT`,
+`NETWORK_TIMEOUT`, `MCP_ERROR`, `ASSERTION_ERROR`, `INVALID_ARGUMENT`,
+`BROWSER_CLOSED`, `NAVIGATION_ERROR`, `SCRIPT_ERROR`, `TOOL_DISABLED`.
+
+```ts
+import { E2EError, E2EErrorCode } from 'chrome-e2e-sdk'
+
+try {
+  await page.getByText('Save').click({ timeout: 2000 })
+} catch (error) {
+  if (error instanceof E2EError && error.code === E2EErrorCode.ELEMENT_NOT_FOUND) {
+    await page.screenshot({ fullPage: true })
+  }
+}
+```
+
+## Debugging
+
+```bash
+DEBUG=chrome-e2e npx tsx your-test.ts
+```
+
+## Timeouts
+
+The default is **30 seconds**, covering navigation, element actions, assertions
+and network waits. A page behind a VPN or an internal network routinely takes
+longer than five seconds to reach `load`, so the default is generous on purpose.
+
+Override per call:
+
+```ts
+await page.goto(url, { timeout: 60000 })
+await page.getByRole('button', { name: 'Save' }).click({ timeout: 5000 })
+await expect(page.getByText('Saved')).toBeVisible({ timeout: 10000 })
+```
+
+Or globally:
+
+```ts
+const browser = await Browser.connect({ defaultTimeout: 60000 })
+browser.setDefaultTimeout(60000)
+```
+
+## Not wrapped
+
+Deliberately, and listed so you know the boundary rather than discovering it:
+
+- **Heap snapshots** (12 `*_heapsnapshot_*` tools) - memory leak debugging
+- **Lighthouse and performance traces** - performance auditing, not E2E
+- **Screencast** - video recording
+- **Extensions, WebMCP, PWA install** - upstream surface with no E2E use case
+  here
+
+## License
+
+MIT