# @fluidframework/test-utils 中文文档 规范地址：https://npmcn.com/package/%40fluidframework/test-utils/ 版本：3\.12\.0 npm 元数据更新时间：2026-11-10T22:57:17.716Z 中文译文更新时间：2026-11-15T02:09:41.876Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fluidframework/test-utils 原文对照：https://npmcn.com/package/%40fluidframework/test-utils/?lang=original 项目主页：https://fluidframework.com/ 源码仓库：https://github.com/microsoft/FluidFramework ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.1 MB，217 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：22 个 - 首次发布：2020-09-01T04:29:57.145Z - 最新版本发布：2026-11-10T22:57:17.565Z - 近 30 天下载量：11499（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：695（近 12 个月 48 个） ## 中文简介 流体测试用具 ## 安装 ```sh npm install @fluidframework/test-utils ``` 也可以使用：`pnpm add @fluidframework/test-utils`、`yarn add @fluidframework/test-utils`、`bun add @fluidframework/test-utils` ## README # @fluidframework/test-utils (英语) 此软件包包含用于在流体框架中写入端到端测试的功能. 它有助于创建简单的托管应用程序来测试流体对象和系统的其他功能. 内部注解:目前,在Mocha下装货时也具有负载副作用 `@fluid-internal/mocha-test-setup` 已使用。 副作用将试图在试验例否则暂停之前注入出错15ms. ## 使用 Fluid 框架库 对于依赖流体框架库的公共API,我们建议 `^` (caret)版本范围. 例如,使用 `^1.3.4`。 。 。 . 依赖不稳定的API,例如: `beta` API,我们推荐一个更具限制性的版本范围. 例如,使用一个 `~` 版本范围. ## 安装 运行此命令以安装软件包 : ```bash npm i @fluidframework/test-utils -D ``` ## 从此软件包导入 此软件包使用 [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-utils`。 。 。 . 导入 `legacy` API 从 `@fluidframework/test-utils/legacy`。 。 。 . ## API 文档 读取 **@fluidframework/test-utils (英语)** API 文档 [https://fluidframework.com/docs/apis/test-utils (中文(简体) )](https://fluidframework.com/docs/apis/test-utils)。 。 。 . ## 本地代码加载器 `LocalCodeLoader` 内 `localCodeLoader.ts` 是一个简单的代码加载器,可以加载带有指定切入点的流体包. 它可用于装入多个不同流体包并带有不同来源(`IFluidCodeDetails`) (中文(简体) ). 应当通过在源列表中传递到切入点映射来创建. 那么进入点可以是 `IFluidDataStoreFactory`, (中文(简体) ), `IRuntimeFactory` 或一个 `fluidExport`数字 : ```typeScript // The fluidEntryPoint type. export type fluidEntryPoint = Partial; // Constructor for LocalCodeLoader. constructor(packageEntries: Iterable<[IFluidCodeDetails, fluidEntryPoint]>); ``` 装货时,它会收回 `fluidEntryPoint` 匹配软件包 `IFluidCodeDetails` 并装入它. ## 本地装入器 `localLoader.ts` 包含几种方法: ### `createLocalLoader` 这种方法创建了一个简单的 `Loader` 用于解析容器或请求流体对象. 它的创建应包含一个源到入点映射列表(类型) `fluidEntryPoint` 说明 [本地代码记录器](https://npmcn.com/package/%40fluidframework/test-utils/#readme-Local-Code-Loader) 页:1 `ILocalDeltaConnectionServer` 还有一个 `IUrlResolver`数字 : ```typeScript export function createLocalLoader( packageEntries: Iterable<[ IFluidCodeDetails, Partial ]>, deltaConnectionServer: ILocalDeltaConnectionServer, urlResolver: IUrlResolver, ): ILoader; ``` - 它创造了一个 `LocalCodeLoader` 使用 `fluidEntryPoint` 列表以装入容器代码. - 它创造了一个 `DocumentServiceFactory` 用作容器和服务器之间的驱动层. ### `createAndAttachContainer` 此方法创建并附加 `Container` 用给定的 `source` 还有一个 `attachRequest`。一个 `ILoader` 还应通过其中将用来装入 `Container`编辑 `attachRequest` 每个 URL 解析器的格式不同。 大多数解析器都有帮助器方法来创建附加请求. 你应该用 url 解析器上的帮助方法传递给加载器生成 `attachRequest`数字 : ```typescript export async function createAndAttachContainer( source: IFluidCodeDetails, loader: ILoader, attachRequest: IRequest, ): Promise; ``` 通常的流量是创建 `LocalLoader` 拨打 `createLocalLoader` 然后用它调用 `createAndAttachContainer`然而,这应当与任何 `ILoader`。 。 。 . ## 测试流体对象 `testFluidObject.ts` 提供 `TestFluidObject` 财务报告和审定财务报表 `TestFluidObjectFactory` 帮助测试分布式数据结构. 它可用于创建流体对象(TestFluid Object),并配有指定的一组DDS,然后可以根据需要稍后取回. 例如,如果需要带有一对共享纹章、一对共享纹章和一对 SparseMatrix 的流体对象,请创建 `TestFluidObjectFactory` 如下并使用此工厂创建流体对象: ```typeScript new TestFluidObjectFactory([ [ "sharedString1" /* id */, SharedString.getFactory() ], [ "sharedString2" /* id */, SharedString.getFactory() ], [ "directory" /* id */, SharedDirectory.getFactory() ], [ "matrix" /* id */, SparseMatrix.getFactory() ], ]); ``` 这个 `TestFluidObject` 初始化时会创建上面的 DS , 然后通过调用检索 `getSharedObject` 上面还有提供 `id` 用来创建它: ```typeScript const sharedString1 = testFluidObject.getSharedObject("sharedString1"); const sharedString1 = testFluidObject.getSharedObject("sharedString2"); const directory = testFluidObject.getSharedObject("directory"); const matrix = testFluidObject.getSharedObject("matrix"); ``` > 如果您希望DDS成为注册的一部分, 以便日后可以创建, 但不希望 `TestFluidObject` 在初始化、 使用时创建 `id` 作为 `undefined` 输入 `TestFluidObjectFactory` 创建. ## 操作处理控制器 `OpProcessingController` 提供测试中操作处理的控制。 它允许您暂停并恢复容器/流体对象的操作处理。 这也让你等待操作被他们和服务器处理完毕. `OpProcessingController` 应该通过在 `ILocalDeltaConnectionServer` 用于测试。 然后您可以注册流体对象/ 容器, 您想要用它控制其操作 . 例如,考虑一下您在 DDS 上执行一些操作的情景,想要验证远程客户端的 DDS 应用了操作. 您必须等待操作发送到服务器,服务器处理操作,发送到远程客户端,远程客户端处理操作. 你可以用这个 `OpProcessingController` 等待这一切的发生 通过打电话 `process` 就在这 检查如何 [共享测试](https://npmcn.com/package/%40fluidframework/end-to-end-tests/src/test/sharedStringEndToEndTests.spec.ts) 这样做. ## 使用量 用于测试流体物体的典型用途如下: 1. 创建一个 `LocalDeltaConnectionServer`数字 : ```typescript const deltaConnectionServer: ILocalDeltaConnectionServer = LocalDeltaConnectionServer.create(); ``` 2. 创建一个 `LocalResolver`数字 : ```typescript const urlResolver: IUrlResolver = new LocalResolver(); ``` 3. 创建一个 `IFluidCodeDetails` (单位:千美元) `TestFluidObjectFactory` 它将成为流线入口(工厂绘图的代码细节): ```typescript const codeDetails: IFluidCodeDetails = { package: "sharedStringTestPackage", config: {}, }; const entryPoint = new TestFluidObjectFactory([["sharedString", SharedString.getFactory()]]); ``` > 这可以被任何 `IFluidDataStoreFactory` 或者说 `IRuntimeFactory`。当装货机被要求用上述编码细节解决集装箱时,它将装载上述工厂. 4. 创建本地 `Loader`数字 : ```typescript const loader: ILoader = createLocalLoader( [[codeDetails, entryPoint]], deltaConnectionServer, urlResolver, ); ``` 5. 创建并附加一个 `Container` 给它一个 `documentId` 用于解析容器的 URL: ```typescript const documentId = "testDocument"; const container = await createAndAttachContainer( codeDetails, loader, urlResolver.createCreateNewRequest(documentId), ); ``` ``` > We used the same `IFluidCodeDetails` that was used to create the `Loader` in step 3. ``` 6. 拿着 `Fluid object (TestFluidObject)` 通过使用 `getEntryPoint()` API 打开 `IContainer`。然后获取 `DDS` 要测试 : ```typescript const fluidObject = await container.getEntryPoint(); const sharedString = await fluidObject.getSharedObject("sharedString"); ``` > 这个 `ITestFluidObject` 已经创建了一个 `SharedString` 基于我们创建时提供的参数 `TestFluidObjectFactory` 在步骤2. 7. 要真正测试协作, 请创建第二个 `Loader`, (中文(简体) ), `Container`, (中文(简体) ), `fluid object` 财务报告和审定财务报表 `DDS` 它将作为远程客户端: ```typescript const documentUrl = `https://localhost/${documentId}`; const loader2: ILoader = createLocalLoader( [[codeDetails, entryPoint]], deltaConnectionServer, urlResolver, ); const container2 = await loader2.resolver({ url: documentUrl }); const fluidObject = await container2.getEntryPoint(); const sharedString2 = await fluidObject2.getSharedObject("sharedString"); ``` > 一定要用同样的 `ILocalDeltaConnectionServer` 创建 `Loader` 和同样的 `documentId` 装入 `Container`这将确保我们加载 `Container` 而不是创造新的. 这些步骤如下图所示: ![Image 1](https://npmcn.com/package/%40fluidframework/test-utils/end-to-end-tests.png) > 注意,本地驱动程序是由 `createLocalLoader` 方法,不需要明确创建. ## 示例 上述用途取自 [共享测试](https://npmcn.com/package/%40fluidframework/end-to-end-tests/src/test/sharedStringEndToEndTests.spec.ts) 这是一个非常基本的例子 如何使用这些功用. 还有一些其他例子(有些比较复杂) [目录](https://npmcn.com/package/%40fluidframework/end-to-end-tests/src/test)。 。 。 . ## 客户最低要求 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-utils 是什么？ 流体测试用具 ### 如何安装 @fluidframework/test-utils？ 在项目目录运行 npm install @fluidframework/test-utils，或使用 pnpm add / yarn add / bun add。 ### @fluidframework/test-utils 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fluidframework/test-utils 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @fluidframework/test-utils 可以商用吗？ @fluidframework/test-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @fluidframework/test-utils 的下载量有多少？ 根据 npm 官方下载统计，@fluidframework/test-utils 在 2026/10/15 – 2026/11/13 这 30 天内被下载 11,499 次，日均约 383 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fluidframework/test-utils 还在维护吗？ 最新版本 3\.12\.0 发布于 2026/11/11（4 天前）；至今共发布 695 个版本，其中过去 12 个月发布了 48 个；首次发布于 2020/09/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。