# @async/witness 中文文档

规范地址：https://npmcn.com/package/%40async/witness/

版本：0\.9\.0
npm 元数据更新时间：2026-08-22T02:48:39.208Z
中文译文更新时间：2026-11-07T01:34:20.571Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：249 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：vite ^8\.0\.0
- 首次发布：2026-06-17T04:58:31.706Z
- 最新版本发布：2026-08-22T02:48:38.856Z
- 近 30 天下载量：18049（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

**看看你的维特输油管到底做了什么 收据.**

## 安装

```sh
npm install @async/witness
```

也可以使用：`pnpm add @async/witness`、`yarn add @async/witness`、`bun add @async/witness`

## README

# 同步证人

**看看你的维特输油管到底做了什么 收据.**

重新来过 重新来过, `console.log`\- 维特一直知道发生了什么 只是从来没有告诉你。 Async Witness 运行您真正的管道并写下 **收据** 每次运行时: 证明你,CI, 或AI特工可以采取行动.

> ⚠️ **提前释放** - 那个 [规格](https://npmcn.com/package/%40async/witness/specs/README.md) 是产品真实的. 由杰克设计,执行 **神话**,经 **代码**。 。 。 .

## 30秒内一个盒子

A 类 **选项框** 是一个小文件 运行在您真正的维特管道 并声称什么 在管道本身的词汇中:

```ts
import { box } from '@async/witness';

export default box('message updates without reload', async ({ browser, project, expect }) => {
    // Visit a real route — this auto-starts your real Vite dev server.
    const page = await browser.visit('/demo');

    // Edit a real source file, like a developer saving in their editor.
    const change = await project.edit('src/message.ts', {
        replace: ['before', 'after'],
    });

    // Declare what Vite should have done about it.
    await expect.edit(change, {
        client: { hmr: 'accepted' }, // hot update applied, no full reload
    });

    // Confirm the browser actually shows the new text.
    await expect.page.text(page, '#message', 'after');
});
```

```sh
witness hmr
```

Async Witness 运行此框,恢复已编辑的文件,并写收据给 `.witness/receipts/` —— 说 或失败,人和机器可读。 如果盒子失败,收据会解释 _为什么_ 内 维特自己的术语:维特发送的载荷,服务器是否重启,控制台所说的话.

![you edit src/message.ts → your real Vite pipeline (dev server, HMR, SSR, build) → receipt.json: hmr accepted, 0 reloads](https://npmcn.com/package/%40async/witness/assets/box-flow.svg)

## 盒子能证明什么

-   一条路由可以装入每个资产 和一个干净的控制台
-   用户制作的UI状态——点击、打入、盘旋、按键、拖入或滚动入的状态——在编辑后存活下来,每一次互动都被记录为收件证据
-   编辑热度更新、重载或默默无所作为——每个环境
-   仅由服务器编辑的浏览器
-   用新插件激活的配置编辑重新启动了服务器
-   SSR 制取和水合物时没有控制台出错
-   这个 **已建成** app行为类似 dev( 构建 + 预览等同)
-   人工制品是正确的——显示的条目,没有陈旧的占位符,没有 `node:fs` 在工人捆绑中
-   业绩预算内保留一个工作流程

## 每张收据都有证人

请求只回答你想问的问题 有趣的失败在于什么 你没有问——控制台错误没有打破你的选择器,请求 当页面仍然打开时死亡, 重新装入的满载在正确的文本上 无论如何。 Async Witness对待一个盒子就像一个案件: 收据是案件档案 观察了里面的跑道.

三名目击者从不同的角度观看了每个浏览器盒. 这个 **管道** 证人是Vite的服务器侧面——它知道实际发送的热载荷是什么,是否 服务器重新启动,每个环境对您的编辑所做的。 这个 **客户端** 证人是页面 ——它的操纵台,它未发现的错误,你框架发射的自定义事件. 这个 **驱动程序** 证人手表来自CDP的外页 `net::ERR_*` 原因,导航页面无法隐藏,截图. 他们都看不见 别人所见的,这是重点,他们互相证实或抵触 独立.

每个证人每个盒子都有判决 当一个盒子通过,但证人持有证据 与跑道相对的, 路由标记 **争议**数字 :

```
pass noisy page records console and network evidence  [pipeline+ client! driver!]  contested
     client reported: 1 console error   driver reported: 1 failed request
```

每一个断言都在这里通过。 页面还记录出一个错误,请求失效——事实否 被问及,保存下来而不是被吞噬。 这就是"测试通过"和 "应用程序是好的",每跑一次都能看到.

直接检查存储收据上的任何盒子:

```sh
witness evidence 'noisy page'
```

```
crimes reported (2):
  ! console error   Failed to load resource: net::ERR_ABORTED   — reported by client
  ! request failed  GET http://127.0.0.1:5173/missing.js        — reported by driver
```

证人身份和判决是收据JSON中的简单数据——稳定、可移动、安全 CI和特工要消费。 颜色只是你的终端画的.

## 为什么Vitest / Playwright / 故事本?

他们很擅长他们拥有的东西,但他们看到了 **页 次**,而不是 **管道** 产生 这个 这种差距是"所有测试通过"和"应用被打破"同时发生的. 同步证人 拥有管道:从编辑到Vite环境事件的链条到您看到的,带有 收条保存整个故事.

下方也没有自动化框架 Async Witness 将浏览器本身驱动到 Chrome DevTools Protocols — 几千行WebSocket和JSON完全拥有, 零依赖性。 一个集合浏览器为整个运行服务,每个盒子都各自隔离 浏览器上下文,同样的架构剧作家使用内部,这就是目击结束的方式 每一次测试的速度都比每个平台CI量的剧作家核心要快.

## 带上自己的浏览器

Async Witness 已经在您的机器上驱动了 Chromium- family 浏览器 协议——不依赖剧作家,安装时不下载. 发现顺序 :

1.  `WITNESS_BROWSER_PATH` ——明确超标. 如果设定了,但没有指向可执行文件, 发现失败时出现错误,而不是默默地掉入到另一个浏览器中.
2.  系统安装了Chrome,Edge,或Chromium,在通常的每个OS位置.
3.  Playwright 的浏览器缓存作为礼貌回放(`~/Library/Caches/ms-playwright` 打开 马科斯, `$XDG_CACHE_HOME` 或者说 `~/.cache/ms-playwright` 在Linux上, `%LOCALAPPDATA%\ms-playwright` 视窗上)——全 `chromium-<revision>` 仅下载, 最新的第一,无头壳被跳过.

macOS,Linux,和Windows都是在CI中实现的. 找不到任何证据,证人就会失败 检查的准确路径 .

## 文档

-   **[光谱](https://npmcn.com/package/%40async/witness/specs/README.md)** ——产品取向与真相来源

## 状态

以切为地. 框写、编辑/建设/审查运行、浏览器证据、证人判决 与 `witness evidence` 钻入,CLI,和JSON的收据今天工作。 这个 状态采集UI,生成类型,接收重播即将到来.

## 捐款

工作空间运行在 **小时** (图书馆本身是运行时间不可知的——它运行在Vite的任何地方) 运行 :

```sh
pnpm install        # install dependencies
pnpm run test       # run the test suite (drives real Vite pipelines)
pnpm run check      # format check + lint + typecheck
```

见 [捐款额](https://npmcn.com/package/%40async/witness/CONTRIBUTING.md) 为完整的设置。 开始 [`specs/`](https://npmcn.com/package/%40async/witness/specs/README.md) 意图,以及 `.ruler/` 工作协议.

## 常见问题

### @async/witness 是什么？

看看你的维特输油管到底做了什么 收据\.

### 如何安装 @async/witness？

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

### @async/witness 支持 TypeScript 吗？

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

### @async/witness 支持 ESM 还是 CommonJS？

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

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

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

### @async/witness 可以商用吗？

@async/witness 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @async/witness 的下载量有多少？

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

### @async/witness 还在维护吗？

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