# @deploysentinel/cypress-debugger 中文文档

规范地址：https://npmcn.com/package/%40deploysentinel/cypress-debugger/

版本：0\.8\.9
npm 元数据更新时间：2023-09-11T16:47:45.755Z
中文译文更新时间：2026-11-12T08:02:50.318Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：1.2 MB，8 个文件
- TypeScript 类型：包内自带
- 运行依赖：18 个
- 首次发布：2022-04-27T02:13:59.744Z
- 最新版本发布：2023-09-11T16:47:45.545Z
- 近 30 天下载量：2651（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：91（近 12 个月 0 个）

## 中文简介

启用 Cypress 从远程环境( ex. CI) 中运行的查看/调试 Cypress , 包含您习惯本地拥有的调试信息 .

## 安装

```sh
npm install @deploysentinel/cypress-debugger
```

也可以使用：`pnpm add @deploysentinel/cypress-debugger`、`yarn add @deploysentinel/cypress-debugger`、`bun add @deploysentinel/cypress-debugger`

## README

# 部署 Sentinel Cypress 调试器

启用从远程环境( ex. CI) 运行的 Cypress 查看/调试 本地调试信息 .

_**浏览器兼容性说明**: 控制台日志和网络捕获尚未完成 兼容 Microsoft Edge 或 Firefox._

## 安装

在您的 Cypress 项目中安装 Cypress 插件 .

```sh
npm install -D @deploysentinel/cypress-debugger
```

## 使用量

### 添加支持文件

在你的Cypress项目 **支助** 页:1. `cypress/support/index.js`增加:

```js
// ❗ Must be declared at the top of the file ❗
import "@deploysentinel/cypress-debugger/support";

...
import "./commands";
```

### 添加插件

在你的Cypress项目 **插件** 页:1. `cypress/plugins/index.js`增加:

```js
module.exports = (on, config) => {
  // ❗ Must be declared at the top of the function ❗
  [on, config] = require('@deploysentinel/cypress-debugger/plugin')(on, config);

  // Use 'on' and 'config' returned from the plugin
  // ...
};
```

_注:插件返回补丁版本 `on` 财务报告和审定财务报表 `config` 改为 [与其他插件和配置消除冲突](https://github.com/cypress-io/cypress/issues/5240)。 。 。 ._

### 添加 API 密钥

最后,将您的 API 密钥添加到一个 `deploysentinel_key` [Cypress 环境变量](https://docs.cypress.io/guides/guides/environment-variables#Setting)。 。 。 . 您可以按下您的 API 键 [登录](https://www.deploysentinel.com/login)编号 :[报名](https://www.deploysentinel.com/register) 部署森蒂内尔并访问您的简介页面: [https://depmousesentinel.com/ profile (中文(简体) )](https://deploysentinel.com/profile)。 。 。 .

之后,您可以通过几种不同的方式指定密钥 :

#### **备选案文1.** Cypress 配置文件

在你身边 `cypress.json` 文件添加:

```json
{
  ...
  "env": {
    ...
    "deploysentinel_key": "YOUR_API_KEY"
  }
}
```

#### **备选案文2.** OS 环境变量

在您环境中导出 OS 环境变量

```sh
CYPRESS_DEPLOYSENTINEL_KEY=YOUR_API_KEY
```

#### **备选案文3.** Cypress CLI 旗帜

```sh
cypress run --env deploysentinel_key=YOUR_API_KEY
```

#### **备选案文4.** 程序通过插件文件

只有在需要程序控制或自定义 API 密钥从 .

在你的Cypress项目 **插件** 页:1. `cypress/plugins/index.js`增加:

```js
module.exports = (on, config) => {
  // Add this to specify the key programmatically, before calling the plugin
  config.env.DEPLOYSENTINEL_KEY =
    process.env.YOUR_CUSTOM_ENV_FOR_API_KEY || 'YOUR_API_KEY';

  // Import plugin as usual, after the key in the env is set above
  require('@deploysentinel/cypress-debugger/plugin')(on, config);

  // ❗ Important: The config needs to be returned in the end
  return config;
};
```

### 电子配置

如果你的测试套房在Electron运行, 你需要通过额外的 旗到 Cypress 打开一个远程调试端口供插件监听 网络和控制台日志.

指定远程调试端口 `ELECTRON_EXTRA_LAUNCH_ARGS` 环境变量。 端口号码可以是任何可用的有效端口号码 那个机器.

```
ELECTRON_EXTRA_LAUNCH_ARGS="--remote-debugging-port=40500" cypress run ...
```

如果你的测试套房只在Chrome/Chrome ex运行的话. `cypress run --browser chrome`,那么这一步骤就没有必要。 联网和 目前不支持为Microsoft Edge和Firefox采集控制台日志.

## 正在本地验证所有工作

默认情况下,插件只在非交互模式(ex. `cypress run`),并且只会上传失败时的抓取. 验证插件 正在本地工作, 您可以强制它总是被启用和上传 通过启用下列环境变量来获取:

```sh
CYPRESS_DEPLOYSENTINEL_UPLOAD_ON_PASSES=true cypress run # or open
```

如果无法设置OS环境变量, 也可以设置 通过类似如何配置 API 密钥的 CLI 旗或配置文件( 见 以上"添加API键"部分.

## 查看测试结果

默认情况下, 测试失败时, 控制台日志中将会有运行的 URL 到运行失败日志。 可以在您的 CI 日志中访问 .

示例日志 :

```
  Running:  pages.js                                            (3 of 3)


  Pages
    ✓ generates complex slug with md extension (647ms)
    1) generates a slug with an index file
     DeploySentinel Debug URL: https://deploysentinel.com/ci/runs/712345677654321abcd00000
    ✓ generates a slug with a slash (672ms)
```

否则,运行可以从Sentinel Dashboard at [https://depmoutsentinel.com/ci/dashboard 页面存档备份,存于互联网档案馆](https://deploysentinel.com/ci/dashboard)。 。 。 .

_注意: 默认情况下, 当测试通过时, 插件将不会上传任何数据 如果测试以交互模式运行。 参见"校验一切在当地工作" 详情见上文._

### J股报告整合

如果Cypress是带着 [J股记者](https://docs.cypress.io/guides/tooling/reporters#Reporter-Options), (中文(简体) ), 插件将自动将“部署Sentinel URL”附加到 整个测试套件运行后测试失败的错误细节, 因此您可以 从您的 JUniversity 报告输出中轻松获取测试抓取 .

## 抓取的数据

启用时, 将自动抓取 Sentinel Cypress 调试器 cypress在测试中采取的行动,以及 DOM 捕获、控制台日志和 网络请求.

## 高级配置

### 网络请求过滤

默认情况下,调试器会捕获所有网络请求. 您可以指定一个 `beforeNetworkSend` 在过滤敏感网络请求的插件文件中 返回时 `null` 或者说 `undefined`。 。 。 .

```js
require('@deploysentinel/cypress-debugger/plugin')(on, config, {
  beforeNetworkSend: event => {
    if (event.request.url.includes('wikipedia.org')) {
      return null;
    } else if ('ds-key' in event.request.headers) {
      return null;
    } else if (event.response?.statusCode === 400) {
      return null;
    }
    return event; // Don't filter out event
  },
});
```

_注意: 更新/修改函数内的网络事件对象不会 修改实际记录的网络事件内容,我们可能允许在 未来通过这个API._

事件对象类型 :

```js
{
  request: {
    url: string;
    method: string;
    headers: { [key: string]: string };
  };
  // optional
  response?: {
    statusCode: number;
    statusMessage: string;
    headers: { [key: string]: string };
    bodySize: number;
    body: string;
  };
}
```

信头会小写。 ưμ㼯A `X-My-Header` 将会是 可通过 `event.headers["x-my-header"]`。 。 。 .

### 启用特定文件的抓取

要抓取特定的测试, 您可以在 `CYPRESS_DEPLOYSENTINEL_SPEC` 环境变量,类似于 `--spec` Cypress CLI旗 (英语).

示例

```sh
CYPRESS_DEPLOYSENTINEL_SPEC="cypress/tests/ui/**, cypress/integration/**"
```

### Git 提交元数据

默认情况下,调试器会自动发送元数据以显示 在仪表板UI。 如果我们不能自动调出信息, 您可以设置以下环境变量来手动指定承诺 资料:

```sh
branch: COMMIT_INFO_BRANCH
message: COMMIT_INFO_MESSAGE
email: COMMIT_INFO_EMAIL
author: COMMIT_INFO_AUTHOR
sha: COMMIT_INFO_SHA
timestamp: COMMIT_INFO_TIMESTAMP
remote: COMMIT_INFO_REMOTE
```

## 发送自定义事件到部署Sentinel \[BETA\]

用户可将自定义事件发送到 Sentinel 以附加额外的调试 测试中的信息。 (例如用 DB 或 app 调试错误和片段) 州立垃圾场) 要使用它,只需将自定义数据传递给命令 `cy.dsAddEvent`。 。 。 .

```js
Cypress.on('fail', e => {
  // As an example, fetch data from Firebase
  cy.callFirestore('get', 'myData').then(r => {
    cy.dsAddEvent(r);
  });
  throw e;
});
```

_说明:对于每个有效载荷,应当能够用 `JSON.stringify` (无圆形依赖关系) 大小必须小于 **4 个 MB**。 。 。 ._

#### 键入符配置

如果你用Typescript与 Cypress, 你需要添加 `@deploysentinel/cypress-debugger` 页:1 `cypress/tsconfig.json` 文件 :

```json
{
  "compilerOptions": {
    "types": ["cypress", "@deploysentinel/cypress-debugger"]
  }
}
```

## 网络固定器 发电机/拦截器 \[BETA\]

启动后, 自动丢弃生成器 网络在测试完成后向本地磁盘请求数据.

另一方面,部署Sentinel Cypress网络拦截器,在启用时, 将使用固定装置在测试运行时自动拦截网络请求 由Fixtures发电机生成.

### 记录模式

一旦启用了记录模式,调试器将把网络文物倾倒到 `/cypress/fixtures` 带有文件名前缀 `ds-network-mock` 以 JSON 为格式

要启用记录模式, 设置 `CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE` 环境变量改为 `record`

```sh
CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=record
```

(备选) 您可以指定 `networkMock` 在要过滤未使用的插件文件中 网络文物

```js
require('@deploysentinel/cypress-debugger/plugin')(on, config, {
  networkMock: {
    mode: 'record', // optional
    methods: ['GET', 'POST'], // default to ["GET", "PATCH", "POST", "PUT", "HEAD", "DELETE"]
    includeUrls: ['https://example.com/**', 'https://api.example.com/users/**'], // default to ['**']
    excludeUrls: ['https://example.com/**'], // inverse of 'includeUrls', default to []
  },
});
```

### 截取模式

启用截取模式时, 调试器会先前读取定着值 从记录模式生成( in) `/cypress/fixtures`)和截取 使用 `cy.intercept`

要启用截取模式, 设置 `CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE` 环境变量改为 `intercept`

```sh
CYPRESS_DEPLOYSENTINEL_NETWORK_MOCK_MODE=intercept
```

_注意: 截取模式将创建一个 `fixtures/.ds-network-cache` 文件夹 暂时存储网络模拟。 此文件夹应该被指定为源 真理来源于 `fixtures/ds-network-mock-*`_

## 更改日志

查看我们的 [我们的网站上直接有更改日志](https://www.deploysentinel.com/docs/cypress-changelog)。 。 。 .

## 常见问题

### @deploysentinel/cypress-debugger 是什么？

启用 Cypress 从远程环境\( ex\. CI\) 中运行的查看/调试 Cypress , 包含您习惯本地拥有的调试信息 \.

### 如何安装 @deploysentinel/cypress-debugger？

在项目目录运行 npm install @deploysentinel/cypress-debugger，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ds，可以用 npx ds 直接运行。

### @deploysentinel/cypress-debugger 支持 TypeScript 吗？

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

### @deploysentinel/cypress-debugger 可以商用吗？

@deploysentinel/cypress-debugger 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @deploysentinel/cypress-debugger 的下载量有多少？

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

### @deploysentinel/cypress-debugger 还在维护吗？

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