# @checkly/playwright-reporter 中文文档

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

版本：1\.15\.0
npm 元数据更新时间：2026-10-26T08:54:12.021Z
中文译文更新时间：2026-11-09T11:42:22.387Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40checkly/playwright-reporter
原文对照：https://npmcn.com/package/%40checkly/playwright-reporter/?lang=original

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

- 包体积（解压后）：307 kB，10 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：5 个
- peer 依赖：@playwright/test \>=1\.40\.0
- 首次发布：2025-10-21T12:46:38.133Z
- 最新版本发布：2026-10-26T08:54:11.769Z
- 近 30 天下载量：32101（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：99（近 12 个月 87 个）

## 中文简介

Checkly的独立 Playwright记者 - 兼容 Playwright 1.40-1.64+

## 安装

```sh
npm install @checkly/playwright-reporter
```

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

## README

# @ checkly/ playwright-reporter (帮助) @ info: whatsthis

Checkly的Playwright官方记者. 自动上传测试结果,截图,视频,和痕迹,以获得对端测试的能见度.

**完全兼容 Playwright 的内置 JSON 记者** - 使用它作为临时替代,增加Checkly集成.

## 安装

```bash
npm install --save-dev @checkly/playwright-reporter
```

**所需经费:**

-   节点20.19+或22.12+
-   剧作家 >= 1.4.0.0
-   A 类 [支票账户](https://app.checklyhq.com/)

## 快速启动

### 1\. 获得全权证书

1.  转到 **账户设置 > 常规** 查找您的账户ID
2.  转到 **用户设置 > API 密钥** 创建 API 密钥

### 2\. 配置剧作家

将记者添加到您的 `playwright.config.ts`数字 :

```typescript
import { defineConfig } from '@playwright/test';
import { createChecklyReporter } from '@checkly/playwright-reporter';

export default defineConfig({
  reporter: [
    ['list'],
    createChecklyReporter(),
  ],
});
```

> **提示 :** 使用 `createChecklyReporter()` 为配置选项提供全智能。 或者使用数组语法 : `['@checkly/playwright-reporter', { ... }]`

### 3\. 设置环境变量

```bash
export CHECKLY_API_KEY=your_api_key
export CHECKLY_ACCOUNT_ID=your_account_id
```

或者用内线通过他们:

```bash
CHECKLY_API_KEY=... CHECKLY_ACCOUNT_ID=... npx playwright test
```

### 4\. 运行测试

```bash
npx playwright test
```

您可以在输出中看到会话 URL :

```
View test results: https://app.checklyhq.com/test-sessions/abc123

[...test execution...]

✓ Check the results: https://app.checklyhq.com/test-sessions/abc123
```

## 配置选项

```typescript
import { createChecklyReporter } from '@checkly/playwright-reporter';

createChecklyReporter({
  outputDir: 'test-results',
  sessionName: 'My Test Suite',
  dryRun: false,
  verbose: false,
  showProgress: true,
  showSummaryTable: true,
})
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | `CHECKLY_API_KEY` 环境 var | 检查 API 密钥 |
| `accountId` | `string` | `CHECKLY_ACCOUNT_ID` 环境 var | 检查账户 ID |
| `outputDir` | `string` | 剧作家 `outputDir` | JSON和ZIP资产目录 |
| `sessionName` | `string | function` | 自动生成 | 自定义会话名称 |
| `dryRun` | `boolean` | `false` | 不上传而创建 ZIP |
| `verbose` | `boolean` | `false` | 启用调试日志 |
| `showProgress` | `boolean` | `true` | 在终端显示实时测试进度 |
| `printSteps` | `boolean` | `false` | 打印单个测试步骤( 要求) `showProgress`(中文(简体) ) |
| `showSummaryTable` | `boolean` | `true` | 运行后显示每个项目的细分表 |
| `scrubbing` | `object | false` | 见 [偷窥秘密](https://npmcn.com/package/%40checkly/playwright-reporter/#readme-secret-scrubbing) | 配置报告和痕迹的秘密擦拭 |
| `testCommand` | `string` | 自动检测 | 覆盖在 Ccheckly UI 中显示的测试命令 |
| `webVitals` | `boolean` | `false` | 通过仪器浏览器上下文来收集核心网络维度(LCP,CLS,INP,FCP,TTFB,TTCT);结果出现在Checkly报告中. 在 Checkly 的跑道上运行时默认存在 |

**输出文件** (写信给 `outputDir`:

-   `checkly-report.json` - JSON测试报告
-   `checkly-report.zip` - 有报告和资产的ZIP档案

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `CHECKLY_API_KEY` | 您的 checkly API 密钥 |
| `CHECKLY_ACCOUNT_ID` | 您的支票账户 ID |
| `CHECKLY_REPORTER_VERBOSE` | 设定为 `true` 详细调试输出 |
| `CHECKLY_REPORTER_DRY_RUN` | 设定为 `true` 要跳过上传 |
| `CHECKLY_REPORTER_OUTPUT_DIR` | 覆盖输出目录 |
| `CHECKLY_REPORTER_SHOW_SUMMARY_TABLE` | 设定为 `false` 以隐藏总表 |
| `CHECKLY_REPORTER_WEB_VITALS` | 设定为 `false` 以禁用 Core Web Virtuals 收藏( kill switch; 默认在 Checkly 的跑取器上使用 ) |
| `CHECKLY_TEST_COMMAND` | 覆盖在 Ccheckly UI 中显示的测试命令 |

环境变量优先于配置中通过的选项.

## 上传什么

-   测试结果和状况(通过/失败/故障)
-   执行期限和时间
-   截图(关于失败或明确捕获)
-   录像
-   剧作家追踪
-   控制台日志和网络请求(取自痕迹)

## 偷窥秘密

记者在上传前会自动从JSON报告中去除敏感值,跟踪文件,附件和日志.

默认情况下,任何名称以 `CHECKLY_SECRET_` 被擦干净。 您可以配置额外的擦除策略 :

```typescript
createChecklyReporter({
  scrubbing: {
    envVars: ['DB_PASSWORD', 'STRIPE_KEY'],
    autoDetect: true,
    prefix: 'CHECKLY_SECRET_',
    replacement: '[REDACTED]',
  },
})
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `envVars` | `string[]` | `[]` | 应去除运行时间值的环境可变名称 |
| `autoDetect` | `boolean` | `false` | Scrub env vars 匹配常见的秘密模式( SECRET, 关键, TOKEN, PASWORD, 认证, AUTH, Private, API) |
| `prefix` | `string | false | null` | `'CHECKLY_SECRET_'` | 从这个前缀开始,将所有嵌入式 vars 全部清除. 设定为 `false` 或者说 `''` 无法禁用 |
| `replacement` | `string` | `'*********'` | 自定义擦除器值的替换字符串 |
| `unscrubbableTraces` | `'reject' | 'upload'` | `'reject'` | 和无法完全抹去秘密的痕迹有什么关系 `'reject'` 把它从上传中留下, `'upload'` 上传为记录, 包含秘密, 并登录警告 |

设定 `scrubbing: false` 完全禁用洗涤.

## 模糊测试检测

记者自动检测出片状测试:

-   **模糊测试**: 初始失败但在重试后通过的测试
-   **有辱人格的地位**: 当有片状测试但没有完全失败时设定
-   **总体状况**数字 : `passed` 如果所有的测试最终通过, `failed` 否则

## 本地运行( 无上传)

对于本地开发而不上传到Checkly:

```bash
# Simply don't set CHECKLY_API_KEY or CHECKLY_ACCOUNT_ID
npx playwright test
```

发生什么了

-   记者打印证书缺失并跳过上传
-   测试正常运行
-   与 `outputDir` 设置, 记者会写一个刷子 `checkly-report.json` 那边

为了得到 `checkly-report.zip` 本地, 使用 [干线运行模式](https://npmcn.com/package/%40checkly/playwright-reporter/#readme-dry-run-mode)。 。 。 .

## 干运行模式

不上传而创建本地 JSON 和 ZIP 文件 :

```typescript
createChecklyReporter({
  dryRun: true,
})
```

有条件的干跑( 无证书时会上传 ) :

```typescript
createChecklyReporter({
  dryRun: !process.env.CHECKLY_API_KEY,
})
```

## CI/CD 一体化

### GitHub 动作

```yaml
name: Playwright Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }}
        run: npx playwright test
```

### GitLab CI 语录

```yaml
test:
  image: mcr.microsoft.com/playwright:v1.57.0-jammy
  stage: test
  script:
    - npm ci
    - npx playwright test
  variables:
    CHECKLY_API_KEY: $CHECKLY_API_KEY
    CHECKLY_ACCOUNT_ID: $CHECKLY_ACCOUNT_ID
```

**设置变量 :**

1.  转到您的 GitLab 项目
2.  导航到设置 > CI/CD > 变量
3.  添加 `CHECKLY_API_KEY` (检查"任务变量")
4.  添加 `CHECKLY_ACCOUNT_ID` (检查"任务变量")

## 多个记者

与其他剧作家记者合并:

```typescript
import { createChecklyReporter } from '@checkly/playwright-reporter';

export default defineConfig({
  reporter: [
    createChecklyReporter(),
    ['html', { outputFolder: 'playwright-report' }],
    ['list'],
    ['junit', { outputFile: 'test-results/junit.xml' }],
  ],
});
```

## 理解测试会话

记者创建 **成套测试会**,而不是单个测试文件结果.

当你跑的时候 `npx playwright test`数字 :

1.  **一个测试会** 创建, 以您的目录命名
2.  **一个测试结果** 整个运行
3.  **所有资产一起上传** 在一个 ZIP 文件内

福利:

-   整个测试套间的综合视图
-   高效存储
-   跟踪总通过率/长期不及格率

## 警卫

总是使用环境变量作为证书. 从不将 API 密钥输入到版本控制 .

```typescript
// DON'T DO THIS
createChecklyReporter({
  apiKey: 'chk_api_...',  // Hardcoded credentials!
})

// DO THIS
createChecklyReporter()  // Reads from environment
```

使用 [偷窥秘密](https://npmcn.com/package/%40checkly/playwright-reporter/#readme-secret-scrubbing) 特性,以确保敏感值不会泄露到上传的报告和痕迹中.

## 文档

详细文件,访问 [checklyhq.com/docs/detect/测试/剧作家-记者](https://www.checklyhq.com/docs/detect/testing/playwright-reporter/)。 。 。 .

## 许可证

Apache 2.0 (英语)

## 常见问题

### @checkly/playwright-reporter 是什么？

Checkly的独立 Playwright记者 - 兼容 Playwright 1\.40-1\.64\+

### 如何安装 @checkly/playwright-reporter？

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

### @checkly/playwright-reporter 支持 TypeScript 吗？

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

### @checkly/playwright-reporter 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @checkly/playwright-reporter 需要什么版本的 Node\.js？

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

### @checkly/playwright-reporter 可以商用吗？

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

### @checkly/playwright-reporter 的下载量有多少？

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

### @checkly/playwright-reporter 还在维护吗？

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