# @xyo-network/event-kit-vitest-config 中文文档

规范地址：https://npmcn.com/package/%40xyo-network/event-kit-vitest-config/

版本：2\.3\.4
npm 元数据更新时间：2026-11-02T22:27:27.253Z
中文译文更新时间：2026-11-02T23:12:54.570Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40xyo-network/event-kit-vitest-config
原文对照：https://npmcn.com/package/%40xyo-network/event-kit-vitest-config/?lang=original
源码仓库：https://github.com/XYOracleNetwork/event-kit

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

- 包体积（解压后）：237 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26
- 运行依赖：9 个
- peer 依赖：ajv ^8\.20，zod ^4\.6，vite ^8\.3，ethers ^6\.17，vitest ^5\.0，async-mutex ^0\.5，@ariestools/sdk ^9\.0，@xyo-network/sdk ^8\.1，@ariestools/actor ^2\.0，@opentelemetry/api ^1\.10，@xyo-network/xl1-sdk ^5\.8，@ariestools/vitest-config ^10\.2，@xyo-network/sdk-protocol ^8\.0，@xyo-network/xl1-protocol ^5\.8，@xyo-network/xl1-statement-graph-sdk ^0\.7，@xyo-network/xl1-statement-graph-engine ^0\.7，@xyo-network/xl1-statement-graph-schemas ^0\.7
- 首次发布：2026-08-27T16:26:12.858Z
- 最新版本发布：2026-11-02T22:27:27.076Z
- 已发布版本数：20（近 12 个月 20 个）

## 中文简介

使用真正的发布者和HTTPS接收器测试预设和拥有的本地XL1事件堆栈

## 安装

```sh
npm install @xyo-network/event-kit-vitest-config
```

也可以使用：`pnpm add @xyo-network/event-kit-vitest-config`、`yarn add @xyo-network/event-kit-vitest-config`、`bun add @xyo-network/event-kit-vitest-config`

## README

# @xyo-network / event-kit-vitest-config

一个可选择的Vitest预设 **真实的，测试拥有的本地事件堆栈**一辆XL1 dev-chain子进程，散列寻址REST数据库，常驻事件发布者， 和经过认证的HTTPS接收器。需要Node.js 26或更新版本；这个 存储库pin为Node 26.9.0。

```sh
pnpm add -D @xyo-network/event-kit-vitest-config vitest
```

```ts
// vitest.config.ts
import { defineEventKitVitestConfig } from '@xyo-network/event-kit-vitest-config'

export default defineEventKitVitestConfig({
  installers: { localEventStack: true },
})
```

加入集成规范 `src/**/spec/local-event-stack/**/*.spec.ts` (或 `packages/*/src/**/spec/local-event-stack/**/*.spec.ts` 在工作空间中)：

```ts
import { getLocalEventStack } from '@xyo-network/event-kit-vitest-config'
import { expect, it } from 'vitest'

it('receives finalized heads', async () => {
  const stack = getLocalEventStack()
  const subscription = await stack.subscribe({
    deploymentId: 'my-indexer',
    queueId: 'heads', // optional
    fromPosition: 0, // explicit historical floor; default is the source head at creation
    maxPositionsPerWake: 16,
  })
  const active = await subscription.waitForActive()
  const wake = await subscription.waitForWake()
  expect(wake.publisher).toBe(stack.publisher)
  expect(active.activeFromBlock).toBeGreaterThan(0)
  expect(wake.fromPosition).toBe(0)
  expect(wake.event.source).toEqual({ kind: 'xl1-finalized', chainId: stack.chainId })
  await subscription.revoke()
})
```

```sh
pnpm vitest run --project local-event-stack
```

平原 `vitest run` 不引导堆栈。它的规格是不普通的 节点/浏览器项目，即使在禁用安装程序时也是如此。集 `localEventStack: { optInOnly: false }` 将其包含在普通运行中。 `defineEventKitVitestProjects` 和 `defineEventKitInstallerProjects` 支持 与其他预设合成。仅组合安装程序项目时，也 应用 `LOCAL_EVENT_STACK_EXCLUDE` 到您的基本项目。

## 运行什么

每个规范文件都有一个新的链ID、临时环回端口和临时环回端口 目录中。该文件中的测试共享堆栈；不要停止，直到 文件的最终测试。设置发布发布者的服务和专用HPKE 加密密钥。 `subscribe()` 创建并资助独立开发者身份； 启动TLS接收器，并通过发布加密的订阅和授权 高屋建瓴的、有主题的主张。

后台发布者通过语句图发现最终的元组 重放，解密端点，执行其HTTPS所有权挑战，发布 接受，并在授权块时成为合格的 **验收块+ 1**. 每个尾流使用规范的未版本的源感知信封，并从 独立申报的 `fromPosition`成批地 `maxPositionsPerWake`. 每个订阅者都有一个持久的游标和发件箱。接收机独立重放 并执行真正的JWT、授权、生命周期和原子收件箱检查 持久的排队。没有HTTP处理程序运行reducer。

`waitForWake()` 声明并确认一个排队唤醒。明确租赁或 减速机试验使用 `subscription.queue.claim()` 和它的 `ack()` / `release()` 方法。 `dropNextDeliveryResponses()` 模拟丢失的响应 _后_ 耐用 入学;重试在新的JWT下保持相同的唤醒ID/散列。 `stats()` 公开 仅测试交付证据。将其jwt和夹具帐户/密钥状态视为 敏感测试数据；不要在实际网络中记录或重用它们。

## 生命周期和低级访问

-   安装/拆除包含启动失败，发布者停止，网关，接收器， 数据库、子进程和临时目录。 `stop()` 是等幂的。
-   `getLocalEventStack()` 在测试/钩子中可用，而不是在模块范围内。 或者进口 `@xyo-network/event-kit-vitest-config/globals` 作为一种类型 键入安装程序拥有的 `eventStack` 全球。
-   `startLocalEventStack({ pollIntervalMs?, readyTimeoutMs? })` 支持手动 所有权。总是 `await stack.stop()` 在一个 `finally` 块。
-   `publisherClient`， `createSubscriber().client`， `viewer`， `rpcUrl`， `dataLakeUrl` 和 `advertisement` 为自定义测试公开真正的公共api。
-   你自己的接收器，请拨 `registerEndpoint(exactHttpsUrl, certificatePem)` **之前** 通过资助的 `createSubscriber()` 客户端。返回 Value注销它。你拥有自定义服务器的清理和挑战， 允许和队列实现。

## 边界

这是一个本地集成工具，而不是基于模拟的单元测试夹具 生产 `event-kit publisher run` 命令。就像dApp Kit的fixture一样 启动已发布的XL1 CLI；它还禁用共享运行状况/指标 侦听器使并发堆栈不会发生冲突。否 `apiLocal` 安装程序 必需的。没有连锁证书， 需要公共数据库、序列或主网访问。所有 `XL1_*` 环境 覆盖和 `NODE_TLS_REJECT_UNAUTHORIZED=0` 必须取消设置以防止环境 钱包/网络配置泄漏到子进程。

只有准确的，显式注册的HTTPS url上的文字 `127.0.0.1` 可调用的。 TLS验证仍然启用每个端点证书信任。DNS名称, 重定向和隐式局域网访问被拒绝。这个仅限测试的津贴可以 不更改生产端点规则。每个挑战一次允许一次出站 尝试。失败或有歧义的HTTP尝试会在稍后的发布者通行证上重试 迎接新的挑战；收到的证明将被保留以备再次接受。

该链使用简化的开发共识和内存链状态；出版商, 数据库和收件箱文件只存在到拆除。这不符合 生产监控，重启恢复，SQLite，多虚拟机，序列或 Mainnet。托管生产资格仍然是独立的。

## 存储库api本地限定

这个存储库保留了选择 `api-local` 项目名称和现有协议 规格，拥有一个存储库 `setupFiles` 在root Vitest配置中重写。 每个文件启动事件堆栈使用的相同的公共XL1 CLI开发链， 然后提供实际观察到的 `rpcUrl` 和 `chainId` 全局变量。配置 解析相对于其自身URL的设置源，因此运行包范围的测试 使用相同的设置。测试钱包使用公共开发助记符；没有内部定位器 提供全局或提供者id修改。

```sh
pnpm test:api-local
pnpm test:api-local-statements
pnpm test:live
```

发布的 `xl1-vitest-config`/`chain-test` 5.5.0进程内生产者导入 `SimpleBlockRunner` 没有XL1 SDK 5.8.0所需的稳定提供商ID。 支持的设置覆盖将链运行时更改为公共CLI；它 不修补依赖关系，降级应用程序SDK或恢复构造函数 名称提供程序标识。这扇门的结果是气候变化中心支持的本地链证据， 不同于历史进程内 `apiLocal` 证据和托管资格。

存储库的 `pnpm test:packed-event-stack` Gate从本地安装 具有严格对等检查的PNPM缓存，对一个单独的消费者进行类型检查，然后运行 两个规范文件通过打包的设置项。填充依赖项缓存 运行前；此门不是注册表发布检查。

许可:lgpl - 3.0。

## 常见问题

### @xyo-network/event-kit-vitest-config 是什么？

使用真正的发布者和HTTPS接收器测试预设和拥有的本地XL1事件堆栈

### 如何安装 @xyo-network/event-kit-vitest-config？

在项目目录运行 npm install @xyo-network/event-kit-vitest-config，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ajv（^8\.20）、zod（^4\.6）、vite（^8\.3）、ethers（^6\.17）、vitest（^5\.0）、async-mutex（^0\.5）、@ariestools/sdk（^9\.0）、@xyo-network/sdk（^8\.1）、@ariestools/actor（^2\.0）、@opentelemetry/api（^1\.10）、@xyo-network/xl1-sdk（^5\.8）、@ariestools/vitest-config（^10\.2）、@xyo-network/sdk-protocol（^8\.0）、@xyo-network/xl1-protocol（^5\.8）、@xyo-network/xl1-statement-graph-sdk（^0\.7）、@xyo-network/xl1-statement-graph-engine（^0\.7）、@xyo-network/xl1-statement-graph-schemas（^0\.7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @xyo-network/event-kit-vitest-config 支持 TypeScript 吗？

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

### @xyo-network/event-kit-vitest-config 支持 ESM 还是 CommonJS？

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

### @xyo-network/event-kit-vitest-config 需要什么版本的 Node\.js？

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

### @xyo-network/event-kit-vitest-config 可以商用吗？

@xyo-network/event-kit-vitest-config 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @xyo-network/event-kit-vitest-config 还在维护吗？

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