# @gate-forge/witness 中文文档

规范地址：https://npmcn.com/package/%40gate-forge/witness/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T03:57:39.840Z
中文译文更新时间：2026-11-15T23:55:38.107Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gate-forge/witness
原文对照：https://npmcn.com/package/%40gate-forge/witness/?lang=original
项目主页：https://github.com/umiddey/gateforge#readme
源码仓库：https://github.com/umiddey/gateforge

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

- 包体积（解压后）：1.3 MB，151 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：4 个
- peer 依赖：bullmq ^6\.3\.10，ioredis ^6\.0\.0，playwright \>=1\.40\.0
- 首次发布：2026-10-03T06:25:15.791Z
- 最新版本发布：2026-11-10T03:57:39.516Z
- 近 30 天下载量：2598（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

Gateforge跑道中性证人:环回HTTP证人代理,每测试会话标记合同,以及跑道适应器合同,每测试跑道员(Playwright, Cypress, pytest+httpx, Jest/Vitest+supertest) 设备,以产生同样可信赖的e

## 安装

```sh
npm install @gate-forge/witness
```

也可以使用：`pnpm add @gate-forge/witness`、`yarn add @gate-forge/witness`、`bun add @gate-forge/witness`

## README

# @ gate- forge/ 证人

跑道中立的Gateforge目击证人:逆向反转的HTTP目击证人 试运行的流量 机器可核实的证据, 加合同每 测试跑步器供养它.

## 此软件包为何存在

Gateforge曾经只为Playwright用户工作. 原因从来不是 证据模型——这是代码的所在地:证人服务和 每个测试会话客户端都生活在一个以跑者命名的包中.

证人是HTTP代理加DB/等号读取器,代理并不在意 谁送交通。 所有跑者特有的 崩溃为四个工作, 声明 `RunnerAdapter` 合同:

| 任务 | 方法 | 跑者必须提供什么 |
| --- | --- | --- |
| 列表 | `enumerate()` | 测试,运行前。 预期的一套是先固定的. |
| 标记 | `childEnv()` | 每测试身份:会话代理来源或已签名会话头. |
| 运行 | `execute()` | 套房,在受信任的监督下,有一段有限的超时. |
| 读取 | `parseResults()` | 以结构化格式(nature JSON或JUnit XML)得出的结果——永远不使用终端颜色. |

## 套装套装

`runRunnerAdapterContract(adapter, host)` 是每个适配器必须的套房 通过。 该套房拥有断言;a `RunnerContractHost` 仅拥有 跑道力学(要实现的文件,如何培养跑道力学,在哪里) 报告土地。 分级总是贯穿 `superviseExecution` 从 `@gate-forge/core` - 同样的中立完整规则 一个Playwright运行是 等级通过.

它检查适配器:

-   列出预期的一套,并报告一个项目 **没有** 测试 `unavailable` 而不是作为一个空的成功运行;
-   标记每个具有自身值的会话, 并永不泄露父侧线条 (核查钥匙、义务、拼接道或CI道);
-   将无法读取的报告视为不完整,而不是发明成果;
-   属性 **无** 测试,其跑道身份从未到达;
-   管理套房本身( e)`execute`报告;
-   和块,有打出的原因,在故障、跳过、再试、计划外或 零测试运行.

## 信托规则(不变)

-   跑者自己的"通过"从来不是权威. `parseResults` 制作记者 INPUT;判决来自监督以及证人签发的开庭证 追踪.
-   没有有效会话标记的请求从不归属于测试.
-   仅添加: 已存在的 JSON 密钥、 导致代码、 退出代码、 配置密钥和 收据是被冻结的 每一个新的设定都会默认今天的行为.

## 适配器

跑道中性部件就住在这里: `RunnerAdapter` 合同 会话标记类型和相容套件。 每个适配器 其驱动的跑步机械(共享) 所监管运行已经使用的收集/报告/集合代码),即 为什么Playwright的适配器 一直生活在 `@gate-forge/pack-playwright`数字 :

| 运行者 | 何处 | 标记频道 |
| --- | --- | --- |
| 剧作家 | `@gate-forge/pack-playwright` (单位:千美元)`discovery/playwright-runner-adapter.ts`(中文(简体) ) | 会话代理 |
| 齐压 | `@gate-forge/pack-playwright` (单位:千美元)`discovery/cypress-runner-adapter.ts`(中文(简体) ) | 会话代理 |
| pytest + httpx 测试 | `@gate-forge/pack-playwright` (单位:千美元)`discovery/pytest-runner-adapter.ts` + 键 `python/gateforge_pytest_plugin.py`(中文(简体) ) | 会话代理 |
| Jest/Vites + 超级测试 | `@gate-forge/pack-playwright` (单位:千美元)`discovery/vitest-runner-adapter.ts`(中文(简体) ) | 会话代理 |

进程内测试客户端( 超级测试, FastAPI) `TestClient`) 调用应用程序 而不通过代理。 适配器使用一个键入模式 而不是悄悄地传递,请求绝不是传达给证人, 所以它不可能是证据.

## 每会场适配器身份

租户单通行(其UNIQUE限制包括 租户范围栏)不能从固定证人-环境读取 座位:该座位的房客已经拥有了排行. 创建 租户首先通过下列方式登记租户的登记: 经届会认证的 `POST /sessions/identity` (单位:千美元)`seat` 加减 证书 `values`,由同一证人 env var 键入 适配器 座席申报). Kit 适配器按 `ctx.sessionId` 首页和 过程 - 全球环境座位.

它的整个权威是 _引擎读作一个会话_。 。 。 . 引擎仍然执行每个读数; 错误的租户使行没有找到 (应用程序回答403/404,实体等级缺失) 由会话 id 键入, 无法为外籍人注册或结束 ;和 证书从未达到记录,运行状态,日志或报告. 这个 完整参数在 `packages/cli/guides/TEST-ENVIRONMENT.md`没有 注册读取的字节与今天的行为相同.

## 每期原产地诊断

只有固定路线 `GATEFORGE_APP_BASE_URL` 到会话代理服务器。 A 类 装入一些其它来源的套件——它自己的基址,常常是从未装入过的 达到了测试进程,因为它缺失了 `envAllowlist` - 路线 没什么,证人什么也没观察到,每个 `observed-e2e` 索赔 测试通过时, 最终会丢失。 固定报告 通过会话认证的无序同主机/落回源 `POST /sessions/page-origins`,零流量注释引用了它们.

它的权威是: _注中一句_它保存在证人的记忆中 开庭, 放弃, 薄荷 没有记录: 没有判决, 没有报告,没有 运行状态可以依赖它. 一个只报道自己页面的谎言的套房 使其自己的失败信息错误.

## 操作员的固定/代理提供者

声明的行为案件名称 a `fixture` 食谱和 `actor`证人 在推动案件之前,通过由下列程序命名的模块实现这两个目标: `GATEFORGE_FIXTURE_PROVIDER` (载: `witness/bin.ts` 启动时; a 证人在没有律师在场的情况下开始的,没有案件可准备.

该模块的默认导出是 `{ prepare(input), release(leaseId), resolveCredential(credentialRef) }`。 。 。 . `prepare` 返回时 `{ leaseId, namespace, subjects, actors }` 具有SERVER-ISSED主题身份; `release` 放弃什么 租赁; `resolveCredential` 转租 `credentialRef` 输入 要求材料和运行 在这个过程中, 所以一个秘密永远不会离开它.

提供商是引擎侧码 也是自己提供的唯一呼叫者 HTTP电话 套房从不进口,没有东西能退货 证据,它只提供对象 一个案件驱动器,所以案件的证据仍然 来自于证人的请求 和它自己读的状态。 A 类 因此,储存库应将供应商排除在产品扫描范围之外 (单位:千美元)`.gateforge.yml` `project.paths.exclude`匹配 `classification-policy.yml` `scanRoots`),或发动机本身的给养 报告流量为未解决的申请呼叫站点。 见 `example/behavior/fixtures/fixture-provider.mjs` 工作供应商.

## 常见问题

### @gate-forge/witness 是什么？

Gateforge跑道中性证人:环回HTTP证人代理,每测试会话标记合同,以及跑道适应器合同,每测试跑道员\(Playwright, Cypress, pytest\+httpx, Jest/Vitest\+supertest\) 设备,以产生同样可信赖的e

### 如何安装 @gate-forge/witness？

在项目目录运行 npm install @gate-forge/witness，或使用 pnpm add / yarn add / bun add。

### @gate-forge/witness 支持 TypeScript 吗？

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

### @gate-forge/witness 支持 ESM 还是 CommonJS？

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

### @gate-forge/witness 需要什么版本的 Node\.js？

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

### @gate-forge/witness 可以商用吗？

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

### @gate-forge/witness 的下载量有多少？

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

### @gate-forge/witness 还在维护吗？

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

