improvement(test-runtime-utils): Add flushSomeMessages() to MockContainerRuntime (#25330)

## Description

This PR adds `flushSomeMessages()` to `MockContainerRuntime`. Similar to
`flush` but will only flush the specified number of messages queued
since the last time `flush` or `flushSomeMessages` was called. This is
intended to help simulate staging mode scenarios where we may want to
flush the pending ops queued prior to entering staging mode and not
flush the ops queued since entering staging mode.

---------

Co-authored-by: Copilot <[email protected]>

Author: scottn12

packages/runtime/test-runtime-utils/api-report/test-runtime-utils.legacy.beta.api.md

@@ -73,6 +73,7 @@ export class MockContainerRuntime extends TypedEventEmitter<IContainerRuntimeEve
     // (undocumented)
     finalizeIdRange(range: IdCreationRange): void;
     flush(): void;
+    flushSomeMessages(numMessages: number): void;
     // (undocumented)
     get isDirty(): boolean;
     protected maybeProcessIdAllocationMessage(message: ISequencedDocumentMessage): boolean;

packages/runtime/test-runtime-utils/package.json

@@ -153,7 +153,17 @@
 		"typescript": "~5.4.5"
 	},
 	"typeValidation": {
-		"broken": {},
+		"broken": {
+			"Class_MockFluidDataStoreRuntime": {
+				"forwardCompat": false
+			},
+			"Class_MockContainerRuntimeForReconnection": {
+				"forwardCompat": false
+			},
+			"Class_MockContainerRuntime": {
+				"forwardCompat": false
+			}
+		},
 		"entrypoint": "legacy"
 	}
 }

packages/runtime/test-runtime-utils/src/mocks.ts

@@ -337,9 +337,21 @@ export class MockContainerRuntime extends TypedEventEmitter<IContainerRuntimeEve
 
 	/**
 	 * If flush mode is set to FlushMode.TurnBased, it will send all messages queued since the last time
-	 * this method was called. Otherwise, calling the method does nothing.
+	 * this method (or `flushSomeMessages`) was called. Otherwise, calling the method does nothing.
 	 */
 	public flush() {
+		this.flushSomeMessages(this.outbox.length);
+	}
+
+	/**
+	 * If flush mode is set to FlushMode.TurnBased, it will send the specified number of messages from the outbox
+	 * queued since the last time this (or `flush`) was called. Otherwise, calling the method does nothing.
+	 * This can be useful when simulating staging mode, and we only want to flush certain messages.
+	 */
+	public flushSomeMessages(numMessages: number): void {
+		if (!Number.isInteger(numMessages) || numMessages < 0) {
+			throw new Error("flushSomeMessages: numMessages must be a non-negative integer");
+		}
 		if (this.runtimeOptions.flushMode !== FlushMode.TurnBased) {
 			return;
 		}
@@ -352,10 +364,11 @@ export class MockContainerRuntime extends TypedEventEmitter<IContainerRuntimeEve
 			this.idAllocationOutbox.push(idAllocationOp);
 		}
 
+		const actualMessagesToSubmit = this.outbox.splice(0, numMessages);
+
 		// As with the runtime behavior, we need to send the idAllocationOps first
-		const messagesToSubmit = this.idAllocationOutbox.concat(this.outbox);
+		const messagesToSubmit = this.idAllocationOutbox.concat(actualMessagesToSubmit);
 		this.idAllocationOutbox.length = 0;
-		this.outbox.length = 0;
 
 		let fakeClientSequenceNumber = 1;
 		messagesToSubmit.forEach((message) => {

packages/runtime/test-runtime-utils/src/test/types/validateTestRuntimeUtilsPrevious.generated.ts

@@ -40,6 +40,7 @@ declare type current_as_old_for_Class_MockAudience = requireAssignableTo<TypeOnl
  * typeValidation.broken:
  * "Class_MockContainerRuntime": {"forwardCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type old_as_current_for_Class_MockContainerRuntime = requireAssignableTo<TypeOnly<old.MockContainerRuntime>, TypeOnly<current.MockContainerRuntime>>
 
 /*
@@ -94,6 +95,7 @@ declare type current_as_old_for_Class_MockContainerRuntimeFactoryForReconnection
  * typeValidation.broken:
  * "Class_MockContainerRuntimeForReconnection": {"forwardCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type old_as_current_for_Class_MockContainerRuntimeForReconnection = requireAssignableTo<TypeOnly<old.MockContainerRuntimeForReconnection>, TypeOnly<current.MockContainerRuntimeForReconnection>>
 
 /*
@@ -184,6 +186,7 @@ declare type current_as_old_for_Class_MockFluidDataStoreContext = requireAssigna
  * typeValidation.broken:
  * "Class_MockFluidDataStoreRuntime": {"forwardCompat": false}
  */
+// @ts-expect-error compatibility expected to be broken
 declare type old_as_current_for_Class_MockFluidDataStoreRuntime = requireAssignableTo<TypeOnly<old.MockFluidDataStoreRuntime>, TypeOnly<current.MockFluidDataStoreRuntime>>
 
 /*