@fluidframework/test-utils (英语)

此软件包包含用于在流体框架中写入端到端测试的功能. 它有助于创建简单的托管应用程序来测试流体对象和系统的其他功能.

内部注解:目前,在Mocha下装货时也具有负载副作用 @fluid-internal/mocha-test-setup 已使用。 副作用将试图在试验例否则暂停之前注入出错15ms.

使用 Fluid 框架库

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

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

安装

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

npm i @fluidframework/test-utils -D

从此软件包导入

此软件包使用 packet.json 导出 通过支持级别将API分离. 有关支助保障的信息改为: API 支持级别。 。 。 .

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

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

API 文档

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

本地代码加载器

LocalCodeLoader 内 localCodeLoader.ts 是一个简单的代码加载器,可以加载带有指定切入点的流体包. 它可用于装入多个不同流体包并带有不同来源(IFluidCodeDetails) (中文(简体) ).

应当通过在源列表中传递到切入点映射来创建. 那么进入点可以是 IFluidDataStoreFactory, (中文(简体) ), IRuntimeFactory 或一个 fluidExport数字 :

// The fluidEntryPoint type.
export type fluidEntryPoint = Partial<IProvideRuntimeFactory & IProvideFluidDataStoreFactory & IFluidModule>;

// Constructor for LocalCodeLoader.
constructor(packageEntries: Iterable<[IFluidCodeDetails, fluidEntryPoint]>);

装货时,它会收回 fluidEntryPoint 匹配软件包 IFluidCodeDetails 并装入它.

本地装入器

localLoader.ts 包含几种方法:

createLocalLoader

这种方法创建了一个简单的 Loader 用于解析容器或请求流体对象.

它的创建应包含一个源到入点映射列表(类型) fluidEntryPoint 说明 本地代码记录器 页:1 ILocalDeltaConnectionServer 还有一个 IUrlResolver数字 :

export function createLocalLoader(
    packageEntries: Iterable<[
        IFluidCodeDetails,
        Partial<IProvideRuntimeFactory & IProvideFluidDataStoreFactory & IFluidModule>
    ]>,
    deltaConnectionServer: ILocalDeltaConnectionServer,
    urlResolver: IUrlResolver,
): ILoader;

• 它创造了一个 LocalCodeLoader 使用 fluidEntryPoint 列表以装入容器代码.
• 它创造了一个 DocumentServiceFactory 用作容器和服务器之间的驱动层.

createAndAttachContainer

此方法创建并附加 Container 用给定的 source 还有一个 attachRequest。一个 ILoader 还应通过其中将用来装入 Container编辑 attachRequest 每个 URL 解析器的格式不同。 大多数解析器都有帮助器方法来创建附加请求. 你应该用 url 解析器上的帮助方法传递给加载器生成 attachRequest数字 :

export async function createAndAttachContainer(
    source: IFluidCodeDetails,
    loader: ILoader,
    attachRequest: IRequest,
): Promise<IContainer>;

通常的流量是创建 LocalLoader 拨打 createLocalLoader 然后用它调用 createAndAttachContainer然而,这应当与任何 ILoader。 。 。 .

测试流体对象

testFluidObject.ts 提供 TestFluidObject 财务报告和审定财务报表 TestFluidObjectFactory 帮助测试分布式数据结构. 它可用于创建流体对象(TestFluid Object),并配有指定的一组DDS,然后可以根据需要稍后取回.

例如,如果需要带有一对共享纹章、一对共享纹章和一对 SparseMatrix 的流体对象,请创建 TestFluidObjectFactory 如下并使用此工厂创建流体对象:

new TestFluidObjectFactory([
    [ "sharedString1" /* id */, SharedString.getFactory() ],
    [ "sharedString2" /* id */, SharedString.getFactory() ],
    [ "directory" /* id */, SharedDirectory.getFactory() ],
    [ "matrix" /* id */, SparseMatrix.getFactory() ],
]);

这个 TestFluidObject 初始化时会创建上面的 DS , 然后通过调用检索 getSharedObject 上面还有提供 id 用来创建它:

const sharedString1 = testFluidObject.getSharedObject<SharedString>("sharedString1");
const sharedString1 = testFluidObject.getSharedObject<SharedString>("sharedString2");
const directory = testFluidObject.getSharedObject<SharedDirectory>("directory");
const matrix = testFluidObject.getSharedObject<SparseMatrix>("matrix");

如果您希望DDS成为注册的一部分, 以便日后可以创建, 但不希望 TestFluidObject 在初始化、 使用时创建 id 作为 undefined 输入 TestFluidObjectFactory 创建.

操作处理控制器

OpProcessingController 提供测试中操作处理的控制。 它允许您暂停并恢复容器/流体对象的操作处理。 这也让你等待操作被他们和服务器处理完毕.

OpProcessingController 应该通过在 ILocalDeltaConnectionServer 用于测试。 然后您可以注册流体对象/ 容器, 您想要用它控制其操作 .

例如,考虑一下您在 DDS 上执行一些操作的情景,想要验证远程客户端的 DDS 应用了操作. 您必须等待操作发送到服务器,服务器处理操作,发送到远程客户端,远程客户端处理操作.

你可以用这个 OpProcessingController 等待这一切的发生 通过打电话 process 就在这 检查如何 共享测试 这样做.

使用量

用于测试流体物体的典型用途如下:

1. 创建一个 LocalDeltaConnectionServer数字 :

   const deltaConnectionServer: ILocalDeltaConnectionServer = LocalDeltaConnectionServer.create();
   

2. 创建一个 LocalResolver数字 :

   const urlResolver: IUrlResolver = new LocalResolver();
   

3. 创建一个 IFluidCodeDetails (单位:千美元) TestFluidObjectFactory 它将成为流线入口(工厂绘图的代码细节):

   const codeDetails: IFluidCodeDetails = {
       package: "sharedStringTestPackage",
       config: {},
   };
   const entryPoint = new TestFluidObjectFactory([["sharedString", SharedString.getFactory()]]);
   

   这可以被任何 IFluidDataStoreFactory 或者说 IRuntimeFactory。当装货机被要求用上述编码细节解决集装箱时,它将装载上述工厂.

4. 创建本地 Loader数字 :

   const loader: ILoader = createLocalLoader(
       [[codeDetails, entryPoint]],
       deltaConnectionServer,
       urlResolver,
   );
   

5. 创建并附加一个 Container 给它一个 documentId 用于解析容器的 URL:

   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 要测试 :

   const fluidObject = await container.getEntryPoint();
   const sharedString = await fluidObject.getSharedObject<SharedString>("sharedString");
   

   这个 ITestFluidObject 已经创建了一个 SharedString 基于我们创建时提供的参数 TestFluidObjectFactory 在步骤2.

7. 要真正测试协作, 请创建第二个 Loader, (中文(简体) ), Container, (中文(简体) ), fluid object 财务报告和审定财务报表 DDS 它将作为远程客户端:

   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>("sharedString");
   

   一定要用同样的 ILocalDeltaConnectionServer 创建 Loader 和同样的 documentId 装入 Container这将确保我们加载 Container 而不是创造新的.

这些步骤如下图所示:

注意,本地驱动程序是由 createLocalLoader 方法,不需要明确创建.

示例

上述用途取自 共享测试 这是一个非常基本的例子 如何使用这些功用.

还有一些其他例子(有些比较复杂) 目录。 。 。 .

客户最低要求

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

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

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

支持的运行时间

• Fluid框架支持节点.js版本22和24同时收到 上游支助。 。 。 .
  • 流体框架将停止支持第22版 当上游支持于2027-04-30结束时。 。 。 .
  • 流体框架不支持节点.js与 --no-experimental-fetch 旗帜.
• Fluid框架支持支持ES2022标准库的现代浏览器.

支持的工具

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

模块分辨率

在类型脚本中 compilerOptions,使用时 Node16, (中文(简体) ), Node20, (中文(简体) ), NodeNext,或 Bundler 模块分辨率. 这些设置遵循 节点.js v12+无害环境管理 分辨率和加载算法。 。 。 .

不使用 Node10 模块分辨率.

模块格式

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

贡献准则

你们可以 贡献 通过这些方式实现流体框架:

• 回答问题 GitHub 讨论。 。 。 .
• 提交错误报告 并且帮助验证修正.
• 审查 源代码更改。 。 。 .
• 贡献错误修正。 。 。 .

详细指示改为: repo 文档。 。 。 .

本项目遵循 Microsoft 开源行为守则。 。 。 . 更多信息,改为: 《行为守则》经常被问到的问题。 。 。 . 问题或评论,联系 打开码@ microsoft.com。 。 。 .

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

帮助

读取 流体框架文件 用于了解流体框架概念和API.

要求提供文件未载列的资料, 创建问题。 。 。 .

商标

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

这些商标或标志的使用必须遵循微软的 商标和品牌准则。 。 。 .

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