# @fluidframework/test-runtime-utils 中文文档

规范地址：https://npmcn.com/package/%40fluidframework/test-runtime-utils/

版本：3\.12\.0
npm 元数据更新时间：2026-11-10T22:35:50.702Z
中文译文更新时间：2026-11-15T01:59:57.889Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fluidframework/test-runtime-utils
原文对照：https://npmcn.com/package/%40fluidframework/test-runtime-utils/?lang=original
项目主页：https://fluidframework.com/
源码仓库：https://github.com/microsoft/FluidFramework

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

- 包体积（解压后）：1.6 MB，163 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：15 个
- 首次发布：2020-09-01T04:29:52.835Z
- 最新版本发布：2026-11-10T22:35:50.333Z
- 近 30 天下载量：33453（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：695（近 12 个月 48 个）

## 中文简介

流体运行时间测试设施

## 安装

```sh
npm install @fluidframework/test-runtime-utils
```

也可以使用：`pnpm add @fluidframework/test-runtime-utils`、`yarn add @fluidframework/test-runtime-utils`、`bun add @fluidframework/test-runtime-utils`

## README

# @fluidframework/test-runtime-utils (英语)

流体框架运行时间测试工具。 包括模拟实施各种运行时界面,以及 用于验证特定日志序列的模拟日志.

## 使用 Fluid 框架库

对于依赖流体框架库的公共API,我们建议 `^` (caret)版本范围. 例如,使用 `^1.3.4`。 。 。 .

依赖不稳定的API,例如: `beta` API,我们推荐一个更具限制性的版本范围. 例如,使用一个 `~` 版本范围.

## 安装

运行此命令以安装软件包 :

```bash
npm i @fluidframework/test-runtime-utils
```

## 从此软件包导入

此软件包使用 [packet.json 导出](https://nodejs.org/api/packages.html#exports) 通过支持级别将API分离. 有关支助保障的信息改为: [API 支持级别](https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels)。 。 。 .

导入 `public` API 从 `@fluidframework/test-runtime-utils`。 。 。 .

导入 `legacy` API 从 `@fluidframework/test-runtime-utils/legacy`。 。 。 .

## API 文档

读取 **@fluidframework/test-runtime-utils (英语)** API 文档 [https://fluidframework.com/docs/apis/test-runtime-utils (中文(简体) )](https://fluidframework.com/docs/apis/test-runtime-utils)。 。 。 .

## DDS 写入单元测试

发展服务单元测试分为三大类。 以下各节解释如何使用本包中的模型为这些类别写出单位测试.

### 当地单位测试

这些测试不需要远程DDS,因此不需要DDS连接. 例如,测试DDS API工作正确,局部事件正确发射,摘要生成并正确加载等. 为了对这些情况进行单位测试,遵循这些步骤:

-   创建一个 `MockFluidDataStoreRuntime`。MockFluidDataStoreRuntime并没有真正做任何事情,只是用来创建DDS.
-   设定 `MockFluidDataStoreRuntime`是因为 `local` 属性改为 `true`。这将确保DDS产生的操作不被发送.
-   使用 `MockFluidDataStoreRuntime` 创建 DDS.

实例 [地图](https://npmcn.com/package/%40fluidframework/map/src/test/map.spec.ts), (中文(简体) ), [目录](https://npmcn.com/package/%40fluidframework/map/src/test/directory.spec.ts), (中文(简体) ), [矩阵](https://npmcn.com/package/%40fluidframework/matrix/test/matrix.spec.ts)。 。 。 .

### 远程单元测试

这些测试需要远程DDS,需要DDS连接. 例如,测试操作正确应用在远程客户端上,本地操作正确ock'd,远程事件正确发射等. 为了对这些情况进行单位测试,遵循这些步骤:

-   创建一个 `MockFluidDataStoreRuntime`。 。 。 .
-   使用 `MockFluidDataStoreRuntime` 创建 DDS.
-   我们需要能够处理来自多个DDS/客户端的信息. 创建一个 `MockContainerRuntimeFactory` 用于存储来自多个客户端的信息,并在需要时对其进行处理.
-   创建一个 `MockContainerRuntime` 拨打 `createContainerRuntime` 编辑 `MockContainerRuntimeFactory`。 。 。 . `MockContainerRuntime` 跟踪信件和本地的OpMetadata,直到它失效.
-   我们需要连接并附加到一个IDelta连接上,以便它可以提交和处理消息. 创建一个 `MockDeltaConnection` 拨打 `createDeltaConnection` 编辑 `MockContainerRuntime`。 。 。 .
-   使用 `MockDeltaConnection` 连接 DDS.

实例 [顺序汉德勒](https://npmcn.com/package/framework/undo-redo/src/test/sequenceHandler.spec.ts), (中文(简体) ), [快取图像](https://npmcn.com/package/%40fluidframework/sequence/src/test/snapshotVersion.spec.ts)。 。 。 .

### 重新连接单元测试

这些是远程单元测试,此外它们还需要断开和重新连接客户的能力. 例如,在重新连接时测试 - DDSs 重新发送操作正确,远程客户端接收操作正确,本地客户端锁定操作正确等. 为了对这些情况进行单位测试,遵循这些步骤:

-   按照上述设想2的所有步骤进行这些修改:
    -   创建 `MockContainerRuntimeFactoryForReconnection` 改为 `MockContainerRuntimeFactory`。 。 。 .
    -   创建 `MockContainerRuntimeForReconnection` 改为 `MockContainerRuntime`。 。 。 .
-   要断开客户端, 设置 `connected = false` 编辑 `MockContainerRuntimeForReconnection`。这将触发删除此客户端在 `MockContainerRuntimeFactoryForReconnection`。 。 。 .
-   要重新连接客户端, 设置 `connection = true` 编辑 `MockContainerRuntimeForReconnection`这将触发 `reSubmit` 调用 DDS 重新发送未装入/ 未发送操作 .

实例 [共享结构](https://npmcn.com/package/%40fluidframework/sequence/src/test/sharedString.spec.ts), (中文(简体) ), [协商一致命令](https://npmcn.com/package/%40fluidframework/consensus-ordered-collection/src/test/consensusOrderedCollection.spec.ts), (中文(简体) ), [协商一致登记](https://npmcn.com/package/%40fluidframework/consensus-register-collection/src/test/consensusRegisterCollection.spec.ts)。 。 。 .

## 不安全的托肯保护者

这个 `InsecureTokenProvider` 为本地生成的 JWT 令牌提供类,使用租户密钥签名,可以发送到流体服务. 这些令牌将用来认证和识别哪个用户正在从客户端发送操作.

它需要两个参数:

-   `tenantKey` - 用来签名 与符号使用 `tenantId` 我们试图连接到服务
-   `user` - 用来在目前编辑容器的观众中充斥当前用户的细节

这个 `AzureClient`从 `@fluidframework/azure-client` 软件包,以 `tokenProvider` 参数作为其构建器的一部分。 此参数可通过使用 `InsecureTokenProvider` 此处导出。 然而,建议它只用于开发或测试目的,因为它有可能暴露您的Azure Fluid Relay服务租户在客户端代码上的密钥.

### 利用当地微小实例促进发展

使用时 `AzureClient`,您可以配置它来对抗本地的微小实例。 请看客户的 [关于地方发展的文件](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/azure-client/README.md#backed-locally) 关于如何这样做的更多信息。 在这种情况下 `InsecureTokenProvider` 将取任何值 `tenantKey` 参数,因为我们正在工作 一个本地的微小实例 不需要任何认证。 因此,我们可以创建这样的例子:

```javascript
const tokenProvider = new InsecureTokenProvider("fooBar", { id: "123", name: "Test User" });
```

### 使用Azure Fluid中继服务促进发展

这个 `AzureClient` 也可以配置到所部署的 Azure Fluid 中继服务实例,如描述 [这里](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/azure-client/README.md#backed-by-a-live-azure-fluid-relay-instance)。现在,配置正在使用真实的 `tenantId` 编辑 `InsecureTokenProvider` 需要匹配 `tenantKey` 服务期间提供的服务.

```javascript
const tokenProvider = new InsecureTokenProvider("YOUR-TENANT-KEY-HERE", {
    id: "123",
    name: "Test User",
});
```

同样,这只应用于本地开发,因为客户端代码中包含租户密钥有可能导致恶意用户从客户端的捆绑中嗅出. 请考虑使用 [AzureFunction Token 创建器](https://github.com/microsoft/FluidFramework/blob/main/packages/framework/azure-client/src/AzureFunctionTokenProvider.ts) 或实现 `ITokenProvider` 接口作为生产情景的替代品.

## 客户最低要求

Fluid框架客户端库支持此文档中的平台. 这些要求有意具有限制性. 在一个主要的版本系列中,我们可以放松这些要求,但我们不能使其更严格. 对于长期支持(LTS)版本,我们可能需要支持这些平台几年.

其他配置可以奏效,但Fluid框架不支持. 如果一个不支持的配置停止工作, 我们不会将此归类为错误 . 要请求支持未列出的配置, 请存档 . 产品组会评估你的要求. 在此问题上,请具体说明配置的现状:

-   配置有效但需要官方支持.
-   配置不起作用,需要更改.

### 支持的运行时间

-   Fluid框架支持节点.js版本22和24同时收到 [上游支助](https://nodejs.org/en/about/previous-releases)。 。 。 .
    -   流体框架将停止支持第22版 [当上游支持于2027-04-30结束时](https://github.com/nodejs/release#release-schedule)。 。 。 .
    -   流体框架不支持节点.js与 `--no-experimental-fetch` 旗帜.
-   Fluid框架支持支持ES2022标准库的现代浏览器.

### 支持的工具

-   [类型脚本 6.0](https://typescriptdocs.com/release-notes/TypeScript%206.0)数字 :
    -   流体框架支持全部 [`strict`](https://www.typescriptlang.org/tsconfig) 选项.
    -   设定建设目标(`lib`, (中文(简体) ), `target`改为: `ES2022` 或后会.
    -   启用 [`strictNullChecks`](https://www.typescriptlang.org/tsconfig)。 。 。 .
    -   流体框架不支持 [在 TypeScript 6.0 中贬值的配置选项](https://typescriptdocs.com/release-notes/TypeScript%206.0#breaking-changes-and-deprecations-in-typescript-6-0)。 。 。 .
    -   流体框架不完全支持 `exactOptionalPropertyTypes`。 。 。 . 如果您启用此选项, 请不要使用 `in`, (中文(简体) ), `Reflect.has`, (中文(简体) ), `Object.hasOwn`,或 `Object.prototype.hasOwnProperty` 改为Fluid框架类型的窄成员. 这些方法可以错误地排除 `undefined` 从可能的值.
-   [网络软件包](https://webpack.js.org/) 页:1
    -   我们不需要一个特定的捆绑者. 其他处理ES模块的捆绑机可以工作,但我们只积极测试网页包.

### 模块分辨率

在类型脚本中 `compilerOptions`,使用时 [`Node16`, (中文(简体) ), `Node20`, (中文(简体) ), `NodeNext`,或 `Bundler`](https://www.typescriptlang.org/tsconfig#moduleResolution) 模块分辨率. 这些设置遵循 [节点.js v12+无害环境管理 分辨率和加载算法](https://nodejs.github.io/nodejs.dev/en/api/v20/esm/#resolution-and-loading-algorithm)。 。 。 .

不使用 `Node10` 模块分辨率.

### 模块格式

-   ES模块: 使用ES模块来消耗Fluid框架客户端软件包,包括在Node.js中.
-   常见JS : Fluid Framework在3.0版本或后期不正式支持CommonJS.

## 贡献准则

你们可以 [贡献](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) 通过这些方式实现流体框架:

-   回答问题 [GitHub 讨论](https://github.com/microsoft/FluidFramework/discussions)。 。 。 .
-   [提交错误报告](https://github.com/microsoft/FluidFramework/issues) 并且帮助验证修正.
-   审查 [源代码更改](https://github.com/microsoft/FluidFramework/pulls)。 。 。 .
-   [贡献错误修正](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md)。 。 。 .

详细指示改为: [repo 文档](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Home.md)。 。 。 .

本项目遵循 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息,改为: [《行为守则》经常被问到的问题](https://opensource.microsoft.com/codeofconduct/faq/)。 。 。 . 问题或评论,联系 [打开码@ microsoft.com](mailto:opencode@microsoft.com)。 。 。 .

这个项目可能包含微软项目的商标或标志,产品,或服务. 这些商标或标志的使用必须遵循微软 [商标和品牌准则](https://www.microsoft.com/trademarks)。 。 。 . 在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 帮助

读取 [流体框架文件](https://fluidframework.com/docs/) 用于了解流体框架概念和API.

要求提供文件未载列的资料, [创建问题](https://github.com/microsoft/FluidFramework/blob/main/docs/content/Contributing/Submitting-Bugs-and-Feature-Requests.md)。 。 。 .

## 商标

这个项目可能包含微软项目的商标或标志,产品,或服务.

这些商标或标志的使用必须遵循微软的 [商标和品牌准则](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general)。 。 。 .

在这个项目的修改后版本中使用微软商标或标志不得造成混淆或暗示微软赞助.

## 常见问题

### @fluidframework/test-runtime-utils 是什么？

流体运行时间测试设施

### 如何安装 @fluidframework/test-runtime-utils？

在项目目录运行 npm install @fluidframework/test-runtime-utils，或使用 pnpm add / yarn add / bun add。

### @fluidframework/test-runtime-utils 支持 TypeScript 吗？

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

### @fluidframework/test-runtime-utils 支持 ESM 还是 CommonJS？

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

### @fluidframework/test-runtime-utils 可以商用吗？

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

### @fluidframework/test-runtime-utils 的下载量有多少？

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

### @fluidframework/test-runtime-utils 还在维护吗？

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