# @codepress/interactions-playwright 中文文档

规范地址：https://npmcn.com/package/%40codepress/interactions-playwright/

版本：1\.1\.0
npm 元数据更新时间：2026-11-05T22:22:41.105Z
中文译文更新时间：2026-11-10T07:39:19.569Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40codepress/interactions-playwright
原文对照：https://npmcn.com/package/%40codepress/interactions-playwright/?lang=original
项目主页：https://github.com/quantfive/codepress-interactions#readme
源码仓库：https://github.com/quantfive/codepress-interactions

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

- 包体积（解压后）：29.7 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@playwright/test \>=1\.40
- 首次发布：2026-11-05T15:47:56.233Z
- 最新版本发布：2026-11-05T22:22:40.750Z
- 近 30 天下载量：2793（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

运行 CodePress 交互功能的 Playwright 助手在测试中检查: 抓取快照, 列出发现, 断言无

## 安装

```sh
npm install @codepress/interactions-playwright
```

也可以使用：`pnpm add @codepress/interactions-playwright`、`yarn add @codepress/interactions-playwright`、`bun add @codepress/interactions-playwright`

## README

# @ codepress/ interactions- playwrit

运行此程序的 Playwright 助手 [代码Press 交互](https://github.com/quantfive/codepress-interactions/blob/main/README.md) UI检查被测试的一页:重叠元素,内容溢出其框外,水平页面卷轴,控制无法到达,小自带目标(touch),被剪接的文本和被打碎的图像.

```sh
npm install --save-dev @codepress/interactions-playwright
```

```ts
import { test } from "@playwright/test";
import { expectNoFindings, findIssues } from "@codepress/interactions-playwright";

test("checkout has no layout findings", async ({ page }) => {
  await page.goto("/checkout/42");
  await expectNoFindings(page, { routeSegments: ["checkout"] });
});
```

失败列出每个发现的一行: 检查、 元素( 测试 ID, 或结构路径, 如 `#cart/div/button` 证据和指纹.

```
2 UI findings on /checkout/42. Pass a fingerprint in ignoreFingerprints to accept one.
  "layout.overlap checkout × promo on /checkout/:id @1280x800: overlap_px=3520 … subject_blocked_points=5 … center_blocked subject_text_covered … [590f6922417e2a04f8d6c9341daf02c1]"
```

发现是指针,不是判断:每个判断都说出所测量的,你来决定它是不是个错误. 排序先放被屏蔽的控件,再覆盖或剪接文本,再放其他的,再放装饰层和无内容的发现(被打碎或被裁剪的图像);它从不掉一个.

## API 密码

-   `captureSnapshot(page, options?)` → `{ body, sha256 }`:用SDK的快照行走器一行一行行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一行一.
-   `findIssues(page, options?)` → `Finding[]`: 页面上现在的检查, 排序 .
-   `expectNoFindings(page, options?)`: 测试失败 `findIssues` 返回任何内容.

选项( 所有选项) :

| 选项 | 默认 |  |
| --- | --- | --- |
| `root` | 整个文档 | CSS 子树选择器 |
| `ignore` | 无 | 额外选取子树以忽略; `[data-layout-ignore]` 永远适用 |
| `route` | 从 URL 中 | 记录在调查结果上并由指纹使用的路由模板 |
| `routeSegments` | `[]` | 在默认路由模板中保存的正文路径段( 其他成为) `:id`(中文(简体) ) |
| `maxElements` | 5万块 | 元素限制 |
| `theme` | 页面 `prefers-color-scheme` | `"light"`, (中文(简体) ), `"dark"` 或者说 `"unknown"` 要记录, 对于带有自己主题切换的应用程序( Playwright ) `colorScheme` 编号 : `page.emulateMedia` 设置默认值) |
| `testId` | `defaultTestIdFilter` | `(value, element) => string | null`: 哪个 `data-interaction-id` 编号 : `data-testid` 要记录的值, 作为浏览器 SDK 的 [`testId` 选项](https://github.com/quantfive/codepress-interactions/blob/main/packages/browser/README.md#test-ids-and-privacy)。它在页面中运行,所以它必须是自成一体的,就像 `page.evaluate` callback; 页面没有失败抓取的名称 。 页面确实有一个名称, 例如测试变量叫做 `status`,或者钩子中的任何其他运行时间出错,在无出错的情况下放下ID,所以在写钩子时检查快照的ID. 写出你的应用程序使用的规则 这样指纹匹配生产,呼叫 `globalThis.__codepressInteractions.defaultTestIdFilter(value)` 在那里它称之为默认. `(value) => value` 保存每个身份 |
| `ignoreFingerprints` | `[]` | (目前接受已知调查结果) |
| `events` | 无 | 协议 v2 事件来运行点击和稳定性检查 |
| `checks` 和阈值 | 见 [检测选项](https://github.com/quantfive/codepress-interactions/blob/main/packages/browser/README.md#ui-checks) |  |

指纹在滚动抵消,运行和机器之间是稳定的:它们将检查,路由模板,取景口宽幅带和元素的身份,永远不坐标.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @codepress/interactions-playwright 是什么？

运行 CodePress 交互功能的 Playwright 助手在测试中检查: 抓取快照, 列出发现, 断言无

### 如何安装 @codepress/interactions-playwright？

在项目目录运行 npm install @codepress/interactions-playwright，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@playwright/test（\>=1\.40）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @codepress/interactions-playwright 支持 TypeScript 吗？

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

### @codepress/interactions-playwright 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @codepress/interactions-playwright 可以商用吗？

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

### @codepress/interactions-playwright 的下载量有多少？

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

### @codepress/interactions-playwright 还在维护吗？

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