bk-press

一个用于 Cypress 自动化测试的 CLI 工具，帮助快速初始化测试环境、并行运行自动化测试，并支持从浏览器录制产物生成 Fixture 拦截数据 与 Cypress 测试脚本。

📋 目录

• 安装
• 快速开始
• CLI 命令一览
• 从网络日志生成 Fixture（fixture）
• 从 Chrome Recorder 生成测试脚本（record）
• 配置文件
• 项目结构
• 使用示例
• 常见问题

安装

全局安装

npm install -g bk-press
# 或
yarn global add bk-press
# 或
pnpm add -g bk-press

本地安装

npm install bk-press
# 或
yarn add bk-press
# 或
pnpm add bk-press

快速开始

1. 初始化 Cypress 测试环境

   bkpress init

2. 配置环境变量 编辑 cypress.env.json 文件，设置开发环境和本地环境的 URL：

   {
     "DEV_URL": "https://your-dev-domain.com",
     "LOCAL_URL": "http://localhost:8080",
     "COOKIE_DOMAIN_A": "your-domain.com",
     "COOKIE_DOMAIN_B": "your-domain.com"
   }

3. 登录并保存 Cookie

   bkpress login

4. 并行运行自动化测试

   bkpress run

CLI 命令一览

| 命令 | 说明 | |------|------| | bkpress init | 初始化 Cypress 测试环境（模板、配置、脚本等） | | bkpress login | 打开浏览器登录并写入 cypress.env.json 中的 Cookie | | bkpress run | 并行运行 E2E 自动化测试 | | bkpress fixture | 从项目根目录的 web-interaction-log.json 生成 cypress_fixtures/ 下的响应 JSON | | bkpress record <paths...> | 根据 Cypress Chrome Recorder 导出的一个或多个 JSON，生成一个或多个 Cypress 测试脚本 |

查看子命令与参数：

bkpress --help
bkpress record --help

从网络日志生成 Fixture（fixture）

适用于：在真实页面上操作一遍后，把 XHR / Fetch 的响应体 落成静态 JSON，供 cy.intercept 等场景做桩数据。

前置条件

1. 在 Chrome 应用商店安装 Web Interaction Logger 插件，在目标站点录制并导出 web-interaction-log.json。
2. 将该文件放在当前项目根目录（与执行 bkpress fixture 时的 cwd 一致）。

用法

bkpress fixture

行为说明

• 读取根目录下的 web-interaction-log.json；若不存在会提示先安装插件并导出文件。
• 仅处理满足以下条件的条目：type 为 network、subtype 为 response-body，且 url 为以 / 开头的相对路径（站点内接口）。
• 在根目录创建或使用 cypress_fixtures/ 目录，按请求方法与 URL 路径写入多个 .json 文件（内容为对应条目的 responseBody）。

生成后可在 Cypress 中把上述路径配进 cy.fixture / cy.intercept 的 fixture 或 body，与项目内约定保持一致即可。

从 Chrome Recorder 生成测试脚本（record）

适用于：使用 Cypress Chrome Recorder 插件导出录制的json后，一键生成 Cypress 测试用例代码。

用法

# 单个文件
bkpress record ./recordings/flow.json

# 多个文件依次转换
bkpress record ./a.json ./b.json

路径为相对于当前工作目录的相对路径，或可使用绝对路径。

配置文件

cypress.env.json

环境变量配置文件，用于存储测试环境相关的配置和 Cookie。

初始配置：

{
  "DEV_URL": "https://your-dev-domain.com",
  "LOCAL_URL": "http://localhost:8080",
  "COOKIE_DOMAIN_A": "your-domain.com",
  "COOKIE_DOMAIN_B": "your-domain.com",
}

登录后的配置： 登录命令会自动将 Cookie 添加到配置文件中：

{
  "DEV_URL": "https://your-dev-domain.com",
  "LOCAL_URL": "http://localhost:8080",
  "COOKIE_DOMAIN_A": "your-domain.com",
  "COOKIE_DOMAIN_B": "your-domain.com",
  "sessionId": "xxx",
  "token": "xxx"
  // ... 其他 Cookie
}

配置说明：

• DEV_URL: 开发环境 URL，用于登录获取 Cookie
• LOCAL_URL: 本地开发服务器 URL，用于运行测试
• COOKIE_DOMAIN_A: Cookie 的域名，用于设置 Cookie 的作用域，可能有多个，自行命名

cypress.config.ts

Cypress 主配置文件，由 init 命令自动创建。

默认配置：

import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {},
});

可以根据项目需求自定义配置。

项目结构

初始化后的项目结构：

your-project/
├── cypress/
│   ├── e2e/              # 端到端测试用例
│   ├── fixtures/         # 测试数据（Cypress 默认 fixtures）
│   ├── support/          # 支持文件
│   │   ├── commands.ts   # 自定义命令
│   │   ├── e2e.ts        # E2E 测试支持
│   │   └── login.ts      # 登录命令（由 login 命令生成）
│   └── ...
├── cypress_fixtures/     # fixture 命令由网络日志生成的响应 JSON（可选，运行 fixture 后出现）
├── web-interaction-log.json   # Web Interaction Logger 导出文件（可选，供 fixture 使用）
├── cypress.config.ts     # Cypress 配置文件
├── cypress.env.json      # 环境变量配置（包含 Cookie）
└── package.json          # 包含测试脚本

使用示例

完整工作流程

# 1. 初始化项目
bkpress init

# 2. 编辑 cypress.env.json，设置环境 URL
# {
#   "DEV_URL": "https://dev.example.com",
#   "LOCAL_URL": "http://localhost:3000",
#   "COOKIE_DOMAIN": "example.com"
# }

# 3. 登录并保存 Cookie
bkpress login
# 在浏览器中完成登录，然后按回车

# 4. 并行运行测试
bkpress run

从网络日志生成接口 Fixture

bkpress fixture

从 Recorder JSON 生成 Cypress 脚本

bkpress record ./my-flow.json

在测试用例中使用登录

// cypress/e2e/example.cy.ts
describe("用户功能测试", () => {
  beforeEach(() => {
    // 使用自动生成的登录命令
    cy.login();
  });

  it("应该显示用户信息", () => {
    cy.visit("/profile");
    cy.contains("用户信息").should("be.visible");
  });
});

手动运行测试

除了使用 bkpress run，你也可以使用 init 命令添加的 npm scripts：

# 打开 Cypress 交互式测试运行器
npm run e2e-dev

# 在无头模式下运行所有测试
npm run e2e

# 运行组件测试
npm run component-test

常见问题

1. init 命令失败：无法克隆模板文件

问题： 提示 "克隆模板文件失败"

解决方案：

• 确保已安装 Git
• 确保有访问模板仓库的权限（SSH 密钥配置正确）
• 检查网络连接

2. login 命令失败：DEV_URL 配置不存在

问题： 提示 "cypress.env.json 文件中 DEV_URL 配置不存在"

解决方案：

• 确保已运行 bkpress init 初始化项目
• 检查 cypress.env.json 文件是否存在
• 确保文件中包含 DEV_URL 配置项

3. run 命令失败：无法启动服务器

问题： 提示 "运行自动化测试失败"

解决方案：

• 确保 package.json 中有 dev 脚本
• 检查 LOCAL_URL 配置是否正确
• 确保端口没有被占用
• 检查开发服务器是否能正常启动

4. TypeScript 类型错误

问题： Cypress 相关的 TypeScript 类型未识别

解决方案：

• 确保已运行 bkpress init（会自动配置 TypeScript）
• 检查 tsconfig.json 中是否包含 cypress 类型
• 重启 IDE 或 TypeScript 服务器

5. Cookie 未正确保存

问题： 登录后 Cookie 未保存或测试中无法使用

解决方案：

• 确保在浏览器中完成登录后再按回车
• 检查 cypress.env.json 文件是否包含 Cookie
• 检查 cypress/support/login.ts 文件是否正确生成
• 确保 cypress/support/e2e.ts 中导入了 ./login

6. fixture 报错：web-interaction-log.json 不存在

问题： 运行 bkpress fixture 时提示找不到 web-interaction-log.json

解决方案：

• 确认文件位于项目根目录，且文件名为 web-interaction-log.json
• 在 Chrome 中安装 Web Interaction Logger，完成录制后使用插件的导出功能保存到上述路径

7. fixture 未生成预期文件

问题： 命令成功但 cypress_fixtures/ 里文件很少或为空

解决方案：

• 当前逻辑只收录 相对路径 接口（url 以 / 开头）；完整 URL（https://...）会被过滤掉
• 只处理 response-body 类型的网络日志，请确认导出内容里包含响应体
• 若条目缺少 responseBody，对应文件不会写入

8. record 命令失败

问题： bkpress record 退出码非 0 或 npx 报错

解决方案：

• 确认已传入至少一个 JSON 路径：bkpress record ./your.json