# @e2e-dev/web 中文文档

规范地址：https://npmcn.com/package/%40e2e-dev/web/

版本：0\.16\.0
npm 元数据更新时间：2026-11-13T13:28:57.695Z
中文译文更新时间：2026-11-13T13:31:04.537Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40e2e-dev/web
原文对照：https://npmcn.com/package/%40e2e-dev/web/?lang=original
项目主页：https://github.com/e2e-inc/e2e/tree/main/packages/web#readme
源码仓库：https://github.com/e2e-inc/e2e

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：634 kB，93 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.3 \|\| \>=24\.8\.0
- 运行依赖：1 个
- peer 依赖：e2e \>=0\.23\.1 \<1
- 首次发布：2026-09-28T18:46:30.217Z
- 最新版本发布：2026-11-13T13:28:57.316Z
- 近 30 天下载量：2146695（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 52 个）

## 中文简介

用于 e2e 代理端到端测试的 Web 引擎, 建于 Playwright

## 安装

```sh
npm install @e2e-dev/web
```

也可以使用：`pnpm add @e2e-dev/web`、`yarn add @e2e-dev/web`、`bun add @e2e-dev/web`

## README

# @e2e-dev/web (英语)

浏览器引擎 [`e2e`](https://www.npmjs.com/package/e2e),在 [剧作家](https://playwright.dev/)。 。 。 .

`e2e` 没有自己的引擎:每个目标都命名驱动引擎 这个包是浏览器用的 它执行公众 `e2e/engine` 合同,所以一个设备或桌面引擎插件插入到同一个 也没有任何特权.

## 安装

```bash
npm install --save-dev e2e @e2e-dev/web
```

此软件包取决于 `playwright-core` 被钉在一个准确的版本,所以 引擎总是运行 Playwright 它被测试。 取决于应用程序 在 Playwright 上保存自己的副本; 两人只共享浏览器缓存 当他们的版本匹配.

```ts
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';

export default {
  targets: [{ name: 'web', engine: web(), app: { url: 'http://localhost:3000' } }],
} satisfies E2EConfig;
```

目标宣布应用;引擎只驱动. 目标 `app` 带 `url` (基础 URL) `app.open()` 打开; 需要在 `web()` 目标, `command` 跑道在跑道前开始 跑道后停止, 与 `readyUrl` 到民意调查,默认 `url`, (中文(简体) ), `environment` (单位:千美元)`test`, (中文(简体) ), `staging`, (中文(简体) ), `production`;从宿主那里推断的 `identity` (稳定的缓存和 当来源为平时,会话键. `web({ url })` 和另一个老人 应用程序选项是 `INVALID_CONFIG`目标 `app.url` 是一个 `browser` 目标,所以测试可以 `requires: ['browser']`。浏览器选项: `browser` (单位:千美元)`chromium`, (中文(简体) ), `firefox`, (中文(简体) ), `webkit`; 默认 `chromium`; 或 一个 `BrowserProvider` 租赁主机浏览器,见下文), `viewport` (单位:千美元)`{ width, height }`; 默认为 1280x720, `testIdAttribute` (属性) `getByTestId` 和一个节点的 `testId` 已读; 默认 `data-testid`, (中文(简体) ), `userAgent` (单位:千美元) `User-Agent` 每一个尝试发出和 `navigator.userAgent` 报告, `locale` 财务报告和审定财务报表 `timezoneId` (语言和时区 每一次尝试都进入, 例如 `de-DE` 财务报告和审定财务报表 `Europe/Berlin`, (中文(简体) ), `colorScheme` 财务报告和审定财务报表 `reducedMotion` (单位:千美元) `prefers-color-scheme` 财务报告和审定财务报表 `prefers-reduced-motion` 每页报告,来自 第一次油漆; `browser.emulateMedia` 以试验改变他们, `initScripts` (每份文件都标注) 运行在页面本身之前),并且 `connect` 附加到 CDP 上的远程浏览器上, 而不是启动本地 一个.

### 附加到远程浏览器( A)`connect`(中文(简体) )

设定 `connect.cdpEndpoint` 附加在 Chrome DevTools 协议上 而不是发射 解药是响起的,在工人的电话里,在工人的电话里 启动任何发现会话的尝试,所以主机浏览器 结束点为每个运行提供 —— 云会话 URL 在 配置负载——每次需要解决. 解决者收到一个 `AbortSignal` 当它或企图被取消或超过时 预算; 之后连接的浏览器是脱去的, 从未使用 。 CDP 随附 只有铬,而处理引擎会解析会话,没有 关闭主机拥有的远程进程.

```ts
engine: web({
  connect: { cdpEndpoint: async () => acquireCloudBrowserSession() },
});
```

运输回收,加 `connect.reconnectEndpoint(signal)`选择 输入远程浏览器的持续默认上下文. `cdpEndpoint` 接下来 为每次尝试,包括复试,提供新的专用浏览器; `reconnectEndpoint` 断开后必须返回同一浏览器。 这个 引擎验证默认上下文 ID 和活动页面目标 ID, 清除 stale 引用, 绝不重复已发送的操作 。 缺少目标失败 尝试。 主机在清理后拥有删除远程浏览器.

此模式不支持 `headers`, (中文(简体) ), `basicAuth`, (中文(简体) ), `userAgent`, (中文(简体) ), `locale`, (中文(简体) ), `timezoneId`,上下文重设,或会话 州取并还. 重新连接后恢复录制, 但有一个片段 断开时丢失的空格仍然无法使用。 见 [剧作家参考](https://npmcn.com/package/docs/reference/web.mdx#recovering-a-cdp-transport) 寿命周期和所有权合同.

### 租赁主机浏览器( U)`browser`(中文(简体) )

`connect` 没有生命周期: 没有告诉主机何时删除浏览器 它提供。 传出 a `BrowserProvider` 作为 `browser` 而不是发动机 需要浏览器时请求浏览器,当其范围结束时还给浏览器, 在每一个退出路径. `scope: 'worker'` (默认)每个浏览器租赁一个 工间 `prepare` 释放他们 `finish`; 浏览器的工人 放弃租赁 替换本身. `scope: 'attempt'` 租赁新浏览器 每个 `startAttempt` 然后放进去 `endAttempt`,通过 租赁费 `reconnectEndpoint` 在运输量下降之后 `connect.reconnectEndpoint`提供者是指铬并排除 `connect`; 包件中没有销售船. 见 [主机浏览器](https://npmcn.com/package/docs/browser.mdx#hosted-browsers) 合同 以及一个通用会话的范例 API.

```ts
engine: web({
  browser: {
    name: 'hosted-browsers',
    acquire: async (request) => ({ id: session.id, cdpEndpoint: session.cdpUrl }),
    release: async (lease) => stopSession(lease.id),
  },
});
```

## 这个 `browser` 固定图

引擎贡献 `browser`导航 路线 饼干 对话框 框架, 下载、键盘和鼠标,加 `expect(browser).toHaveURL()` 财务报告和审定财务报表 `toHaveTitle()` 财务报告和审定财务报表 `toHaveClass()`导入 `test` 从这个包得到它 键入; 运行时间相同 `test` 作为 `e2e`对.

```ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('signs in', async ({ app, screen, browser }) => {
  await app.open('/login');
  await screen.getByLabel('Email').fill('user@example.test');
  await expect(browser).toHaveURL('/dashboard');
});
```

## 浏览器

每跑一次,在运行过程中,在运行后,一个缺失的浏览器都会被下载 测试在应用程序开始前收集:运行中的进展打印 日志中,运行的时钟仅在下载完成后开始,没有启动或 测试暂停 永远包括它。 工人推出所安装的浏览器.

在CI中,安装浏览器作为自己的步骤,因此成本是可见的,并且 可缓存 :

```bash
npx @e2e-dev/web install chromium --with-deps
```

它下载了 Playwright 版本的浏览器 此软件包的针 发动机的发射 在 pnpm 下,按名称运行本位 : `pnpm exec e2e-web install chromium --with-deps`。 。 。 .

`--with-deps` 还安装系统库中缺少一个瘦小的容器图像.

## 文档

完整文档生活于 [e2e.com/文档](https://e2e.com/docs)。 。 。 .

## 常见问题

### @e2e-dev/web 是什么？

用于 e2e 代理端到端测试的 Web 引擎, 建于 Playwright

### 如何安装 @e2e-dev/web？

在项目目录运行 npm install @e2e-dev/web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：e2e（\>=0\.23\.1 \<1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 e2e-web，可以用 npx e2e-web 直接运行。

### @e2e-dev/web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @e2e-dev/web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @e2e-dev/web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.22\.3 \|\| \>=24\.8\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @e2e-dev/web 可以商用吗？

@e2e-dev/web 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @e2e-dev/web 的下载量有多少？

根据 npm 官方下载统计，@e2e-dev/web 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,146,695 次，日均约 71,557 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @e2e-dev/web 还在维护吗？

最新版本 0\.16\.0 发布于 2026/11/13（今天）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/09/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。