# @ghostry/harness 中文文档

规范地址：https://npmcn.com/package/%40ghostry/harness/

版本：0\.0\.6
npm 元数据更新时间：2026-11-02T00:17:43.434Z
中文译文更新时间：2026-11-16T08:33:25.761Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：142 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2026-09-11T03:22:49.882Z
- 最新版本发布：2026-11-02T00:17:43.074Z
- 近 30 天下载量：2386（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

一个针对Jest兼容测试框架的集成的上下文感包.

## 安装

```sh
npm install @ghostry/harness
```

也可以使用：`pnpm add @ghostry/harness`、`yarn add @ghostry/harness`、`bun add @ghostry/harness`

## README

# @ghostry/ harness (恶作剧)

**一个集成的包件 在一个与Jest兼容的测试框架之上.**

每个幽灵图书馆都有同样的API. 框架是一个参数,从不导入——这个包的运行时间依赖度为零.

[![npm](https://img.shields.io/badge/npm-ffffff.svg?style=for-the-badge&color=000000&logo=npm&logoColor=CB3837)](https://www.npmjs.com/package/@ghostry/harness) [![jsr](https://img.shields.io/badge/jsr-ffffff?style=for-the-badge&color=000000&logo=jsr&logoColor=F7DF1E)](https://jsr.io/@ghostry/harness) [![github](https://img.shields.io/badge/github-ffffff?style=for-the-badge&color=000000&logo=github&logoColor=ffffff)](https://github.com/ghostry-dev/harness) [![typescript](https://img.shields.io/badge/typescript-ffffff?style=for-the-badge&color=000000&logo=typescript&logoColor=3178C6)](https://npmcn.com/package/%40ghostry/harness/#) [![bun](https://img.shields.io/badge/bun-ffffff?style=for-the-badge&color=000000&logo=bun&logoColor=FBF0DF)](https://npmcn.com/package/%40ghostry/harness/#) [![node](https://img.shields.io/badge/node-ffffff?style=for-the-badge&color=000000&logo=nodedotjs&logoColor=5FA04E)](https://npmcn.com/package/%40ghostry/harness/#)

## 安装

```bash
npm install @ghostry/harness
```

## 示例

```ts
import { initialize as initializeFabricator } from "@ghostry/fabricator";
import { initialize as initializeHarness } from "@ghostry/harness";
import { integration as fabricatorIntegration } from "@ghostry/fabricator/harnessing";
import * as framework from "bun:test";

/**
 * One fixed instant for the whole suite: every test and hook shares this "now,"
 * and the test path alone varies the data. Without it the clock is the
 * wall-clock instant of this call, and the suite stops reproducing across
 * runs.
 */
export const fabricator = initializeFabricator({
  clock: new Date("2024-01-01T00:00:00Z"),
});

export const { describe, it, expect } = initializeHarness({
  framework,
  integrations: [fabricatorIntegration(fabricator)],
});
```

将此放入一个设置模块,并从每个测试文件中导入. 在面包上,这需要1.2.23或以后: 早期的版本绑起一个模块的 `bun:test` 导入到装入它的第一个测试文件,所以以后的每个文件的测试都会在没有出错的情况下被丢弃——不管有没有这个库. 在一个更老的包子上,从设置模块中导出一个功能,这个功能将使用框架并调用 `initialize`,并拥有每个测试文件的通过 `import * as framework from "bun:test"`。 。 。 .

`@ghostry/harness` 取决于编织者或跑者 整合满足 `{ name, provides, frame? }` 结构: `provides` 是上下文密钥的映射 `({ identity, established }) => value` 并且是这种整合键的唯一来源,因此没有任何东西可以单独宣布,也没有东西可以命名一种组合键实际上没有贡献.

`frame` 是一个有一台发电机的每个测试寿命周期 `yield`在它被设置之前, 身体运行在它, 之后的一切都是被撕裂的:

```ts
*frame() {
  const tx = openTransaction();
  try {
    yield;          // the test body runs here
  } finally {
    tx.rollback();  // runs when the body settles, sync or async
  }
}
```

那个 `try`编号 :`finally` 意思是它看起来像什么, 一个召回不能。 第一次在同步机体回调 `await`,因此,这是 `finally` 测试中间点起火来,从里面无法调用到它。 它会修正: 函数调用不能暂停调用器, 而唯一两个中止函数的构造是 `await` (这能改变你们所返回的)和 `yield` (这是 `frame`” .

当身体必须运行 **内部** 某事 - 一个 `AsyncLocalStorage` 范围, 图书馆本身 `wrap`,集合连接的回调——产生包接功能. 它接收身体,在它需要的地方运行它,并返回它的价值不变。 无论它传递给 `body` 联系您的提供者 :

```ts
provides: { db: ({ established: tx }) => tx },
*frame({ identity }) {
  try {
    yield (body) => withConnection(identity, (tx) => body(tx));
  } finally {
    report(identity);
  }
}
```

撕裂在包裹的瞄准镜内 所以 `AsyncLocalStorage` 打开的值仍然可以在 `finally`需要在里面的设置会进入包装器内部, 因为代码之前 `yield` 在应用包装之前运行.

平时什么情况都没有. `async function*` 由于同步发生器会同步恢复,而且无处可等,因此需要进行试验,并进行必须等待的拆解。 被撕下最先横穿整合,一个外层则等待一个内层同步的,在你的一侧没有命令逻辑:每个框架都围住下个框架,这样就可以进行排序.

每一个测试机构都得到一个 `context` 参数 – 每个整合的贡献合并为一个目标. 这些密钥是只读的,在运行时不可写入以匹配:对象每测试一次被刻出,所以重新指派一个就一无所获. 它很浅 (整合本身的价值是您想要使用的) 对象仍然可以延伸,所以 `beforeEach` 可以留下自己的钥匙给身体。 身份是测试路径( I)`describe` 名称 – 测试名称),而非文件: 两个测试相同路径的测试即使在不同文件中也画出相同的每个测试范围. 路径由固定的链接构建,当 `describe` 被调用,而不是从堆栈中打出 作为回调,所以它不依赖于 _何时_ 跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跳跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑呼回--------跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑 `node:test` 引用一个内线, 而包子、活字和rstest 则推迟,直到后面的回调返回.

目前这个包 `describe`编号 :`it`编号 :`test`他们 `.only`编号 :`.skip`编号 :`.todo`编号 :`.failing`编号 :`.concurrent` 修饰者, `.skipIf`编号 :`.todoIf`编号 :`.failingIf`, (中文(简体) ), `.each` 和钩子。 被包裹的表面取自您框架自己宣布的类型,因此它只有在跑道实际拥有一个时才提供一个转发的修饰符—— `it.failing` 没有在vitest和rstest, 它的拼写 `fails`,以及 `describe.todo` 开玩笑的缺席. `.each` 例外:这个图书馆扩充了它,而不是转发,所以它总是可供使用,包括没有本地语言的跑者 `.each` 例如 `node:test` 还有摩卡. `.each` 接收机构 `{ ...context, row }` ——行是地产,不是立场论证——和 `identity.row` 是该行的索引。 给一个 `describe.each` 标题`describe.each(rows)("case $name", …)`:套接字行只通过内插名来到达身份,而两个同名行内的测试本会共享一个范围. 指数符号基于 0 (`$#`, (中文(简体) ), `%#`与欢笑相伴 `%$` 用于基于1的表格.

Hooks在他们的身份是否需要每一次测试信息上分裂. `beforeAll`编号 :`afterAll` 以套件身份在编组框架内运行(`kind: "suite"`, (中文(简体) ), `name: ""`——它们只在跑者宣布时出现. `beforeEach`编号 :`afterEach` 完全不与跑者注册:它们被收集到套房节点和包裹上 `it` 在测试本身的框架内运行它们,因此它们得到的上下文对象与机体相同的,并共享其集成框架. 这也是为什么他们总是在场,甚至在没有本土钩子的跑道上也是如此.

A 类 `beforeEach`编号 :`afterEach` 没有套房投出 `AmbientHookError`。在文件的顶层,没有套房来按键, 并且与推荐的一..`initialize` 共享模块包包将运行一个文件的顶级钩子,用于每个文件的每个测试——放入一个 `describe`,或使用 `framework.beforeEach` 通过逃生舱门,接受 向那里发送的钩子没有上下文。 相同的错误覆盖一个环境钩,在 之后叫做 `await` 在演讲中 `describe`,指针已经恢复的; 定点就是 `it` 已经需要了,下面,从套房范围取出钩子.

发送费用 `beforeEach`编号 :`afterEach` 在测试中:

-   A 类 `beforeEach`编号 :`afterEach` 失败表面为 **测试** 失败,不是钩子失败。 运行器输出和时间归属改变.
-   虎克时间与 **测试** 暂停 .
-   每小时选项在类型级别被拒绝 `beforeEach`编号 :`afterEach`· ; `beforeAll`编号 :`afterAll` 保持框架分发并保存.
-   一个配置 `beforeEach` 总是运行 **内部** 任意 `framework.beforeEach`,无论宣布命令。 用户想要跑步级别的钩子语义学使用出逃舱门.
-   `.skip`编号 :`.todo` 尸体从不跑 所以他们的钩子从不跑 匹配框架.
-   A 类 `beforeAll` 登记后 `await` 在演讲中 `async` 描述跑道上的土地 _拥有_ 当前套房,它已经继续运行了 —— 包裹的同样危险 `it` 已经共享 . `beforeEach`编号 :`afterEach` 他们不会碰跑者.
-   在一个路径上有两个套件身份(a) `beforeAll` 还有一个 `afterAll` 在一个 `describe`共享一个身份。 这种碰撞是故意的.

每个钩子都有套装框 _调用_,而不是每个套房: 整合 `frame` 编号 `beforeAll` 当钩子返回时关闭 而不包套房的测试。 集成按构造将用户钩包起来(在每次安装之前设置) `beforeEach`,在每次拆分之后 `afterEach`,而一个包装器 夹住两者, 所以它打开的瞄准镜是活的 `afterEach` 绝不然,而且不能与他们接触.

出逃舱口是未被包裹的舱口,因此无法维护路径. A 类 `framework.describe` 环绕一圈 `it` 默默地从身份中去掉这个名字,里面的测试画出更浅的路径的范围. 带包裹的组合 `describe` 并达到 `framework` 只为那些不能遮盖者 `beforeEach`编号 :`afterEach`,跑道特异性匹配者.

一个 `async` 描述回调以更微妙的形式存在同样的问题。 它刚回来 `await`,所以环境 `it` 不再解决该套房 在封闭的注册运行时。 宣布套房范围,他们从逻辑上解决问题 `await` 无法打扰——调整结构,身体读取准确如:

```ts
describe("parser", async ({ it }) => {
  const cases = JSON.parse(await readFile("cases.json", "utf8"));
  for (const entry of cases) it(entry.name, (context) => { … });
});
```

范围包含 `describe`, (中文(简体) ), `it`, (中文(简体) ), `test`,四个钩子绑在那个套房上;一个有巢的套房有自己的套房. `expect` 上面不是因为它不依赖路径.

宣布参数是选入,并且 `async` 召回不丢一个 `AsyncDescribeError` 命名套房——它没有办法处理其注册问题,并将在更浅的路径上存档。 一旦处理完毕,可处理器就交给跑道员,每人按其一贯做法收集(bun、vitest、rstest和 `node:test` 等待吧,你们嘲笑他 `async` 描述; mocha 丢弃 1 中的测试).

## 狭隘的言论

`expect(user.address).toBeDefined()` 请检查值但不能告诉 TypeScript 有关它的内容 : `expect(x)` 返回匹配对象,该对象上的方法无法缩小 `x` 你错过了 所以下一行到达 `!`, (中文(简体) ), `?.` 或一个演员. `initialize` ưμ㼯a `attest`一连串的断言,每一次通话 都会被束缚在跑者身上 `expect`数字 :

```ts
import { initialize, type Attest } from "@ghostry/harness";
import * as framework from "bun:test";

export const harness = initialize({ framework, integrations });
export const { describe, it, expect } = harness;
export const attest: Attest = harness.attest;
```

需要附加说明。 TypeScript 只在呼叫中每个名称被明确类型宣布时,才会通过一个断言来缩小范围,这意味着您绑定,而不是库名. 建筑结构从不合格 连注解都不行 `harness.attest.definite(…)`。把它弄错了,而这个呼叫是一个编译错误(TS2775),绝不是沉默地缩小。 共享设置模块中的一行覆盖每个导入它的测试文件.

| 成员 | 关于成功 |
| --- | --- |
| `definite(value)` | 缩进 `value` 改为: `null` 也没有 `undefined` |
| `definitely(value)` | 返回时 `value`,键入方式相同,用于表达式 |
| `instanceOf(value, Class)` | 缩进 `value` 证明: `Class` |
| `variant(value, "kind", "err")` | 将受歧视的工会缩小为: `kind: "err"` 成员 |
| `that(value, isFoo)` | 缩进 `value` 通过你自己类型的警卫 |
| `throws(Class, () => …)` | 返回函数所抛出的东西,作为实例 `Class` |
| `rejects(Class, promise)` | 决定拒绝理由,作为 `Class` |

```ts
const error = attest.throws(HarnessError.EachTableError, () => it.each([]));
expect(error.reason).toBe("empty");

attest.variant(event, "kind", "err");
expect(event.message).toBe("timed out");

expect(attest.definitely(users[0]).name).toBe("Ada");
```

`definite` 通过 `0`, (中文(简体) ), `""` 财务报告和审定财务报表 `false`: 仅 `null` 财务报告和审定财务报表 `undefined` 失败,因为那是 `NonNullable` 移除. `definitely`, (中文(简体) ), `throws`,以及 `rejects` 因此他们不需要任何注释. `throws` 运行您的函数一次, 如果它返回一个承诺, 则失败 `rejects`工作; `rejects` 接受一个承诺或函数返回一个,并将该函数的同步抛出算作拒绝。 检查值的会员先拿,所以 `instanceOf(value, Class)` 以它所声称的句子为准; `throws` 财务报告和审定财务报表 `rejects` 将类取为第一,所以多行函数最后坐落在召回位置. 每个成员都会选择跟踪 `label` 命名对象,该对象出现在失败中.

失败是你的跑者自己的。 每个成员首先给匹配者打电话(`toBeDefined`, (中文(简体) ), `toBeInstanceOf`, (中文(简体) ), `toThrow`, (中文(简体) ), `rejects.toThrow`.) 所以你得到跑者的信息和diff, 然后再次检查自己,扔 `HarnessError.AttestationError` 如果跑者让它通过。 第二次检查使得一个跑者的声音越来越小 `expect` 缺少匹配者或不投出。 在包子上,源取出一个出故障点到这个包而不是你的行:包子取出所抛出线条,这是内部的匹配者呼叫 `attest`下方的堆放痕迹仍为您命名.

## 重写集成的密钥

一个集成名称 它所贡献的密钥, 默认情况下,你把它们当作它运送它们. `remap` 包入一个集并重写地图——重命名一个密钥,将一个嵌入的值提升到根上,放下一个你不想的,或者添加一个你自己的:

```ts
import { initialize, remap } from "@ghostry/harness";
import { integration as externIntegration } from "@ghostry/extern/harnessing";

export const { describe, it, expect } = initialize({
  framework,
  integrations: [
    remap(externIntegration(), {
      provides: { mock: ({ provided }) => provided.extern.mock },
    }),
  ],
});
```

现在读作 `context.mock`,以及 `context.extern` 已消失 —— 重映射不删除名称的密钥 . `provided` 是由被包裹的整合本身的背景,从您所经过的整合中打出,一个被重写提供商收到一个普通人身边所做的一切(`identity`, (中文(简体) ), `established`) (中文(简体) ). 过 `name` 并行 `provides` 重新命名集成本身,当重映射存在时,就值得将其中两个分开.

这也是利用两个有助于同样关键因素的一体化的唯一途径. `initialize` 强烈地拒绝碰撞, 下游的任何东西都不能拒绝, 所以重命名一边:

```ts
integrations: [
  postgres(),
  remap(redis(), {
    name: "redis (as cache)",
    provides: { cache: ({ provided }) => provided.db },
  }),
];
```

结果是一个普通的集成: 它的重写键经过同样的碰撞, `__proto__` 财务报告和审定财务报表 `row` 支票和其他的,一个包裹 `frame` 仍然运行和确定它所建立的东西,以及没有 `frame` 之后仍然没有。 每个包裹的供应商每个测试一次 重新绘图可以重新命名一个集成的贡献,它不会改变它的工作频率. `remap` 编曲, 并重新绘制名称, 在仍然运行被包时没有键贡献 `frame`。 。 。 .

## 遵约

子路径导出记录了检查您跑者运行的套件 。 因此兼容性是您自己的环境可以测试的东西, 而不是一个运行成功者列表 :

```ts
import { conformance } from "@ghostry/harness/conformance";
import * as framework from "bun:test";

conformance(framework);
```

放在自己的测试文件中 它自己建起来的 `initialize` 用它自己的探测器集成, 将一切记录在一个下 `describe`,并且只等待微任务,所以安装了假定时器是安全的. 它检查一个巢 `describe` 到达身体 作为其完整的逻辑路径, 跑者完成收集 `describe` 在测试之前,钩子和整合的撕裂 运行顺序在身体周围, 不测试开始 在前一个解决之前 `beforeAll`编号 :`afterAll` 当跑者宣布时 给他们的套房打上括号.

跑者是否等待承诺 尸体返回被检查 尸体拒绝,注册通过 `it.failing` (bun, 笑话)或 `it.fails` (vitest, rstest)——只有在被拒作为失败到达跑道时跑道才会保持绿色. 摩诃迦叶和 `node:test` 没有,有包 记录一个跳过测试说。 它不检查一个 `async` 说明哪些跑者合法地不同意,或报告同步故障,但不能从跑道内观察.

## 许可证

[麻省理工学院](https://npmcn.com/package/%40ghostry/harness/LICENSE) 帕特里克·雷布希(英语:

## 常见问题

### @ghostry/harness 是什么？

一个针对Jest兼容测试框架的集成的上下文感包\.

### 如何安装 @ghostry/harness？

在项目目录运行 npm install @ghostry/harness，或使用 pnpm add / yarn add / bun add。

### @ghostry/harness 支持 TypeScript 吗？

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

### @ghostry/harness 支持 ESM 还是 CommonJS？

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

### @ghostry/harness 需要什么版本的 Node\.js？

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

### @ghostry/harness 可以商用吗？

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

### @ghostry/harness 的下载量有多少？

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

### @ghostry/harness 还在维护吗？

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

