# @env-hopper/test-kit 中文文档

规范地址：https://npmcn.com/package/%40env-hopper/test-kit/

版本：2\.9\.3
npm 元数据更新时间：2026-11-13T03:22:28.318Z
中文译文更新时间：2026-11-13T23:58:14.411Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40env-hopper/test-kit
原文对照：https://npmcn.com/package/%40env-hopper/test-kit/?lang=original
项目主页：https://github.com/lislon/env-hopper
源码仓库：https://github.com/lislon/env-hopper

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

- 包体积（解压后）：233 kB，50 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=16
- 运行依赖：11 个
- peer 依赖：jsdom \>=25，react 19\.1\.2，vitest 3\.2\.2，react-dom 19\.1\.2，@env-hopper/backend-core ^2\.9\.3，@env-hopper/frontend-core ^2\.9\.3
- 首次发布：2026-09-30T05:09:00.684Z
- 最新版本发布：2026-11-13T03:22:27.998Z
- 近 30 天下载量：2798（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Env Hopper 的集成测试控制:模拟后端、模拟网络和页面对象

## 安装

```sh
npm install @env-hopper/test-kit
```

也可以使用：`pnpm add @env-hopper/test-kit`、`yarn add @env-hopper/test-kit`、`bun add @env-hopper/test-kit`

## README

# @env-phopper/test-kit (英语)

为Env Hopper进行整合测试. `renderApp()` 挂载真实 `App` —— 说 真实路由器, 真实客户端 DB, 真实的查询客户端 – 相对于模拟后端服务 并用后页的物体来驱动它.

它的存在是为了让行为独立于UI 执行它。 一个场景说"一个环境和资源决心 一个跳跃 url";只有页面对象在 `src/tools` 知道是什么元素吗? 替换 然后,UI意味着重新指定页面对象,而不是重写情景.

## 用这个

```ts
// vite.config.ts
import { quickpickle } from 'quickpickle'

export default defineConfig({
  plugins: [viteReact(), svgr(), quickpickle()],
  resolve: {
    // Resolve the cores from source, so nothing needs building first.
    conditions: ['my-custom-condition'],
    alias: { '~': path.resolve(__dirname, '../frontend-core/src') },
  },
  test: {
    environment: 'jsdom',
    environmentOptions: { jsdom: { url: 'http://localhost:3000' } },
    include: ['**/*.feature', '**/*.test.ts', '**/*.test.tsx'],
    setupFiles: ['@env-hopper/test-kit/setup', '@env-hopper/test-kit/cucumber'],
  },
})
```

三个切入点:

| 导入 | 这是什么 |
| --- | --- |
| `@env-hopper/test-kit` | `renderApp`,固定的 DSL,页面对象 |
| `@env-hopper/test-kit/setup` | 测试 `setupFile`: jsdom 漏洞,存储,每测试清理 |
| `@env-hopper/test-kit/cucumber` | 测试 `setupFile`:步骤定义 |

## 在类型脚本中写入方案

```ts
const { ui } = await renderApp({ server, initialLink: '/env/dev/app/app1' })

expect(ui.resourceJump.jumps.getUrl('App1')).toBe('http://localhost:4000/env/dev/app/app1')
```

## 在 Gherkin 中写一个

```gherkin
Given the "car shop" catalog opened at "/env/dev/app/parts-inventory"
Then the "Parts Inventory" jump goes to "http://localhost:4000/env/dev/app/parts-inventory"
```

## 带上自己的目录

这里的固定装置是发明的样本数据. 下游回波重用该步骤 逐字逐字地对照它自己的定义,用它的名称登记固定字 `.feature` 文件然后请求:

```ts
import { registerCatalog } from '@env-hopper/test-kit/cucumber'

registerCatalog('production', {
  envs: [{ slug: 'dev' }, { slug: 'prod' }],
  apps: [{ slug: 'billing', resourceJumps: '2-pager' }],
})
```

```gherkin
Given the "production" catalog opened at "/env/prod/app/billing"
```

命名环境和应用程序; 映射器将其扩展为每个后端 形状前端读取。 A 类 `2-pager` 也有第二页的用户需要 键入的值,这就是晚解参数路径如何被覆盖.

## 本地运行应用程序

任何关于外观的东西都需要一个真实的浏览器,它排除了绳子: jsdom 无法看到造型, msw 答案会在测试过程中获取, 所以 浏览器本身也从未达到它. 有两种方法可以让真正的UI在你面前 时间 `localhost`不需要部署.

### 面对真正的后端

最好的数据是后端实际生成的数据. 下游开始 本地端后端,然后通过dev服务器的代理端将前端指向它:

```sh
EH_API_PORT=4002 VITE_EH_API_URL=/api/trpc pnpm run dev:x
```

一个亲戚 `VITE_EH_API_URL` 保持请求来源相同, 所以代理 转发它 —— 这意味着后端发送没有 CORS 头, 对于一个正常 期待坐在它自己的静态服务器后,工作不变.

### 在模拟后端

`src/dev-server/serveMockBackend.ts` 都一样 `BackendData` 处理器 在端口上服务,所以不需要数据库或后端:

```sh
pnpm run dev:local     # from the repository root
```

启动模拟后端 `:4000` 并打开前端 dev 服务器 `:3999`。 。 。 . 无论哪种方式,编辑一个组件都是重新装入页面,而不是部署.

### 重放抓取的目录

样本定型是3个应用, 足够一个情景,但还不够 以看到布局坚挺. `capture-fixture.mjs` 记录两个有效载荷 运行后端——本地端是明显的选择——和模拟后端 重放它们,所以环线会继续下线:

```sh
EH_ORIGIN=http://localhost:4002 EH_FIXTURE_DIR=~/eh-fixture \
  node packages/test-kit/scripts/capture-fixture.mjs

EH_FIXTURE_DIR=~/eh-fixture pnpm run dev:local
```

捕捉器将每个暗视值替换为 `REDACTED` 在同一通行证中 作为下载——原始回复从不写入磁盘——并打印如何 许多键,它编辑。 钥匙留下,所以一个证书面板仍然可以.

保留 `EH_FIXTURE_DIR` **此仓库外**一个真正的目录名称 后端自己的主机和环境,这个寄存器是公开的. 还没有, `dev:local` 服务于样本固定,所以默认不花费什么.

| 变量 | 默认 | 它会做什么 |
| --- | --- | --- |
| `EH_FIXTURE_DIR` | 未设定 | 载有两个被捕获的有效载荷的目录 |
| `EH_API_PORT` | `4000` | 移植 dev 服务器代理 `/api` 改为 |
| `VITE_EH_API_URL` | `http://localhost:4000/trpc` | 其中前端寻找 tRPC |

## 它没有覆盖

jsdom没有布局引擎,也没有CSS,因此这里没有任何东西可以看见有型.

## 常见问题

### @env-hopper/test-kit 是什么？

Env Hopper 的集成测试控制:模拟后端、模拟网络和页面对象

### 如何安装 @env-hopper/test-kit？

在项目目录运行 npm install @env-hopper/test-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：jsdom（\>=25）、react（19\.1\.2）、vitest（3\.2\.2）、react-dom（19\.1\.2）、@env-hopper/backend-core（^2\.9\.3）、@env-hopper/frontend-core（^2\.9\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @env-hopper/test-kit 支持 TypeScript 吗？

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

### @env-hopper/test-kit 支持 ESM 还是 CommonJS？

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

### @env-hopper/test-kit 需要什么版本的 Node\.js？

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

### @env-hopper/test-kit 可以商用吗？

@env-hopper/test-kit 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @env-hopper/test-kit 的下载量有多少？

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

### @env-hopper/test-kit 还在维护吗？

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