@fluidframework/test-utils 2.90.0 → 2.92.0

package/src/index.ts

@@ -3,8 +3,12 @@
  * Licensed under the MIT License.
  */
 
+export type { IEventAndErrorTrackingLogger } from "./eventAndErrorLogger.js";
+export {
+	EventAndErrorTrackingLogger,
+	getUnexpectedLogErrorException,
+} from "./eventAndErrorLogger.js";
 export { IProvideTestFluidObject, ITestFluidObject } from "./interfaces.js";
-export { LoaderContainerTracker } from "./loaderContainerTracker.js";
 export {
 	fluidEntryPoint,
 	LocalCodeLoader,
@@ -30,25 +34,33 @@ export {
 	TestFluidObjectFactory,
 	TestDataObjectKind,
 } from "./testFluidObject.js";
-export {
-	createDocumentId,
-	DataObjectFactoryType,
-	EventAndErrorTrackingLogger,
-	type IEventAndErrorTrackingLogger,
-	getUnexpectedLogErrorException,
+
+// #region Exports with load side-effect
+// The below runtime (not "type") exports transitively or directly import
+// timeoutUtils.ts, which always executes on import and may patch Mocha's timeout
+// handling. That patching only takes effect when consumers use
+// @fluid-internal/mocha-test-setup that sets globalThis.getMochaModule.
+// @fluid-internal/mocha-test-setup is pervasive in our tests and thus patch
+// is usually in effect (when this package is used).
+export { LoaderContainerTracker } from "./loaderContainerTracker.js";
+export type {
 	IDocumentIdStrategy,
 	IOpProcessingController,
 	ITestContainerConfig,
 	ITestObjectProvider,
+} from "./testObjectProvider.js";
+export {
+	createDocumentId,
+	DataObjectFactoryType,
 	TestObjectProvider,
 	TestObjectProviderWithVersionedLoad,
 } from "./testObjectProvider.js";
+export type { SummaryInfo } from "./TestSummaryUtils.js";
 export {
 	createSummarizer,
 	createSummarizerCore,
 	createSummarizerFromFactory,
 	summarizeNow,
-	SummaryInfo,
 } from "./TestSummaryUtils.js";
 export {
 	timeoutAwait,
@@ -63,6 +75,8 @@ export {
 	getContainerEntryPointBackCompat,
 	getDataStoreEntryPointBackCompat,
 } from "./containerUtils.js";
+// #endregion
+
 export {
 	type ContainerRuntimeFactoryWithDefaultDataStoreConstructor,
 	type ContainerRuntimeFactoryWithDefaultDataStoreProps,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/test-utils";
-export const pkgVersion = "2.90.0";
+export const pkgVersion = "2.92.0";

package/src/testObjectProvider.ts

@@ -18,7 +18,6 @@ import {
 import type { IContainerRuntimeOptionsInternal } from "@fluidframework/container-runtime/internal";
 import {
 	IRequestHeader,
-	ITelemetryBaseEvent,
 	ITelemetryBaseLogger,
 	ITelemetryBaseProperties,
 	TelemetryBaseEventPropertyType,
@@ -32,7 +31,6 @@ import {
 import { isOdspResolvedUrl } from "@fluidframework/odsp-driver/internal";
 import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
 import {
-	type ITelemetryGenericEventExt,
 	createChildLogger,
 	createMultiSinkLogger,
 	type ITelemetryLoggerPropertyBags,
@@ -41,10 +39,14 @@ import {
 } from "@fluidframework/telemetry-utils/internal";
 import { v4 as uuid } from "uuid";
 
+import type { IEventAndErrorTrackingLogger } from "./eventAndErrorLogger.js";
+import {
+	EventAndErrorTrackingLogger,
+	getUnexpectedLogErrorException,
+} from "./eventAndErrorLogger.js";
 import { LoaderContainerTracker } from "./loaderContainerTracker.js";
 import { LocalCodeLoader, fluidEntryPoint } from "./localCodeLoader.js";
 import { createAndAttachContainer } from "./localLoader.js";
-import { isNonEmptyArray } from "./nonEmptyArrayType.js";
 import { ChannelFactoryRegistry } from "./testFluidObject.js";
 
 const defaultCodeDetails: IFluidCodeDetails = {
@@ -329,111 +331,6 @@ function getDocumentIdStrategy(type?: TestDriverTypes): IDocumentIdStrategy {
 	}
 }
 
-/** @internal */
-export interface IEventAndErrorTrackingLogger {
-	registerExpectedEvent: (...orderedExpectedEvents: ITelemetryGenericEventExt[]) => void;
-	reportAndClearTrackedEvents: () => {
-		expectedNotFound: { index: number; event: ITelemetryGenericEventExt }[];
-		unexpectedErrors: ITelemetryBaseEvent[];
-	};
-}
-
-/**
- * This class tracks events. It allows specifying expected events, which will be looked for in order.
- * It also tracks all unexpected errors.
- * At any point you call reportAndClearTrackedEvents which will provide all unexpected errors, and
- * any expected events that have not occurred.
- * @internal
- */
-export class EventAndErrorTrackingLogger
-	implements ITelemetryBaseLogger, IEventAndErrorTrackingLogger
-{
-	/**
-	 * Even if these error events are logged, tests should still be allowed to pass
-	 * Additionally, if downgrade is true, then log as generic (e.g. to avoid polluting the e2e test logs)
-	 */
-	private readonly allowedErrors: { eventName: string; downgrade?: true }[] = [
-		// This log was removed in current version as unnecessary, but it's still present in previous versions
-		{
-			eventName: "fluid:telemetry:Container:NoRealStorageInDetachedContainer",
-			downgrade: true,
-		},
-		// This log's category changes depending on the op latency. test results shouldn't be affected but if we see lots we'd like an alert from the logs.
-		{ eventName: "fluid:telemetry:OpRoundtripTime" },
-	];
-
-	constructor(private readonly baseLogger?: ITelemetryBaseLogger) {}
-
-	private readonly expectedEvents: { index: number; event: ITelemetryGenericEventExt }[] = [];
-	private readonly unexpectedErrors: ITelemetryBaseEvent[] = [];
-
-	public registerExpectedEvent(...orderedExpectedEvents: ITelemetryGenericEventExt[]): void {
-		if (this.expectedEvents.length !== 0) {
-			// we don't have to error here. just no reason not to. given the events must be
-			// ordered it could be tricky to figure out problems around multiple registrations.
-			throw new Error(
-				"Expected events already registered.\n" +
-					"Call reportAndClearTrackedEvents to clear them before registering more",
-			);
-		}
-		this.expectedEvents.push(
-			...orderedExpectedEvents.map((event, index) => ({ index, event })),
-		);
-	}
-
-	send(event: ITelemetryBaseEvent): void {
-		if (isNonEmptyArray(this.expectedEvents)) {
-			const ee = this.expectedEvents[0].event;
-			if (ee.eventName === event.eventName) {
-				let matches = true;
-				for (const key of Object.keys(ee)) {
-					if (ee[key] !== event[key]) {
-						matches = false;
-						break;
-					}
-				}
-				if (matches) {
-					// we found an expected event
-					// so remove it from the list of expected events
-					// and if it is an error, change it to generic
-					// this helps keep our telemetry clear of
-					// expected errors.
-					this.expectedEvents.shift();
-					if (event.category === "error") {
-						event.category = "generic";
-					}
-				}
-			}
-		}
-		if (event.category === "error") {
-			// Check to see if this error is allowed and if its category should be downgraded
-			const allowedError = this.allowedErrors.find(
-				({ eventName }) => eventName === event.eventName,
-			);
-
-			if (allowedError === undefined) {
-				this.unexpectedErrors.push(event);
-			} else if (allowedError.downgrade) {
-				event.category = "generic";
-			}
-		}
-
-		this.baseLogger?.send(event);
-	}
-
-	public reportAndClearTrackedEvents(): {
-		expectedNotFound: { index: number; event: ITelemetryGenericEventExt }[];
-		unexpectedErrors: ITelemetryBaseEvent[];
-	} {
-		const expectedNotFound = this.expectedEvents.splice(0, this.expectedEvents.length);
-		const unexpectedErrors = this.unexpectedErrors.splice(0, this.unexpectedErrors.length);
-		return {
-			expectedNotFound,
-			unexpectedErrors,
-		};
-	}
-}
-
 /**
  * Shared base class for test object provider.  Contain code for loader and container creation and loading
  * @internal
@@ -1171,50 +1068,3 @@ function getUrlTelemetryProps(
 
 	return tagData(TelemetryDataTag.UserData, props);
 }
-
-/** Summarize the event with just the primary properties, for succinct output in case of test failure */
-const primaryEventProps = ({
-	category,
-	eventName,
-	error,
-	errorType,
-}: ITelemetryBaseEvent): Partial<ITelemetryBaseEvent> => ({
-	category,
-	eventName,
-	error,
-	errorType,
-	["..."]: "*** Additional properties not shown, see full log for details ***",
-});
-
-/**
- * Retrieves unexpected errors from a logger and returns them as an exception.
- *
- * @internal
- */
-export function getUnexpectedLogErrorException(
-	logger: IEventAndErrorTrackingLogger | undefined,
-	prefix?: string,
-): Error | undefined {
-	if (logger === undefined) {
-		return;
-	}
-	const results = logger.reportAndClearTrackedEvents();
-	if (results.unexpectedErrors.length > 0) {
-		return new Error(
-			`${prefix ?? ""}Unexpected Errors in Logs:\n${JSON.stringify(
-				results.unexpectedErrors.map(primaryEventProps),
-				undefined,
-				2,
-			)}`,
-		);
-	}
-	if (results.expectedNotFound.length > 0) {
-		return new Error(
-			`${prefix ?? ""}Expected Events not found:\n${JSON.stringify(
-				results.expectedNotFound,
-				undefined,
-				2,
-			)}`,
-		);
-	}
-}

package/src/timeoutUtils.ts

@@ -3,7 +3,15 @@
  * Licensed under the MIT License.
  */
 
+// Warning: this module has load side effect of patching Mocha's timeout handling.
+// See globalThis.getMochaModule use below.
+
 import { assert, Deferred } from "@fluidframework/core-utils/internal";
+// Note that "@types/mocha" is only a devDependency of this package.
+// None of the mocha types are exposed through exports and thus it's reasonable
+// to leave mocha as a devDependency only. Further, the underlying code is only
+// used when @fluid-internal/mocha-test-setup is used and that package dictates
+// a mocha version.
 import type * as Mocha from "mocha";
 
 const timeBuffer = 15; // leave 15 ms leeway for finish processing