@gate-forge/witness

中文文档
0.19.2发布于 2026/11/10Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 2598

Gateforge runner-neutral witness: the loopback HTTP witness proxy, the per-test session tagging contract, and the runner-adapter contract every test runner (Playwright, Cypress, pytest+httpx, Jest/Vitest+supertest) implements to produce the same trusted e

原始使用文档
文档目录7 节
  1. Why this package exists
  2. The conformance suite
  3. Trust rules (unchanged)
  4. Adapters
  5. Per-session adapter identity
  6. Per-session origin diagnostics
  7. The operator's fixture/actor provider

@gate-forge/witness

The runner-neutral Gateforge witness: the loopback HTTP witness that turns a test run's traffic into machine-verifiable evidence, plus the contract every test runner implements to feed it.

Why this package exists

Gateforge used to only work for Playwright users. The reason was never the evidence model — it was where the code sat: the witness service and the per-test session client lived inside a package named after one runner.

The witness is an HTTP proxy plus a DB/queue reader, and a proxy does not care who sends the traffic. Everything runner-specific collapses into four jobs, declared by the RunnerAdapter contract:

JobMethodWhat a runner must provide
Listenumerate()The tests, BEFORE the run. The expected set is fixed first.
TagchildEnv()The per-test identity: a session proxy origin or a signed session header.
Runexecute()The suite, under trusted supervision with a finite timeout.
ReadparseResults()The outcome in a STRUCTURED format (native JSON or JUnit XML) — never terminal colors.

The conformance suite

runRunnerAdapterContract(adapter, host) is the one suite every adapter must pass. The suite owns the assertions; a RunnerContractHost owns only the runner mechanics (which files to materialize, how to spawn the runner, where its report lands). Grading always runs through superviseExecution from @gate-forge/core — the same neutral completeness rules a Playwright run is graded by.

It checks that the adapter:

  • enumerates the expected set, and reports a project with no tests as unavailable rather than as an empty successful run;
  • tags every session with its own value, and never leaks parent-side wiring (the verifier key, the obligations, spool or CI paths) to the runner child;
  • reads an unreadable report as incomplete instead of inventing outcomes;
  • attributes nothing to a test whose runner identity never arrived;
  • runs a suite itself (execute), not just reports;
  • and blocks, with a typed cause, on a failing, skipping, retried, unplanned or zero-test run.

Trust rules (unchanged)

  • A runner's own "passed" is never authority. parseResults produces reporter INPUT; the verdict comes from supervision plus the witness-issued session trace.
  • A request without a valid session tag is never attributed to a test.
  • Additions only: existing JSON keys, cause codes, exit codes, config keys and receipts are frozen, and every new setting defaults to today's behavior.

Adapters

The runner-neutral parts live here: the RunnerAdapter contract, the session tagging types, and the conformance suite. Each adapter implementation lives beside the runner machinery it drives (the shared collection/report/spool code the supervised run already uses), which is why the Playwright adapter has always lived in @gate-forge/pack-playwright:

RunnerWhereTag channel
Playwright@gate-forge/pack-playwright (discovery/playwright-runner-adapter.ts)session proxy
Cypress@gate-forge/pack-playwright (discovery/cypress-runner-adapter.ts)session proxy
pytest + httpx@gate-forge/pack-playwright (discovery/pytest-runner-adapter.ts + python/gateforge_pytest_plugin.py)session proxy
Jest/Vitest + supertest@gate-forge/pack-playwright (discovery/vitest-runner-adapter.ts)session proxy

An in-process test client (supertest, FastAPI TestClient) calls the app without going through the proxy. The adapters REFUSE that mode with a typed message instead of passing it silently — the request never reaches the witness, so it can never be evidence.

Per-session adapter identity

A per-tenant singleton row (a table whose UNIQUE constraint includes the tenant scope column) cannot be read from the fixed witness-environment seat: that seat's tenant already has the row. A test that creates the tenant first registers that tenant's login for ITS OWN session through the session-authenticated POST /sessions/identity (seat plus the credential values, keyed by the same witness env var names the adapter seat declares). Kit adapters resolve the seat by ctx.sessionId first and the process-global environment seat otherwise.

The whole of its authority is who the engine reads as, for one session. The engine still performs every read; a wrong tenant makes the row unfound (the app answers 403/404 and the entity grades absent); the identity is keyed by that session id, cannot be registered for a foreign or ended session, and is dropped when the session closes or is released; and the credential never reaches a record, the run state, a log or a report. The full argument is in packages/cli/guides/TEST-ENVIRONMENT.md. Without a registration the read is byte-identical to today's behavior.

Per-session origin diagnostics

The fixture routes only GATEFORGE_APP_BASE_URL onto the session proxy. A suite that loads some other origin — its own base URL, often one that never reached the test process because it was missing from envAllowlist — routes nothing, the witness observes nothing, and every observed-e2e claim finalizes as missing while the tests pass. The fixture reports those unrouted same-host/loopback origins through the session-authenticated POST /sessions/page-origins, and the zero-traffic note quotes them.

Its authority is a sentence in a note. It is kept in witness memory for the session, dropped with it, and mints no record: no verdict, no report and no run state can depend on it. A suite that reports a lie about its own page only makes its own failure message wrong.

The operator's fixture/actor provider

A declared behavior case names a fixture recipe and an actor. The witness materializes both before it drives the case, through the module named by GATEFORGE_FIXTURE_PROVIDER (loaded by witness/bin.ts at startup; a witness started without one simply has no cases to prepare).

The module's default export is { prepare(input), release(leaseId), resolveCredential(credentialRef) }. prepare returns { leaseId, namespace, subjects, actors } with SERVER-ISSUED subject identities; release drops what that lease provisioned; resolveCredential turns a lease credentialRef into request material and runs in this process, so a secret never leaves it.

The provider is engine-side code and the only caller of its own provisioning HTTP calls. The suite never imports it, and nothing it returns can mint evidence — it only supplies the subjects a case drives, so a case's proof still comes from the request the witness issued and the state it read itself. A repository should therefore exclude the provider from its product scan scope (.gateforge.yml project.paths.exclude, matching classification-policy.yml scanRoots), or the engine's own provisioning traffic is reported as unresolved application call sites. See example/behavior/fixtures/fixture-provider.mjs for a working provider.

版本与发布记录

@gate-forge/witness 共发布 35 个版本,首次发布于 2026/10/03;过去 12 个月发布了 35 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.2latest2026/11/105 天前
0.19.12026/11/106 天前
0.19.02026/10/2917 天前
0.18.32026/10/2522 天前
0.18.22026/10/2125 天前
0.18.12026/10/2125 天前

关于 @gate-forge/witness 的常见问题

@gate-forge/witness 是什么?

Gateforge runner-neutral witness: the loopback HTTP witness proxy, the per-test session tagging contract, and the runner-adapter contract every test runner (Playwright, Cypress, pytest+httpx, Jest/Vitest+supertest) implements to produce the same trusted 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 和提交记录判断。