# @harperfast/integration-testing 中文文档

规范地址：https://npmcn.com/package/%40harperfast/integration-testing/

版本：1\.1\.0
npm 元数据更新时间：2026-11-16T23:12:30.930Z
中文译文更新时间：2026-11-17T10:23:21.723Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40harperfast/integration-testing
原文对照：https://npmcn.com/package/%40harperfast/integration-testing/?lang=original
项目主页：https://github.com/HarperFast/integration-testing
源码仓库：https://github.com/HarperFast/integration-testing

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

- 包体积（解压后）：274 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：harper ^5\.0\.0
- 首次发布：2026-04-10T20:45:24.996Z
- 最新版本发布：2026-11-16T23:12:30.589Z
- 近 30 天下载量：118298（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

Harper项目的综合测试设施。 提供哈珀实例生命周期管理,回回地址集合,以及测试跑取脚本.

## 安装

```sh
npm install @harperfast/integration-testing
```

也可以使用：`pnpm add @harperfast/integration-testing`、`yarn add @harperfast/integration-testing`、`bun add @harperfast/integration-testing`

## README

# @harperfast/整合测试

Harper项目的综合测试设施。 提供框架-不可知的哈珀实例生命周期管理,同时提供回回回地址池,目录压缩工具,以及可选的预配置节点.js测试跑道脚本.

## 测试 Ethos

哈珀生态系统有三种不同的测试水平:

-   **单位** 测试可以直接根据源码或已建代码验证孤立的逻辑,依靠模拟或积分来取代真正的依赖.
-   **一体化** 测试与哈珀软件相对, 但本地和电平。 哈珀作为每个测试套房的童年过程开始,给予一个临时的安装目录,并在套房完成后被撕下. 没有远程基础设施可以管理.
-   **端对端** 测试更进一步:它们的目标是尽可能密切地反映生产的部署——想象一个具有真正的基础设施、远程系统和业务配置的中转环境.

这个项目是严格意义上的 **融合** 测试.

这种区分很重要,因为集成测试让你对哈珀的实际行为有信心,而没有管理所部署环境的成本和复杂性. 你得到真正的软件,不是嘲笑,而是快速的本地迭代.

不论使用何种框架或跑道,整合测试应力求:

-   **独立**: 不依赖执行命令或与其他测试共享状态
-   **隐形**: 自成一体,无外在副作用
-   **决定性**: 相同的输入总是产生相同的输出

这些属性使得安全同时执行成为可能——没有这些属性,平行化会产生片面的,依赖订单的失败.

## 安装

```sh
npm install --save-dev @harperfast/integration-testing
```

## 框架不可知论

本包中的核心生命周期和回回池 API—— `startHarper`, (中文(简体) ), `teardownHarper`, (中文(简体) ), `killHarper`,以及回旋公用事业——即 **不与任何特定的试验跑道或框架挂钩**它们产出和管理哈珀儿童进程,并安全地在同时进行的进程中分配回路地址,无论它们的PID命名空间或 `TMPDIR`。这意味着它们可以和任何支持同步设置和拆解的测试框架一起使用:Node.js `node:test`维特 普莱特 或者其他什么.

这些API赋予你的关键责任是 **批判性考虑哈珀实例范围**. 开始一个哈珀实例具有真正的成本——它产生一个过程,从池中分配回回回地址,并创建一个临时安装目录. 你们的瞄准镜实例取决于你们的框架和测试内容. 在一个逻辑测试区块中,一个在很多说法中共享的单一实例可能是完全适当的;为每一个个人断言翻出一个新实例将是浪费。 重要的是同时执行范围每个都有各自的实例和回回地址——池能安全地处理跨进程分配,但由你的设置和被拆卸的钩子决定边界.

本套装还包括: **预配置了 Node.js 测试跑步脚本** (单位:千美元)`harper-integration-test-run`作为建议,包括电池在内,可以与该设备一起进行测试 `node:test` API (英语). 现将本报告及其 [来源](https://npmcn.com/package/%40harperfast/integration-testing/src/run.ts) 用作任何将这些公用事业与另一跑道合并的参考.

## 设置: 循环地址

同时运行哈珀集成测试需要多个回回地址,这样每个哈珀实例就可以绑定一个不同的地址而不会发生端口冲突.

Linux 和 Windows 整个路线 `127.0.0.0/8` 块`127.0.0.1–127.255.255.255`)默认回放,所以不需要设置. macOS 只启用 `127.0.0.1`。 。 。 .

在 macOS 上,请使用包含的脚本配置其余的:

```sh
npx harper-integration-test-setup-loopback
```

此脚本需要 `sudo` 并尊重 `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT` 环境变量(默认为32).

在macOS上,别名被配置为主机(`/32`)网盖. 这很重要: 默认的A类(`/8`网盖 `127.0.0.x` 其他索赔 `127.0.0.0/8` 网络,并大范围计算由此产生的一组重叠子网接口地址驱动器 `mDNSResponder`"地址冲突防御" 变成CPU-pinning暴风雨 MDNS公告 在港口5353。 如果您以前运行过此脚本的更旧版本, 请重运行它, 将已有的别名转换为 `/32`。 。 。 .

### 横跨反弹( macOS)

`ifconfig` 化名只活在运行中的内核中 – macOS 不持续手动添加 `lo0` 化名,所以它们消失 在每次重启, 游泳池必须重新配置。 对于一个定期复发的dev机器,安装一个 `launchd` 运行设置脚本的守护进程 . `scripts/io.harperdb.loopback-setup.plist` 已为此提供; 脚本是 root- aware, 因此不需要 `sudo` 当发射时,它作为根运行.

```sh
# 1. Copy the setup script to a stable, root-owned path (the plist points here)
sudo mkdir -p /usr/local/sbin
sudo install -m 755 -o root -g wheel \
  "$(npm root)/@harperfast/integration-testing/scripts/setup-loopback.sh" \
  /usr/local/sbin/harper-loopback-setup.sh

# 2. Install the daemon (must be root:wheel and mode 644 or launchd rejects it)
sudo install -m 644 -o root -g wheel \
  "$(npm root)/@harperfast/integration-testing/scripts/io.harperdb.loopback-setup.plist" \
  /Library/LaunchDaemons/io.harperdb.loopback-setup.plist

# 3. Load and run it now (also runs at every boot via RunAtLoad)
sudo launchctl bootstrap system /Library/LaunchDaemons/io.harperdb.loopback-setup.plist

# 4. Verify
cat /var/log/harper-loopback-setup.log        # ✓ Configured ... line
ifconfig lo0 | grep '127.0.0' | tail -3       # aliases present
```

编辑 `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_COUNT` 值在已安装的列表中更改池大小(默认为32个,匹配脚本)。 要删除守护进程 : `sudo launchctl bootout system/io.harperdb.loopback-setup` 删除列表。 如果您编辑已安装的列表, `bootout` 接下来 `bootstrap` 再次装入.

### 其他在哈珀港口收听的服务

每个节点会将固定的端口绑在自己的回路地址上,因此不同地址上的节点共存. 在同一端口上监听的进程 **所有接口** 不同 – 本地的哈珀实例, 其默认配置是通常的 。 在macOS和Windows上,当节点在它的地址上没有自己的收听器时,该过程会接收到节点的连接:当节点开始时,当它的HTTP工人重启时,在被撕毁后. 保持动态连接,然后保持它, 所以一个套房失败,或者通过,对错的服务器.

`getNextAvailableLoopbackAddress`,因此 `startHarper`,当另一个进程已经接受操作或HTTP端口的连接时,拒绝地址,丢出一个 `ForeignListenerError` 命名端口。 停止另一个进程或将其绑定在一个特定的地址上(`lsof -nP -iTCP:9926 -sTCP:LISTEN` 说吧 反正要跑,设置 `HARPER_INTEGRATION_TEST_ALLOW_FOREIGN_LISTENERS=1`,使错误变成警告.

在Linux上,这样的收听器也阻止了将端口绑在一个单一地址上的其他任何内容,哈珀包含,因此同样错误也覆盖了哈珀的HTTPS,MQTT和MQTTS端口. 在Linux上设置变量后,即使另一个收听器下绑有该地址的哈珀节点不能排除,地址还是被发出.

## API 密码

下面的生命周期和效用API是框架不可知的. 他们管理哈珀儿童流程和一个跨进程回回回地址池. 在您喜欢的测试框架的设置/收缩钩中使用它们 .

`startHarper`, (中文(简体) ), `setupHarperWithFixture`, (中文(简体) ), `killHarper` 财务报告和审定财务报表 `teardownHarper` 都拿着 **上下文** - 对象有: `harper` 财产——而不是在 `ctx.harper`。通过节点 扔出一个 `TypeError`:被撕开的一对叫你把它包起来(`teardownHarper({ harper: node })`),而起首对则告诉你要通过上下文,节点来自,因为从节点开始,会发布一个新的上下文,并放弃已经运行的实例. 它曾经被默默接受,使得节点一直跑到跑者出道. 其背景 `harper` 从来没有人居住 仍然是不开放的, 所以撕后 `before` 扔入的钩子保持安全.

### `startHarper(ctx, options?)`

从池中分配回回路地址,创建临时安装目录,启动哈珀进程,并等待准备. 分布 `ctx.harper` 和案例的细节。 调用设置/`before()` 钩.

哈珀作为自己的脱去过程组运行,因此在不进行清理的情况下死亡的跑者会让它活活地持有固定的端口. 在POSIX上,该实例以共享方式注册 [实例监视器](https://npmcn.com/package/%40harperfast/integration-testing/#readme-orphaned-instance-monitor-posix) 那样的话,就能得到它.

哈珀二进制按以下顺序解决: 1

1.  `harperBinPath` 选项直接传递到 `startHarper()`
2.  `HARPER_INTEGRATION_TEST_INSTALL_SCRIPT` 环境变量(路径到 `dist/bin/harper.js`(中文(简体) )
3.  离这里最近的 `dist/bin/harper.js` 在工作目录中或其祖先——哈珀建筑(harper,harper-pro)中,你的测试在内部运行,它优先于 `harper` 用于此软件包对等依赖的 npm 软件包自动安装
4.  A 类 `harper` 作为项目依赖性安装的软件包: `require('harper')` 决定从工作目录中找到,该目录将通过其 `bin` 字段

**选项 :**

```ts
interface StartHarperOptions {
  startupTimeoutMs?: number;   // Idle timeout: max gap between startup output chunks. Default: 60000 (150000 under CI) or HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS
  startupMaxMs?: number;       // Absolute startup ceiling regardless of output. Default: 120000 (300000 under CI) or HARPER_INTEGRATION_TEST_STARTUP_MAX_MS
  config?: object;             // Harper config overrides (passed via HARPER_SET_CONFIG)
  env?: object;                // Additional environment variables for the Harper process
  harperBinPath?: string;      // Explicit path to dist/bin/harper.js
}
```

哈珀打印检测到启动准备状态 `successfully started`监督员使用的是“慢而健康的靴子”与“被绞死”而不是“被绞死后” **闲置超时** 在每一块产出上重放——因此,限制是时间——自上而后的进展——加宽的绝对上限作为后盾。 这就是为什么一个慢的CI靴子 使伐木不再穿越超时.

> **行为改变 :** `startupTimeoutMs` (和 `HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS`)之前指绝对起动期限. 现在意思是 **闲置/ 无输出窗口**。如果你依赖它作为一个硬天花板 快速失败慢靴,设置 `startupMaxMs` (或 `HARPER_INTEGRATION_TEST_STARTUP_MAX_MS`相反.

**环境变量:**

-   `HARPER_INTEGRATION_TEST_STARTUP_TIMEOUT_MS` - 闲置启动超时:哈珀作为挂起(重置在输出上)之前,启动输出块之间的最大时间。 默认 `60000` (单位:千美元)`150000` 页:1.
-   `HARPER_INTEGRATION_TEST_STARTUP_MAX_MS` - 总启动时间的绝对上限,不论正在进行的产出如何。 默认 `120000` (单位:千美元)`300000` 页:1.
-   `HARPER_INTEGRATION_TEST_INSTALL_PARENT_DIR` - 临时哈珀安装 dirs 的父目录( 默认: OS tmpdir)
-   `HARPER_INTEGRATION_TEST_INSTALL_SCRIPT` - 哈珀CLI脚本的路径
-   `HARPER_INTEGRATION_TEST_ALLOW_FOREIGN_LISTENERS` - 准备 `1` 或者说 `true` 在操作或 HTTP 端口的地址上启动一个节点, 其操作或 HTTP 端口的另一个进程已经接受连接, 或无法检查其中的连接, 并带有警告而不是错误( 见 [其他在哈珀港口收听的服务](https://npmcn.com/package/%40harperfast/integration-testing/#readme-other-services-listening-on-harpers-ports)) (中文(简体) ).

### `setupHarperWithFixture(ctx, fixturePath, options?)`

喜欢 `startHarper()`,但是在开始前复制一个组件目录到哈珀安装中,所以它可以在没有部署的第一靴子上使用.

### `killHarper(ctx, options?)`

终止哈珀的整个过程树,等待它退出. 它首先发送SIGTERM,给予哈珀一个宽限期,在升级为SIGKILL之前,清洁地关闭(flush RocksDB,放出端口,收割工人),然后短暂地等待实际退出. 因为哈珀是作为自己的流程组被产入的`detached` 在POSIX上,信号针对的是群体——父母和任何孩子的过程——而不只是直接的孩子;在Windows上它使用 `taskkill /T`。一个死过程释放它的收听套接字,所以一次 `killHarper` 返回固定端口是免费的(当它无法确认节点已停止时,它会记录一个警告)。 不发布回路地址或清理安装目录 。 用于测试需要的重新启动情景 `startHarper` 再来一次.

它也停止了一个重新开始的节点. 哈珀餐厅 `restart` 操作重新启动节点作为一个新的、分离的过程,让一个 `startHarper` 产出,所以一旦程序退出 `killHarper` 终止任何进程 `<dataRootDir>/hdb.pid` 名称—— pid 文件 `harper stop` 使用——在同一SIGTERM中,优等,SIGKILL序列(在POSIX上,等待其整个进程组),如果SIGKILL将其留下,则去掉pid文件. 替换器仅在前身出厂后,即半秒后在一台闲置机上记录出它的pid. 产卵过程在它重新启动之前 第二次打印出它的准备状态线 所以在这条线之后 `killHarper` 等待 pid 文件出现, 最多5 秒( 在 CI 下为 15, 或 `HARPER_INTEGRATION_TEST_RELAUNCH_WAIT_MS`从宣布过程退出时开始。 Harper在RocksDB关闭时给予这个过程长达15秒的时间退出,因此等待时间不会提前开始. 一个节点停止了,没有重新开始报告,没有支付等待。 若为 `killHarper` 无法确认已停止的节点——一个已宣布的替换者从未记录过节点,或者一个进程已过期的SIGKILL——它记录了一个警告,因为它的端口可能仍然被持有。 只有第一次重启是这样做的:当一个替换者再次重启时,等待重启完成后再拆除.

`options.graceMs` 超过 SIGTERM- SIGKILL 宽限期( 默认) `5000`,或 `HARPER_INTEGRATION_TEST_TEARDOWN_GRACE_MS`) (中文(简体) ).

### `teardownHarper(ctx)`

杀死哈珀的进程树,将回回地址放回池中,并去掉安装目录. 催泪瓦斯/`after()` 钩.

自兹 `killHarper` 等待进程树退出,其固定端口(Operations API,HTTP/S,MQTT/S)在地址被再生时已经发布. 作为安全主张,拆卸仍在核查这些港口在回收之前是免费的——池子只保证 _地址_ 可绑定,而不是说这些特定端口是自由的——如果仍然持有(一个哈珀进程标志逃脱了 kill),它会记录一个警告,并同时留下地址和安装目录:该位点会一直被停放,直到这个进程退出,因此后期的套件无法与端口相并存,在仍然持有这些位点的过程中目录不会被删除.

如果杀死本身无法确认——哈珀宣布重启,但替换者从未记录过它的pid,或者一个进程已过期的SIGKILL——拆卸记录一个警告并留下安装目录和地址,而不是在可能仍在运行的进程中删除目录. 这会拖得一塌糊涂 `killHarper` 已经警告过:停站一直没有经过证实,直到替换人员消失为止.

**环境变量:**

-   `HARPER_INTEGRATION_TEST_TEARDOWN_GRACE_MS` - 在SIGKIL升入SIGTERM之前的Grace期 默认 `5000`。 。 。 .
-   `HARPER_INTEGRATION_TEST_PORT_RELEASE_TIMEOUT_MS` - 最大时间撕毁的安全主张等待哈珀的端口在循环回回回地址(通常是即时的,因为过程树已经枯萎了)之前是自由的. 默认 `5000`。 。 。 .
-   `HARPER_INTEGRATION_TEST_RELAUNCH_WAIT_MS` - 经过哈珀程序,宣布 `restart` 重启退出, 多长时间 `killHarper` 等待替换者记录其pid. 默认 `5000` (单位:千美元)`15000` 页:1.

### `sendOperation(context, operation)`

帮助 POST 操作到操作 API 并声明 HTTP 200 .

### `createHarperContext(name?)`

创建满足的普通对象 `HarperTestContext`,用于外部 `node:test` (例如,Playwright工人固定装置). 这个 `name` 是可选的,用于日志目录命名.

```ts
// Playwright example
const ctx = createHarperContext(`worker-${workerInfo.workerIndex}`);
await startHarper(ctx);
```

### 类型

有四种相关的TypeScript类型——帮助理解它们如何作曲.

**`HarperContext`** 是实例数据对象存储于 `ctx.harper` 之后 `startHarper()` 决定。 它描述了一个运行中的哈珀实例:

```ts
interface HarperContext {
  dataRootDir: string;          // absolute path to the Harper install directory
  admin: { username: string; password: string };
  httpURL: string;              // e.g. 'http://127.0.0.2:9926'
  operationsAPIURL: string;     // e.g. 'http://127.0.0.2:9925'
  hostname: string;             // e.g. '127.0.0.2'
  process: ChildProcess;
  logDir?: string;              // set when HARPER_INTEGRATION_TEST_LOG_DIR is configured
  startupOutput?: { stdout: string; stderr: string }; // captured startup output
}
```

**`HarperTestContext`** 是被 `startHarper()`, (中文(简体) ), `setupHarperWithFixture()`, (中文(简体) ), `killHarper()`,以及 `teardownHarper()`。它故意松开,以便它能被普通物体或 `node:test` 语境 :

```ts
interface HarperTestContext {
  name?: string;                // used for log directory naming
  harper?: Partial<HarperContext>;  // populated by startHarper()
}
```

**`StartedHarperTestContext`** 与 `HarperTestContext` 不过 `harper` 保证人口充足 `HarperContext`它是返回类型 `startHarper()` 财务报告和审定财务报表 `setupHarperWithFixture()`参数类型 `killHarper()` 财务报告和审定财务报表 `teardownHarper()`数字 :

```ts
interface StartedHarperTestContext extends HarperTestContext {
  harper: HarperContext;
}
```

**`ContextWithHarper`** 用于 `node:test` 只有这个 它延伸了两者 `SuiteContext` 财务报告和审定财务报表 `TestContext` 从 `node:test` 与 `harper: HarperContext`,因此,您可以将其作为一个 `suite()` 回调 :

```ts
// node:test usage
suite('my suite', (ctx: ContextWithHarper) => {
  before(async () => { await startHarper(ctx); });
  after(async () => { await teardownHarper(ctx); });

  test('example', async () => {
    const res = await fetch(ctx.harper.httpURL);
  });
});
```

如果你没有使用 `node:test`,使用时 `createHarperContext()` 创建平原 `HarperTestContext` 换句话说.

### 孤儿事件监测员(POSIX)

试跑者死而不掉 `SIGKILL`困难的崩溃,一个被取消的CI工作——不能收获它开始的哈珀事件,因为这些事件被故意分解为自己的流程组,这样整条树的倒塌才能奏效. 独自一人,他们持有他们的回转地址的固定端口,直到机器被重启.

为了缩小这一差距, `startHarper()` 在小盘上注册每个实例,并确保一个共享 **显示器** 进程正在运行。 显示器不是随身携带的一款:一款是按每个登记簿目录(机器上的每个用户,默认情况下)的要求启动的,每个同时跑者都会重新使用它,一旦登记册空出一段时间,它就会退出. 注册更新通过将完整的文件更名而发布,因此被杀死的跑者会离开上一个注册——因此其他跑者收获目标——完好无损. 它在间隔时间扫描登记册并终止—— `SIGTERM`,则 `SIGKILL` 在一段宽限期之后——任何本身的跑者已经离开,或已超过其终身预算的情况的流程组。 实例匹配为 PID _财务报告和审定财务报表_ 进程启动时间,它缩小了PID再利用,而不是消除它——一个回收的PID `ps` 仍然可以描述 被拒绝,在一个主机 `ps` 无法报告一个启动时间( busybox/ Alpine) , 它会降解为只检查 PID 的检查, 显示器在启动时会日志 .

记录描述一个过程 _组_,而不是一个过程,而显示器是唯一可以删除一个过程的——当该组没有成员离开的时候. 哈珀退出不是组的结束:一个无视 `SIGTERM` 留在里面, 仍然持有端口, 记录是记得 集团足够长的时间升级到 `SIGKILL` 或当它的跑者死后收获它.

跑者自己来的 `exit`编号 :`SIGINT`编号 :`SIGTERM`编号 :`SIGHUP` 操作者仍然在它能观察到的任何出口上立即接收到实例;监视器只处理它不能处理的死亡.

登记册目录布局`${TMPDIR}/harper-integration-test-monitor-${uid}` 默认情况下 —— 每个用户, 因为给另一个用户的进程组信号失败 `EPERM` 绝不然

| 文件 | 目录 |
| --- | --- |
| `registry.json` | 当前显示器和每个已注册实例( PID、 启动时间、 拥有运行器、 回回地址、 截止日期) |
| `registry.lock` | 跨进程 mutex 守护 `registry.json` |
| `monitor.log` | 仅附上监视器启动/退出和每次收获的记录,并说明原因 |
| `registry.json.*.pending` | 正在写入登记册更新, 重新命名为 `registry.json` 完成后,没有读者看到一个部分。 只有暂时存在,或者被中后期被杀死的作家留下 |

每个管理好的哈珀进程也携带 `HARPER_IT_KIND=harper-instance`, (中文(简体) ), `HARPER_IT_INSTANCE_ID`,以及 `HARPER_IT_OWNER_PID` 显示器的指令行包含 `--harper-integration-test-monitor`,所以两者都可以从 `ps` 编号 : `/proc` 未经登记.

这是 POSIX 唯一的: 收割依赖于进程组, Windows 没有这些组. 在Windows上,注册被跳过,跑道侧清理处理器是唯一的保护.

**环境变量:**

-   `HARPER_INTEGRATION_TEST_MONITOR` - 准备 `off` 以完全禁用注册和显示器。 默认(仅限POSIX).
-   `HARPER_INTEGRATION_TEST_MONITOR_DIR` -登记簿 默认 `${TMPDIR}/harper-integration-test-monitor-${uid}`。在单独的目录中点出单独的运行,以给它们单独的显示器.
-   `HARPER_INTEGRATION_TEST_MONITOR_INTERVAL_MS` - 监视器多久重新扫描一次登记册。 默认 `2000`。 。 。 .
-   `HARPER_INTEGRATION_TEST_MONITOR_REAP_GRACE_MS` - 显示器和SIGKILL之间的格蕾丝期 默认 `5000`。 。 。 .
-   `HARPER_INTEGRATION_TEST_MONITOR_IDLE_MS` - 在显示器关闭之前,登记册必须保持空置多久。 默认 `60000`。 。 。 .
-   `HARPER_INTEGRATION_TEST_INSTANCE_MAX_LIFETIME_MS` - 后站的一生, 之后一个案例被收获 即使它的跑者看起来还活着。 默认 `14400000` (4小时).

### 服务器日志抓取

何时 `HARPER_INTEGRATION_TEST_LOG_DIR` 每个哈珀实例将其日志写到一个每套子目录。 日志保存在日志目录的寿命. 在CI中,结合文物上传步骤,在无法捕获出故障运行日志时运行.

```sh
HARPER_INTEGRATION_TEST_LOG_DIR=/tmp/harper-test-logs npx harper-integration-test-run "integrationTests/**/*.test.ts"
```

此外, `startupOutput` 打开 `HarperContext` 提供从哈珀启动时捕获的stdout/stderr用于程序访问(例如附加在Playwright测试结果上).

在测试失败时,跑者还打印出哈珀节点的尾巴 `hdb.log` 到操纵台。 一旦时间戳被剥去(例如,重复的民意测验),连续行的行数相同,倒入一行外加一行 `(repeated N times)` 在取出尾巴前加标记,这样高吵的重复行不会将实际出错推出打印窗口. 磁盘上的日志文件从未被修改 .

-   `HARPER_INTEGRATION_TEST_LOG_TAIL_LINES` - 跟踪次数(崩溃后) `hdb.log` 每个失败的测试打印行( 边界若不拆分, 另打印一行) `(repeated N times)` 标记从它算起的行)。 默认 `200`。 。 。 . `0` (或任何非正值)会打印出整个日志,不折叠.

### `HarperStartupError`

当哈珀未能启动或出局时, a `HarperStartupError` 被抛出。 它延伸 `Error` 包括结构化 `stdout` 财务报告和审定财务报表 `stderr` 诊断属性 :

```ts
import { HarperStartupError } from '@harperfast/integration-testing';

try {
  await startHarper(ctx);
} catch (error) {
  if (error instanceof HarperStartupError) {
    console.error('Startup failed:', error.message);
    console.error('stdout:', error.stdout);
    console.error('stderr:', error.stderr);
  }
}
```

### `ForeignListenerError`

被丢弃 `getNextAvailableLoopbackAddress`,因此 `startHarper`,当另一个进程已经接受新分配地址的操作或HTTP端口的连接,或者通过所有接口的监听器在其哈珀端口的Linux上连接(参见 [其他在哈珀港口收听的服务](https://npmcn.com/package/%40harperfast/integration-testing/#readme-other-services-listening-on-harpers-ports)) (中文(简体) ). 它延伸 `Error` 与 `name` 设置为 `'ForeignListenerError'`附加时 `loopbackAddress` 财务报告和审定财务报表 `port` 属性命名所达到的内容。 地址在抛出错误前发布. 设定 `HARPER_INTEGRATION_TEST_ALLOW_FOREIGN_LISTENERS=1` (或 `true`)来得到警告.

### `LoopbackPoolExhaustedError`

被丢弃 `getNextAvailableLoopbackAddress`,因此 `startHarper`,当没有地址在内部自由 `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_TIMEOUT_MS` (默认) `600000`10分钟). 它延伸 `Error` 与 `name` 设置为 `'LoopbackPoolExhaustedError'`。消息给出了集合范围,对于每个控件进程,它所持有的地址是:它的pid,与这个进程不同时的PID命名空间,以及不同时的主机名称。 它还列出了一个进程所持有的、没有表明身份的任何地址,任何未声明地址的哈珀节点仍然有约束。 同一份清单记录为 `[loopback-pool]` 警告等待时间达到30秒(或超时时间的四分之一,如果更短)。 见 [循环池公用事业](https://npmcn.com/package/%40harperfast/integration-testing/#readme-loopback-pool-utilities)。 。 。 .

### `targz(dirPath)`

将一个目录包并压缩成一个基数64-编码的tar.gz字符串. 用于 `deploy_component` 操作API呼叫.

### 循环池公用事业

这些是内部使用的: `startHarper` 财务报告和审定财务报表 `teardownHarper`,但用于高级用途或自定义跑道集成.

-   `validateLoopbackAddressPool(): Promise<{ successful: string[]; failed: { loopbackAddress: string; error: Error }[] }>` - 验证所有池地址可以约束
-   `getNextAvailableLoopbackAddress(): Promise<string>` - 从游泳池中分配一个地址,如果所有地址都持有,则等待释放 `ForeignListenerError` 如果另一个进程已经接受在其操作或HTTP端口上的连接(参见 [其他在哈珀港口收听的服务](https://npmcn.com/package/%40harperfast/integration-testing/#readme-other-services-listening-on-harpers-ports)),或 a `LoopbackPoolExhaustedError` 如果等待超过时间 `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_TIMEOUT_MS`
-   `releaseLoopbackAddress(address: string): Promise<void>` - 将地址返回池中
-   `releaseAllLoopbackAddressesForCurrentProcess(): Promise<void>` - 发布这一进程中的所有地址

进程通过倾听其 **索赔端口** (单位:千美元)`HARPER_INTEGRATION_TEST_LOOPBACK_CLAIM_PORT`默认值 `9924`) (中文(简体) ). 内核允许每个地址和端口有一个收听器,因此,虽然一个进程持有一个地址,但没有任何其他进程可以声称它. 内核在进程退出时也会关闭收听器,而不管它退出. 这涵盖了一个网络命名空间中的每一个过程,即一个地址上的两个哈珀节点会相撞,不管它们的PID命名空间或 `TMPDIR`. 单独的网络命名空间中的进程,如大多数容器,都有单独的回回接口,不能相撞. 机器上的每跑一次都必须使用同一权利港。 没有写到磁盘上.

分配取第一个地址,其索赔端口是免费的,所以一个过程留下的地址一次重复使用. 然后跳过一个地址,哈珀的操作,HTTP,HTTPS,MQTT或MQTTS端口仍然被绑定,例如被一个节点所活过一个被杀死的测试跑者,然后尝试下一个. 复制没有选中: Harper-pro的默认复制端口没有主机, 所以每个节点都会将它绑在所有接口上. 放弃一个地址只能解除这一程序所持有的权利.

当每个地址被保留时,分配要等到 `HARPER_INTEGRATION_TEST_LOOPBACK_POOL_TIMEOUT_MS` (默认) `600000`然后丢出一个 [`LoopbackPoolExhaustedError`](https://npmcn.com/package/%40harperfast/integration-testing/#readme-loopbackpoolexhaustederror) 命名持有人,而不是永远等待。 如果套房合法排队的时间长于此,则提高暂停时间。 要命名它的持有者,一个权利要求会回答一个与JSON一行的连接:它的过程的pid,PID命名空间和主机名. 分配本身从未与索赔挂钩.

版本 1. 0.5 , 并更早保存该池作为进程 ID 的文件 `${TMPDIR}/harper-integration-test-loopback-pool.json`。他们不看到索赔,这个版本不读该文件。 在机器上每次运行都使用这个版本之前,两人都可以在任何一个开始其节点之前将一个地址发到两个运行. 在切换前, 让旧版本运行完成 。 然后可以删除旧文件 .

## 节点.js 测试运行器

> 此导师执行的测试必须使用 `node:test` API (英语). 如果使用不同的测试框架,请使用 [寿命周期 APIs](https://npmcn.com/package/%40harperfast/integration-testing/#readme-api) 直接提及 [运行源](https://npmcn.com/package/%40harperfast/integration-testing/src/run.ts) 作为参考执行.

包含的内容 `harper-integration-test-run` 脚本是哈珀整合测试的推荐方式. 它建在节点上 `node:test` API 并处理 [原始平行分析](https://github.com/Ethan-Arrowood/node-test-runner-parallelization-analysis):因为每次集成测试都会产生资源密集型的哈珀过程,所以安全默认的同分币大约是可用系统并行性的一半,而不是节点. js 的默认 `availableParallelism() - 1`。 。 。 .

跑者执行每个测试 **文件** 也就是说文件是隔离的单位 为了安全和可预测地进行这项工作,每个测试文件必须坚持报告中所述的独立、隐含和决定性能 [测试 Ethos](https://npmcn.com/package/%40harperfast/integration-testing/#readme-testing-ethos)。严格遵循这些属性可以使文件同时运行而不相互干扰。 当一个测试中断时,该文件可以被孤立地运行到固定上,而不重新运行一切.

这个 [哈珀整合测试](https://github.com/HarperFast/harper/tree/main/integrationTests) 是一个开源实例,说明这一跑道和生产使用框架.

### 运行测试

```sh
npx harper-integration-test-run "integrationTests/**/*.test.ts"
```

或加进你的 `package.json`数字 :

```json
{
  "scripts": {
    "test:integration": "harper-integration-test-run integrationTests/**/*.test.ts"
  }
}
```

### 运行者选项

所有 CLI 参数都可用关联方式推翻 `HARPER_INTEGRATION_TEST_*` 环境变量.

| CLI 参数 | 环境变量 | 默认 | 说明 |
| --- | --- | --- | --- |
| `--concurrency=N` | `HARPER_INTEGRATION_TEST_CONCURRENCY` | `floor(parallelism/2)+1` | 并行试验程序的数目 |
| `--isolation=mode` | `HARPER_INTEGRATION_TEST_ISOLATION` | `process` | `process` 或者说 `none` |
| `--shard=index/total` | `HARPER_INTEGRATION_TEST_SHARD` | `1/1` | CI 测试硬化 |
| `--only` | `HARPER_INTEGRATION_TEST_ONLY` | `false` | 只运行标记为 `.only` |

示例 - 连续运行,无回放池 :

```sh
npx harper-integration-test-run --isolation=none "integrationTests/**/*.test.ts"
```

实例 - CI在4个工作上硬化:

```sh
npm run test:integration -- --shard=1/4
npm run test:integration -- --shard=2/4
npm run test:integration -- --shard=3/4
npm run test:integration -- --shard=4/4
```

### 写入测试

测试文件应以ESM TypeScript 书写,以 `.test.ts`,然后从一个评论块开始,描述它们核实的内容。 文件名称应短而连字符分隔——例如, `install.test.ts` 或者说 `application-management.test.ts`。 。 。 .

测试应使用 `suite`编号 :`describe`, (中文(简体) ), `test`编号 :`it`,以及寿命周期方法`before`, (中文(简体) ), `beforeEach`, (中文(简体) ), `after`, (中文(简体) ), `afterEach`从 `node:test`的断言 `node:assert/strict`。 。 。 .

一个测试文件可以包含多个套房. 衣服总是跑 **按顺序**组合运行中的测试 **默认顺序**,但可以与 `{ concurrency: true }` ——在这种情况下,该套套房内的每个个别测试必须本身是独立的,具有隐蔽性和决定性的.

由于这些测试与运行中的哈珀实例相互作用,它们经常验证实际应用输出:标准流(`stdout`编号 :`stderr`),网络响应,或文件系统状态.

#### 套接字货币示例

这个文件包含两个套房,每个套房有两个1秒的测试. 第一个套房可以 `{ concurrency: true }`,第二个没有.

```ts
import { suite, test } from 'node:test';
import { setTimeout as sleep } from 'node:timers/promises';

suite('Concurrency Enabled', { concurrency: true }, () => {
  test('1 second', async () => {
    await sleep(1000);
  });

  test('1 second', async () => {
    await sleep(1000);
  });
});

suite('Concurrency Disabled', () => {
  test('1 second', async () => {
    await sleep(1000);
  });

  test('1 second', async () => {
    await sleep(1000);
  });
});
```

-   第一套房的测试同时进行 ~~ 1秒
-   第二套房的测试按顺序进行 ~~2秒
-   服饰总是按顺序运行 ~ **总计~3秒**

```
▶ Concurrency Enabled
  ✔ 1 second (1001.359083ms)
  ✔ 1 second (1001.860375ms)
✔ Concurrency Enabled (1002.26125ms)
▶ Concurrency Disabled
  ✔ 1 second (1001.122166ms)
  ✔ 1 second (1000.5495ms)
✔ Concurrency Disabled (2001.850625ms)
ℹ tests 4
ℹ duration_ms 3087.786041
```

#### 模板

```ts
/**
 * Description of what this test file verifies.
 */
import { suite, test, before, after } from 'node:test';
import { strictEqual } from 'node:assert/strict';
import { startHarper, teardownHarper, type ContextWithHarper } from '@harperfast/integration-testing';

suite('short description', (ctx: ContextWithHarper) => {
  before(async () => {
    await startHarper(ctx);
  });

  after(async () => {
    await teardownHarper(ctx);
  });

  test('test description', async () => {
    const response = await fetch(ctx.harper.httpURL);
    strictEqual(response.status, 200);
  });
});
```

### 使用其他框架

生命周期 API 与任何支持 Aync 设置和被撕毁的框架相配合. 这个 [运行源](https://npmcn.com/package/%40harperfast/integration-testing/src/run.ts) 具体参考了节点Js如何 `node:test` 整合被连接起来,包括货币配置和硬性支持。 在为另一个框架建立一体化时,把它作为起点.

## GitHub 动作并行

一体化测试应当有效和可靠地运行在CI上,而不仅仅是在当地进行. 随着测试文件数量的增加——通过验证多个操作系统或运行时间版本而进一步复杂化——即使是一个微小的测试套件也可以成为大型的CI操作. 目标是在成本和彻底之间取得平衡。 测试必须始终可靠运行;正确性绝不因速度而受到损害. 超载跑跑者会造成片状故障.

**默认 GitHub 动作跑者性能有限 .** 他们可以合理处理单一的集成测试,但将其中很多同时进行,往往会超过跑者的能力. 建议的战略是: **使用工作流程矩阵任务在多个执行者之间实现平行** 结合 **测试硬化** ——在跑者之间分发测试文件,而不是全部运行在一上.

较大的跑道可供使用,但成本会增加。 正确的取舍取决于您组织的CI工作总量,因为平行的工作执行通常在Org级别上限. 当可供选用跑车的等待时间开始超过平行化节省的时间时,较大跑车的工作减少可能更有效.

也值得考虑一下 _何时_ 完全整合套房运行。 在每一个公开的PR的每个承诺上运行所有支持的配置的每个测试,可以快速地用尽货币限制. 文件路径过滤触发器等策略,手动触发了工作流程,将完整的矩阵限制为合并时间检查,可以保持CI响应而不会牺牲覆盖.

A 类 **合并队列** 值得考虑的最后一点——仅在公钥通过初始检查(例如单一配置)后运行完整的矩阵,然后在合并前验证完整的矩阵。 这样可以更快地进行PR重迭,同时保持主分支的彻底测试.

这个 [哈珀整合测试工作流程](https://github.com/HarperFast/harper/blob/main/.github/workflows/integration-tests.yml) 这是这些战略的实际实例.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @harperfast/integration-testing 是什么？

Harper项目的综合测试设施。 提供哈珀实例生命周期管理,回回地址集合,以及测试跑取脚本\.

### 如何安装 @harperfast/integration-testing？

在项目目录运行 npm install @harperfast/integration-testing，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：harper（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 harper-integration-test-run、harper-integration-test-setup-loopback，可以用 npx harper-integration-test-run 直接运行。

### @harperfast/integration-testing 支持 TypeScript 吗？

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

### @harperfast/integration-testing 支持 ESM 还是 CommonJS？

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

### @harperfast/integration-testing 需要什么版本的 Node\.js？

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

### @harperfast/integration-testing 可以商用吗？

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

### @harperfast/integration-testing 的下载量有多少？

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

### @harperfast/integration-testing 还在维护吗？

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

