@fluidframework/test-utils 2.0.0-dev.2.3.0.115467 → 2.0.0-dev.4.1.0.148229

package/src/TestSummaryUtils.ts

@@ -6,158 +6,157 @@
 import { ContainerRuntimeFactoryWithDefaultDataStore } from "@fluidframework/aqueduct";
 import { assert } from "@fluidframework/common-utils";
 import { IContainer, IHostLoader, LoaderHeader } from "@fluidframework/container-definitions";
-import { ConnectionState } from "@fluidframework/container-loader";
 import {
-    IGCRuntimeOptions,
-    ISummarizer,
-    ISummaryRuntimeOptions,
+	IGCRuntimeOptions,
+	ISummarizer,
+	ISummaryRuntimeOptions,
 } from "@fluidframework/container-runtime";
 import { FluidObject, IRequest } from "@fluidframework/core-interfaces";
 import { DriverHeader } from "@fluidframework/driver-definitions";
 import {
-    IContainerRuntimeBase,
-    IFluidDataStoreFactory,
-    NamedFluidDataStoreRegistryEntries,
+	IContainerRuntimeBase,
+	IFluidDataStoreFactory,
+	NamedFluidDataStoreRegistryEntries,
 } from "@fluidframework/runtime-definitions";
 import { requestFluidObject } from "@fluidframework/runtime-utils";
 import { IConfigProviderBase } from "@fluidframework/telemetry-utils";
+import { ITelemetryBaseLogger } from "@fluidframework/common-definitions";
 import { ITestContainerConfig, ITestObjectProvider } from "./testObjectProvider";
 import { mockConfigProvider } from "./TestConfigs";
+import { waitForContainerConnection } from "./containerUtils";
+import { timeoutAwait } from "./timeoutUtils";
 
 const summarizerClientType = "summarizer";
 
-async function createSummarizerCore(absoluteUrl: string | undefined, loader: IHostLoader, summaryVersion?: string) {
-    if (absoluteUrl === undefined) {
-        throw new Error("URL could not be resolved");
-    }
-
-    const request: IRequest = {
-        headers: {
-            [LoaderHeader.cache]: false,
-            [LoaderHeader.clientDetails]: {
-                capabilities: { interactive: false },
-                type: summarizerClientType,
-            },
-            [DriverHeader.summarizingClient]: true,
-            [LoaderHeader.reconnect]: false,
-            [LoaderHeader.version]: summaryVersion,
-        },
-        url: absoluteUrl,
-    };
-    const summarizerContainer = await loader.resolve(request);
-    await waitForContainerConnection(summarizerContainer);
-
-    const fluidObject =
-        await requestFluidObject<FluidObject<ISummarizer>>(summarizerContainer, { url: "_summarizer" });
-    if (fluidObject.ISummarizer === undefined) {
-        throw new Error("Fluid object does not implement ISummarizer");
-    }
-
-    return {
-        container: summarizerContainer,
-        summarizer: fluidObject.ISummarizer,
-    };
+async function createSummarizerCore(
+	container: IContainer,
+	loader: IHostLoader,
+	summaryVersion?: string,
+) {
+	const absoluteUrl = await container.getAbsoluteUrl("");
+	if (absoluteUrl === undefined) {
+		throw new Error("URL could not be resolved");
+	}
+
+	const request: IRequest = {
+		headers: {
+			[LoaderHeader.cache]: false,
+			[LoaderHeader.clientDetails]: {
+				capabilities: { interactive: false },
+				type: summarizerClientType,
+			},
+			[DriverHeader.summarizingClient]: true,
+			[LoaderHeader.version]: summaryVersion,
+		},
+		url: absoluteUrl,
+	};
+	const summarizerContainer = await loader.resolve(request);
+	await waitForContainerConnection(summarizerContainer);
+
+	const fluidObject: FluidObject<ISummarizer> | undefined = summarizerContainer.getEntryPoint
+		? await summarizerContainer.getEntryPoint?.()
+		: await requestFluidObject<FluidObject<ISummarizer>>(summarizerContainer, {
+				url: "_summarizer",
+		  });
+	if (fluidObject?.ISummarizer === undefined) {
+		throw new Error("Fluid object does not implement ISummarizer");
+	}
+
+	return {
+		container: summarizerContainer,
+		summarizer: fluidObject.ISummarizer,
+	};
 }
 
 const defaultSummaryOptions: ISummaryRuntimeOptions = {
-    summaryConfigOverrides: {
-        state: "disableHeuristics",
-        maxAckWaitTime: 10000,
-        maxOpsSinceLastSummary: 7000,
-        initialSummarizerDelayMs: 0,
-        summarizerClientElection: false,
-    },
+	summaryConfigOverrides: {
+		state: "disableHeuristics",
+		maxAckWaitTime: 10000,
+		maxOpsSinceLastSummary: 7000,
+		initialSummarizerDelayMs: 0,
+	},
 };
 
+/**
+ * Creates a summarizer client from the given container and data store factory, and returns the summarizer client's
+ * IContainer and ISummarizer.
+ * The ISummarizer can be used to generate on-demand summaries. The IContainer can be used to fetch data stores, etc.
+ */
 export async function createSummarizerFromFactory(
-    provider: ITestObjectProvider,
-    container: IContainer,
-    dataStoreFactory: IFluidDataStoreFactory,
-    summaryVersion?: string,
-    containerRuntimeFactoryType = ContainerRuntimeFactoryWithDefaultDataStore,
-    registryEntries?: NamedFluidDataStoreRegistryEntries,
-): Promise<ISummarizer> {
-    const innerRequestHandler = async (request: IRequest, runtime: IContainerRuntimeBase) =>
-        runtime.IFluidHandleContext.resolveHandle(request);
-    const runtimeFactory = new containerRuntimeFactoryType(
-        dataStoreFactory,
-        registryEntries ??
-        [
-            [dataStoreFactory.type, Promise.resolve(dataStoreFactory)],
-        ],
-        undefined,
-        [innerRequestHandler],
-        { summaryOptions: defaultSummaryOptions },
-    );
-
-    const loader = provider.createLoader(
-        [[provider.defaultCodeDetails, runtimeFactory]],
-        { configProvider: mockConfigProvider() },
-    );
-    const absoluteUrl = await container.getAbsoluteUrl("");
-    return (await createSummarizerCore(absoluteUrl, loader, summaryVersion)).summarizer;
+	provider: ITestObjectProvider,
+	container: IContainer,
+	dataStoreFactory: IFluidDataStoreFactory,
+	summaryVersion?: string,
+	containerRuntimeFactoryType = ContainerRuntimeFactoryWithDefaultDataStore,
+	registryEntries?: NamedFluidDataStoreRegistryEntries,
+	logger?: ITelemetryBaseLogger,
+): Promise<{ container: IContainer; summarizer: ISummarizer }> {
+	const innerRequestHandler = async (request: IRequest, runtime: IContainerRuntimeBase) =>
+		runtime.IFluidHandleContext.resolveHandle(request);
+	const runtimeFactory = new containerRuntimeFactoryType(
+		dataStoreFactory,
+		registryEntries ?? [[dataStoreFactory.type, Promise.resolve(dataStoreFactory)]],
+		undefined,
+		[innerRequestHandler],
+		{ summaryOptions: defaultSummaryOptions },
+	);
+
+	const loader = provider.createLoader([[provider.defaultCodeDetails, runtimeFactory]], {
+		configProvider: mockConfigProvider(),
+		logger,
+	});
+	return createSummarizerCore(container, loader, summaryVersion);
 }
 
+/**
+ * Creates a summarizer client from the given container and returns the summarizer client's IContainer and ISummarizer.
+ * The ISummarizer can be used to generate on-demand summaries. The IContainer can be used to fetch data stores, etc.
+ */
 export async function createSummarizer(
-    provider: ITestObjectProvider,
-    container: IContainer,
-    summaryVersion?: string,
-    gcOptions?: IGCRuntimeOptions,
-    configProvider: IConfigProviderBase = mockConfigProvider(),
-): Promise<ISummarizer> {
-    const absoluteUrl = await container.getAbsoluteUrl("");
-    return (await createSummarizerWithContainer(
-        provider,
-        absoluteUrl,
-        summaryVersion,
-        gcOptions,
-        configProvider,
-    )).summarizer;
-}
-
-export async function createSummarizerWithContainer(
-    provider: ITestObjectProvider,
-    absoluteUrl: string | undefined,
-    summaryVersion?: string,
-    gcOptions?: IGCRuntimeOptions,
-    configProvider: IConfigProviderBase = mockConfigProvider(),
-): Promise<{ container: IContainer; summarizer: ISummarizer; }> {
-    const testContainerConfig: ITestContainerConfig = {
-        runtimeOptions: {
-            summaryOptions: defaultSummaryOptions,
-            gcOptions,
-        },
-        loaderProps: { configProvider },
-    };
-    const loader = provider.makeTestLoader(testContainerConfig);
-    return createSummarizerCore(absoluteUrl, loader, summaryVersion);
+	provider: ITestObjectProvider,
+	container: IContainer,
+	summaryVersion?: string,
+	gcOptions?: IGCRuntimeOptions,
+	configProvider: IConfigProviderBase = mockConfigProvider(),
+	logger?: ITelemetryBaseLogger,
+): Promise<{ container: IContainer; summarizer: ISummarizer }> {
+	const testContainerConfig: ITestContainerConfig = {
+		runtimeOptions: {
+			summaryOptions: defaultSummaryOptions,
+			gcOptions,
+		},
+		loaderProps: { configProvider, logger },
+	};
+	const loader = provider.makeTestLoader(testContainerConfig);
+	return createSummarizerCore(container, loader, summaryVersion);
 }
 
+/**
+ * Summarizes on demand and returns the summary tree, the version number and the reference sequence number of the
+ * submitted summary.
+ */
 export async function summarizeNow(summarizer: ISummarizer, reason: string = "end-to-end test") {
-    const result = summarizer.summarizeOnDemand({ reason });
-
-    const submitResult = await result.summarySubmitted;
-    assert(submitResult.success, "on-demand summary should submit");
-    assert(submitResult.data.stage === "submit",
-        "on-demand summary submitted data stage should be submit");
-    assert(submitResult.data.summaryTree !== undefined, "summary tree should exist");
+	const result = summarizer.summarizeOnDemand({ reason });
 
-    const broadcastResult = await result.summaryOpBroadcasted;
-    assert(broadcastResult.success, "summary op should be broadcast");
+	const submitResult = await timeoutAwait(result.summarySubmitted);
+	assert(submitResult.success, "on-demand summary should submit");
+	assert(
+		submitResult.data.stage === "submit",
+		"on-demand summary submitted data stage should be submit",
+	);
+	assert(submitResult.data.summaryTree !== undefined, "summary tree should exist");
 
-    const ackNackResult = await result.receivedSummaryAckOrNack;
-    assert(ackNackResult.success, "summary op should be acked");
+	const broadcastResult = await timeoutAwait(result.summaryOpBroadcasted);
+	assert(broadcastResult.success, "summary op should be broadcast");
 
-    await new Promise((resolve) => process.nextTick(resolve));
+	const ackNackResult = await timeoutAwait(result.receivedSummaryAckOrNack);
+	assert(ackNackResult.success, "summary op should be acked");
 
-    return {
-        summaryTree: submitResult.data.summaryTree,
-        summaryVersion: ackNackResult.data.summaryAckOp.contents.handle,
-    };
-}
+	await new Promise((resolve) => process.nextTick(resolve));
 
-export async function waitForContainerConnection(container: IContainer): Promise<void> {
-    if (container.connectionState !== ConnectionState.Connected) {
-        return new Promise((resolve) => container.once("connected", () => resolve()));
-    }
+	return {
+		summaryTree: submitResult.data.summaryTree,
+		summaryVersion: ackNackResult.data.summaryAckOp.contents.handle,
+		summaryRefSeq: submitResult.data.referenceSequenceNumber,
+	};
 }

package/src/containerUtils.ts

@@ -0,0 +1,48 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IContainer } from "@fluidframework/container-definitions";
+import { ConnectionState } from "@fluidframework/container-loader";
+import { PromiseExecutor, timeoutPromise, TimeoutWithError } from "./timeoutUtils";
+
+/**
+ * Utility function to wait for the specified Container to be in Connected state.
+ * If the Container is already connected, the Promise returns immediately; otherwise it resolves when the Container emits
+ * its 'connected' event.
+ * If failOnContainerClose === true, the returned Promise will be rejected if the container emits a 'closed' event
+ * before a 'connected' event.
+ * @param container - The container to wait for.
+ * @param failOnContainerClose - If true, the returned Promise will be rejected if the container emits a 'closed' event
+ * before a 'connected' event.
+ * Defaults to true.
+ * @param timeoutOptions - Options related to the behavior of the timeout.
+ * If provided, the returned Promise will reject if the container hasn't emitted relevant events in timeoutOptions.durationMs.
+ * If not provided, the Promise will wait indefinitely for the Container to emit its 'connected' (or 'closed', if
+ * failOnContainerClose === true) event.
+ *
+ * @returns A Promise that either:
+ * - Resolves when the specified container emits a 'connected' event (or immediately if the Container is already connected).
+ * - Rejects if failOnContainerClose === true and the container emits a 'closed' event before a 'connected' event.
+ * - Rejects after timeoutOptions.durationMs if timeoutOptions !== undefined and the container does not emit relevant
+ * events, within that timeframe.
+ */
+export async function waitForContainerConnection(
+	container: IContainer,
+	failOnContainerClose: boolean = true,
+	timeoutOptions?: TimeoutWithError,
+): Promise<void> {
+	if (container.connectionState !== ConnectionState.Connected) {
+		const executor: PromiseExecutor = (resolve, reject) => {
+			container.once("connected", () => resolve());
+			if (failOnContainerClose) {
+				container.once("closed", (error) => reject(error));
+			}
+		};
+
+		return timeoutOptions === undefined
+			? new Promise(executor)
+			: timeoutPromise(executor, timeoutOptions);
+	}
+}

package/src/index.ts

@@ -3,37 +3,38 @@
  * Licensed under the MIT License.
  */
 
-export { wrapDocumentService, wrapDocumentServiceFactory, wrapDocumentStorageService } from "./DriverWrappers";
+export {
+	wrapDocumentService,
+	wrapDocumentServiceFactory,
+	wrapDocumentStorageService,
+} from "./DriverWrappers";
 export { IProvideTestFluidObject, ITestFluidObject } from "./interfaces";
 export { LoaderContainerTracker } from "./loaderContainerTracker";
 export { fluidEntryPoint, LocalCodeLoader, SupportedExportInterfaces } from "./localCodeLoader";
 export { createAndAttachContainer, createLoader } from "./localLoader";
 export { retryWithEventualValue } from "./retry";
 export { mockConfigProvider } from "./TestConfigs";
-export { createTestContainerRuntimeFactory, TestContainerRuntimeFactory } from "./testContainerRuntimeFactory";
+export {
+	createTestContainerRuntimeFactory,
+	TestContainerRuntimeFactory,
+} from "./testContainerRuntimeFactory";
 export { ChannelFactoryRegistry, TestFluidObject, TestFluidObjectFactory } from "./testFluidObject";
 export {
-    createDocumentId,
-    DataObjectFactoryType,
-    EventAndErrorTrackingLogger,
-    getUnexpectedLogErrorException,
-    IOpProcessingController,
-    ITestContainerConfig,
-    ITestObjectProvider,
-    TestObjectProvider,
+	createDocumentId,
+	DataObjectFactoryType,
+	EventAndErrorTrackingLogger,
+	getUnexpectedLogErrorException,
+	IOpProcessingController,
+	ITestContainerConfig,
+	ITestObjectProvider,
+	TestObjectProvider,
 } from "./testObjectProvider";
+export { createSummarizer, createSummarizerFromFactory, summarizeNow } from "./TestSummaryUtils";
 export {
-    createSummarizer,
-    createSummarizerFromFactory,
-    createSummarizerWithContainer,
-    summarizeNow,
-    waitForContainerConnection,
-} from "./TestSummaryUtils";
-export {
-    defaultTimeoutDurationMs,
-    ensureContainerConnected,
-    timeoutAwait,
-    timeoutPromise,
-    TimeoutWithError,
-    TimeoutWithValue,
+	defaultTimeoutDurationMs,
+	timeoutAwait,
+	timeoutPromise,
+	TimeoutWithError,
+	TimeoutWithValue,
 } from "./timeoutUtils";
+export { waitForContainerConnection } from "./containerUtils";

package/src/interfaces.ts

@@ -5,17 +5,20 @@
 
 import { IFluidDataStoreRuntime } from "@fluidframework/datastore-definitions";
 import { ISharedMap } from "@fluidframework/map";
-import { IFluidDataStoreContext, IFluidDataStoreChannel } from "@fluidframework/runtime-definitions";
+import {
+	IFluidDataStoreContext,
+	IFluidDataStoreChannel,
+} from "@fluidframework/runtime-definitions";
 import { IFluidLoadable } from "@fluidframework/core-interfaces";
 
 export interface IProvideTestFluidObject {
-    readonly ITestFluidObject: ITestFluidObject;
+	readonly ITestFluidObject: ITestFluidObject;
 }
 
 export interface ITestFluidObject extends IProvideTestFluidObject, IFluidLoadable {
-    root: ISharedMap;
-    readonly runtime: IFluidDataStoreRuntime;
-    readonly channel: IFluidDataStoreChannel;
-    readonly context: IFluidDataStoreContext;
-    getSharedObject<T = any>(id: string): Promise<T>;
+	root: ISharedMap;
+	readonly runtime: IFluidDataStoreRuntime;
+	readonly channel: IFluidDataStoreChannel;
+	readonly context: IFluidDataStoreContext;
+	getSharedObject<T = any>(id: string): Promise<T>;
 }