@rpgjs/testing 5.0.0-beta.1 → 5.0.0-beta.3

package/dist/index.js

@@ -1,378 +1,466 @@
-import { mergeConfig } from './node_modules/.pnpm/@signe_di@2.8.3/node_modules/@signe/di/dist/index.js';
-import { provideLoadMap, LoadMapToken, startGame, provideRpg, provideClientGlobalConfig, provideClientModules, inject, WebSocketToken, RpgClientEngine, clearInject } from '@rpgjs/client';
-import { createServer, provideServerModules, clearInject as clearInject$1 } from '@rpgjs/server';
-import { h, Container } from 'canvasengine';
-import { Subject, combineLatest, filter, take, firstValueFrom, map, timer, switchMap, throwError, race } from 'rxjs';
-
+import { mergeConfig } from "./node_modules/.pnpm/@signe_di@2.9.0/node_modules/@signe/di/dist/index.js";
+import { LoadMapToken, RpgClientEngine, WebSocketToken, clearInject, inject, provideClientGlobalConfig, provideClientModules, provideLoadMap, provideRpg, startGame } from "@rpgjs/client";
+import { clearInject as clearInject$1, createServer, provideServerModules } from "@rpgjs/server";
+import { Container, h } from "canvasengine";
+import { Subject, combineLatest, filter, firstValueFrom, map, race, switchMap, take, throwError, timer } from "rxjs";
+//#region src/index.ts
+/**
+* Provides a default map loader for testing environments
+*
+* This function returns a `provideLoadMap` provider that creates mock maps
+* with default dimensions (1024x768) and a minimal component. It's automatically
+* used by `testing()` if no custom `provideLoadMap` is provided in `clientConfig.providers`.
+*
+* @returns A provider function that can be used with `provideLoadMap`
+* @example
+* ```ts
+* // Used automatically by testing()
+* const fixture = await testing([myModule])
+*
+* // Or use directly in clientConfig
+* const fixture = await testing([myModule], {
+*   providers: [provideTestingLoadMap()]
+* })
+* ```
+*/
 function provideTestingLoadMap() {
-  return provideLoadMap((id) => {
-    return {
-      id,
-      data: {
-        width: 1024,
-        height: 768,
-        hitboxes: [],
-        params: {}
-      },
-      component: h(Container),
-      width: 1024,
-      height: 768
-    };
-  });
+	return provideLoadMap((id) => {
+		return {
+			id,
+			data: {
+				width: 1024,
+				height: 768,
+				hitboxes: [],
+				params: {}
+			},
+			component: h(Container),
+			width: 1024,
+			height: 768
+		};
+	});
 }
+/**
+* Normalizes modules input to extract server/client modules from createModule providers or direct module objects
+*
+* @param modules - Array of modules that can be either:
+*   - Direct module objects: { server: RpgServer, client: RpgClient }
+*   - Providers returned by createModule(): Provider[] with meta.server/client and useValue
+* @returns Object with separate arrays for server and client modules
+* @example
+* ```ts
+* // Direct modules
+* normalizeModules([{ server: serverModule, client: clientModule }])
+*
+* // createModule providers
+* const providers = createModule('MyModule', [{ server: serverModule, client: clientModule }])
+* normalizeModules(providers)
+* ```
+*/
 function normalizeModules(modules) {
-  if (!modules || modules.length === 0) {
-    return { serverModules: [], clientModules: [] };
-  }
-  const isProviderArray = modules.some(
-    (item) => item && typeof item === "object" && "meta" in item && "useValue" in item
-  );
-  const serverModules = [];
-  const clientModules = [];
-  if (!isProviderArray) {
-    modules.forEach((module) => {
-      if (module && typeof module === "object") {
-        if (module.server) {
-          serverModules.push(module.server);
-        }
-        if (module.client) {
-          clientModules.push(module.client);
-        }
-      }
-    });
-    return { serverModules, clientModules };
-  }
-  const seenUseValues = /* @__PURE__ */ new Set();
-  modules.forEach((provider) => {
-    if (!provider || typeof provider !== "object" || !("meta" in provider) || !("useValue" in provider)) {
-      return;
-    }
-    const { useValue } = provider;
-    if (seenUseValues.has(useValue)) {
-      return;
-    }
-    if (useValue && typeof useValue === "object" && ("server" in useValue || "client" in useValue)) {
-      seenUseValues.add(useValue);
-      if (useValue.server) {
-        serverModules.push(useValue.server);
-      }
-      if (useValue.client) {
-        clientModules.push(useValue.client);
-      }
-    }
-  });
-  return { serverModules, clientModules };
+	if (!modules || modules.length === 0) return {
+		serverModules: [],
+		clientModules: []
+	};
+	const isProviderArray = modules.some((item) => item && typeof item === "object" && "meta" in item && "useValue" in item);
+	const serverModules = [];
+	const clientModules = [];
+	if (!isProviderArray) {
+		modules.forEach((module) => {
+			if (module && typeof module === "object") {
+				if (module.server) serverModules.push(module.server);
+				if (module.client) clientModules.push(module.client);
+			}
+		});
+		return {
+			serverModules,
+			clientModules
+		};
+	}
+	const seenUseValues = /* @__PURE__ */ new Set();
+	modules.forEach((provider) => {
+		if (!provider || typeof provider !== "object" || !("meta" in provider) || !("useValue" in provider)) return;
+		const { useValue } = provider;
+		if (seenUseValues.has(useValue)) return;
+		if (useValue && typeof useValue === "object" && ("server" in useValue || "client" in useValue)) {
+			seenUseValues.add(useValue);
+			if (useValue.server) serverModules.push(useValue.server);
+			if (useValue.client) clientModules.push(useValue.client);
+		}
+	});
+	return {
+		serverModules,
+		clientModules
+	};
 }
-const globalFixtures = [];
+var globalFixtures = [];
+/**
+* Testing utility function to set up server and client instances for unit testing
+*
+* This function creates a test environment with both server and client instances,
+* allowing you to test player interactions, server hooks, and game mechanics.
+*
+* @param modules - Array of modules that can be either:
+*   - Direct module objects: { server: RpgServer, client: RpgClient }
+*   - Providers returned by createModule(): Provider[] with meta.server/client and useValue
+* @param clientConfig - Optional client configuration
+* @param serverConfig - Optional server configuration
+* @returns Testing fixture with createClient method
+* @example
+* ```ts
+* // Using direct modules
+* const fixture = await testing([{
+*   server: serverModule,
+*   client: clientModule
+* }])
+*
+* // Using createModule
+* const myModule = createModule('MyModule', [{
+*   server: serverModule,
+*   client: clientModule
+* }])
+* const fixture = await testing(myModule)
+* ```
+*/
 async function testing(modules = [], clientConfig = {}, serverConfig = {}) {
-  const { serverModules, clientModules } = normalizeModules(modules);
-  const mapChangeSubject = new Subject();
-  const serverClass = createServer({
-    ...serverConfig,
-    providers: [
-      provideServerModules([
-        ...serverModules,
-        {
-          player: {
-            onJoinMap(player, map2) {
-              const mapId = map2?.id;
-              if (mapId) {
-                mapChangeSubject.next({ mapId, player });
-              }
-            }
-          }
-        }
-      ]),
-      ...serverConfig.providers || []
-    ]
-  });
-  const hasLoadMap = clientConfig.providers?.some((provider) => {
-    if (Array.isArray(provider)) {
-      return provider.some((p) => p?.provide === LoadMapToken);
-    }
-    return provider?.provide === LoadMapToken;
-  }) || false;
-  await startGame(
-    mergeConfig(
-      {
-        ...clientConfig,
-        providers: [
-          provideClientGlobalConfig({
-            // TODO
-            // bootstrapCanvasOptions: {
-            //   components: mockComponents,
-            //   autoRegister: false,
-            // },
-          }),
-          ...hasLoadMap ? [] : [provideTestingLoadMap()],
-          // Add only if not already provided
-          provideClientModules(clientModules),
-          ...clientConfig.providers || []
-        ]
-      },
-      {
-        providers: [provideRpg(serverClass, { env: { TEST: "true" } })]
-      }
-    )
-  );
-  const websocket = inject(WebSocketToken);
-  const clientEngine = inject(RpgClientEngine);
-  return {
-    async createClient() {
-      const clientObj = {
-        socket: websocket.getSocket(),
-        client: clientEngine,
-        get playerId() {
-          return Object.keys(websocket.getServer().subRoom.players())[0];
-        },
-        get player() {
-          return websocket.getServer().subRoom.players()[clientObj.playerId];
-        },
-        /**
-         * Wait for player to be on a specific map
-         *
-         * This utility function waits for the `onJoinMap` hook to be triggered
-         * when the player joins the expected map, or throws an error if the timeout is exceeded.
-         *
-         * ## Design
-         *
-         * Uses RxJS to listen for map change events emitted by `onJoinMap`. The function:
-         * 1. Checks if the player is already on the expected map
-         * 2. Subscribes to the `mapChangeSubject` observable
-         * 3. Filters events to match the expected map ID
-         * 4. Uses `race` operator with a timer to implement timeout handling
-         * 5. Resolves with the player when the map change event is received
-         *
-         * @param expectedMapId - The expected map ID (without 'map-' prefix, e.g. 'map1')
-         * @param timeout - Maximum time to wait in milliseconds (default: 5000)
-         * @returns Promise that resolves when player is on the expected map
-         * @throws Error if timeout is exceeded
-         * @example
-         * ```ts
-         * const client = await fixture.createClient()
-         * await client.waitForMapChange('map1')
-         * ```
-         */
-        async waitForMapChange(expectedMapId, timeout = 5e3) {
-          const currentMap = clientObj.player.getCurrentMap();
-          if (currentMap?.id === expectedMapId) {
-            return clientObj.player;
-          }
-          const mapChange$ = mapChangeSubject.pipe(
-            filter((event) => event.mapId === expectedMapId),
-            take(1),
-            map((event) => event.player)
-          );
-          const timeout$ = timer(timeout).pipe(
-            take(1),
-            switchMap(() => {
-              const currentMap2 = clientObj.player.getCurrentMap();
-              return throwError(() => new Error(
-                `Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. Current map: ${currentMap2?.id || "null"}`
-              ));
-            })
-          );
-          try {
-            const result = await firstValueFrom(race([mapChange$, timeout$]));
-            return result;
-          } catch (error) {
-            if (error instanceof Error) {
-              throw error;
-            }
-            const currentMap2 = clientObj.player.getCurrentMap();
-            throw new Error(
-              `Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. Current map: ${currentMap2?.id || "null"}`
-            );
-          }
-        }
-      };
-      return clientObj;
-    },
-    get server() {
-      return websocket.getServer();
-    },
-    /**
-     * Clear all server, client instances and reset the DOM
-     *
-     * This method should be called in afterEach to clean up test state.
-     * It destroys all created client instances, clears the server, and resets the DOM.
-     *
-     * @example
-     * ```ts
-     * const fixture = await testing([myModule])
-     *
-     * afterEach(() => {
-     *   fixture.clear()
-     * })
-     * ```
-     */
-    clear() {
-      return clear();
-    },
-    async applySyncToClient() {
-      websocket.getServer().subRoom.applySyncToClient();
-      await waitForSync(clientEngine);
-    },
-    /**
-     * Manually trigger a game tick for processing inputs and physics
-     *
-     * This method is a convenience wrapper around the exported nextTick() function.
-     * It uses the clientEngine from the fixture, so no client parameter is needed.
-     *
-     * @param timestamp - Optional timestamp to use for the tick (default: Date.now())
-     * @returns Promise that resolves when the tick is complete
-     *
-     * @example
-     * ```ts
-     * const fixture = await testing([myModule])
-     *
-     * // Manually advance the game by one tick
-     * await fixture.nextTick()
-     * ```
-     */
-    async nextTick(timestamp) {
-      return nextTick(clientEngine);
-    },
-    async nextTickTimes(times, timestamp) {
-      for (let i = 0; i < times; i++) {
-        await nextTick(clientEngine);
-      }
-    },
-    async wait(ms) {
-      return new Promise((resolve) => setTimeout(resolve, ms));
-    },
-    async waitUntil(promise) {
-      let settled = false;
-      let resolvedValue;
-      let rejectedError;
-      promise.then((value) => {
-        settled = true;
-        resolvedValue = value;
-      }).catch((error) => {
-        settled = true;
-        rejectedError = error;
-      });
-      while (!settled) {
-        await nextTick(clientEngine);
-        await new Promise((resolve) => setTimeout(resolve, 0));
-      }
-      if (typeof rejectedError !== "undefined") {
-        throw rejectedError;
-      }
-      return resolvedValue;
-    }
-  };
+	const { serverModules, clientModules } = normalizeModules(modules);
+	const mapChangeSubject = new Subject();
+	const serverClass = createServer({
+		...serverConfig,
+		providers: [provideServerModules([...serverModules, { player: { onJoinMap(player, map) {
+			const mapId = map?.id;
+			if (mapId) mapChangeSubject.next({
+				mapId,
+				player
+			});
+		} } }]), ...serverConfig.providers || []]
+	});
+	const hasLoadMap = clientConfig.providers?.some((provider) => {
+		if (Array.isArray(provider)) return provider.some((p) => p?.provide === LoadMapToken);
+		return provider?.provide === LoadMapToken;
+	}) || false;
+	await startGame(mergeConfig({
+		...clientConfig,
+		providers: [
+			provideClientGlobalConfig({}),
+			...hasLoadMap ? [] : [provideTestingLoadMap()],
+			provideClientModules(clientModules),
+			...clientConfig.providers || []
+		]
+	}, { providers: [provideRpg(serverClass, { env: { TEST: "true" } })] }));
+	const websocket = inject(WebSocketToken);
+	const clientEngine = inject(RpgClientEngine);
+	return {
+		async createClient() {
+			const clientObj = {
+				socket: websocket.getSocket(),
+				client: clientEngine,
+				get playerId() {
+					return Object.keys(websocket.getServer().subRoom.players())[0];
+				},
+				get player() {
+					return websocket.getServer().subRoom.players()[clientObj.playerId];
+				},
+				/**
+				* Wait for player to be on a specific map
+				*
+				* This utility function waits for the `onJoinMap` hook to be triggered
+				* when the player joins the expected map, or throws an error if the timeout is exceeded.
+				*
+				* ## Design
+				*
+				* Uses RxJS to listen for map change events emitted by `onJoinMap`. The function:
+				* 1. Checks if the player is already on the expected map
+				* 2. Subscribes to the `mapChangeSubject` observable
+				* 3. Filters events to match the expected map ID
+				* 4. Uses `race` operator with a timer to implement timeout handling
+				* 5. Resolves with the player when the map change event is received
+				*
+				* @param expectedMapId - The expected map ID (without 'map-' prefix, e.g. 'map1')
+				* @param timeout - Maximum time to wait in milliseconds (default: 5000)
+				* @returns Promise that resolves when player is on the expected map
+				* @throws Error if timeout is exceeded
+				* @example
+				* ```ts
+				* const client = await fixture.createClient()
+				* await client.waitForMapChange('map1')
+				* ```
+				*/
+				async waitForMapChange(expectedMapId, timeout = 5e3) {
+					if (clientObj.player.getCurrentMap()?.id === expectedMapId) return clientObj.player;
+					const mapChange$ = mapChangeSubject.pipe(filter((event) => event.mapId === expectedMapId), take(1), map((event) => event.player));
+					const timeout$ = timer(timeout).pipe(take(1), switchMap(() => {
+						const currentMap = clientObj.player.getCurrentMap();
+						return throwError(() => /* @__PURE__ */ new Error(`Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. Current map: ${currentMap?.id || "null"}`));
+					}));
+					try {
+						return await firstValueFrom(race([mapChange$, timeout$]));
+					} catch (error) {
+						if (error instanceof Error) throw error;
+						const currentMap = clientObj.player.getCurrentMap();
+						throw new Error(`Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. Current map: ${currentMap?.id || "null"}`);
+					}
+				}
+			};
+			return clientObj;
+		},
+		get server() {
+			return websocket.getServer();
+		},
+		/**
+		* Clear all server, client instances and reset the DOM
+		*
+		* This method should be called in afterEach to clean up test state.
+		* It destroys all created client instances, clears the server, and resets the DOM.
+		*
+		* @example
+		* ```ts
+		* const fixture = await testing([myModule])
+		*
+		* afterEach(() => {
+		*   fixture.clear()
+		* })
+		* ```
+		*/
+		clear() {
+			return clear();
+		},
+		async applySyncToClient() {
+			websocket.getServer().subRoom.applySyncToClient();
+			await waitForSync(clientEngine);
+		},
+		/**
+		* Manually trigger a game tick for processing inputs and physics
+		*
+		* This method is a convenience wrapper around the exported nextTick() function.
+		* It uses the clientEngine from the fixture, so no client parameter is needed.
+		*
+		* @param timestamp - Optional timestamp to use for the tick (default: Date.now())
+		* @returns Promise that resolves when the tick is complete
+		*
+		* @example
+		* ```ts
+		* const fixture = await testing([myModule])
+		*
+		* // Manually advance the game by one tick
+		* await fixture.nextTick()
+		* ```
+		*/
+		async nextTick(timestamp) {
+			return nextTick(clientEngine, timestamp);
+		},
+		async nextTickTimes(times, timestamp) {
+			for (let i = 0; i < times; i++) await nextTick(clientEngine, timestamp);
+		},
+		async wait(ms) {
+			return new Promise((resolve) => setTimeout(resolve, ms));
+		},
+		async waitUntil(promise) {
+			let settled = false;
+			let resolvedValue;
+			let rejectedError;
+			promise.then((value) => {
+				settled = true;
+				resolvedValue = value;
+			}).catch((error) => {
+				settled = true;
+				rejectedError = error;
+			});
+			while (!settled) {
+				await nextTick(clientEngine, Date.now());
+				await new Promise((resolve) => setTimeout(resolve, 0));
+			}
+			if (typeof rejectedError !== "undefined") throw rejectedError;
+			return resolvedValue;
+		}
+	};
 }
+/**
+* Clear all caches and reset test state
+*
+* This function should be called after the end of each test to clean up
+* all server and client instances, clear caches, and reset the DOM.
+*
+* ## Design
+*
+* Cleans up all created fixtures, client engines, server instances, and resets
+* the DOM to a clean state. This ensures no state leaks between tests.
+*
+* @returns void
+*
+* @example
+* ```ts
+* import { clear } from '@rpgjs/testing'
+*
+* afterEach(() => {
+*   clear()
+* })
+* ```
+*/
 async function clear() {
-  await new Promise((resolve) => setTimeout(resolve, 0));
-  for (const client of globalFixtures) {
-    try {
-      if (client.clientEngine && typeof client.clientEngine.clear === "function") {
-        client.clientEngine.clear();
-      }
-      const serverMap = client.server?.subRoom;
-      if (serverMap && typeof serverMap.clear === "function") {
-        serverMap.clear();
-      }
-    } catch (error) {
-      console.warn("Error during cleanup:", error);
-    }
-  }
-  globalFixtures.length = 0;
-  try {
-    clearInject();
-  } catch (error) {
-    console.warn("Error clearing client inject:", error);
-  }
-  try {
-    clearInject$1();
-  } catch (error) {
-    console.warn("Error clearing server inject:", error);
-  }
-  if (typeof window !== "undefined" && window.document) {
-    window.document.body.innerHTML = `<div id="rpg"></div>`;
-  }
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	for (const client of globalFixtures) try {
+		if (client.clientEngine && typeof client.clientEngine.clear === "function") client.clientEngine.clear();
+		const serverMap = client.server?.subRoom;
+		if (serverMap && typeof serverMap.clear === "function") serverMap.clear();
+	} catch (error) {
+		console.warn("Error during cleanup:", error);
+	}
+	globalFixtures.length = 0;
+	try {
+		clearInject();
+	} catch (error) {
+		console.warn("Error clearing client inject:", error);
+	}
+	try {
+		clearInject$1();
+	} catch (error) {
+		console.warn("Error clearing server inject:", error);
+	}
+	if (typeof window !== "undefined" && window.document) window.document.body.innerHTML = `<div id="rpg"></div>`;
 }
+/**
+* Manually trigger a game tick for processing inputs and physics
+*
+* This function allows you to manually advance the game by one tick.
+* It performs the following operations:
+* 1. On server: processes pending inputs and advances physics
+* 2. Server sends data to client
+* 3. Client retrieves data and performs inputs (move, etc.) and server reconciliation
+* 4. A tick is performed on the client
+* 5. A tick is performed on VueJS (if Vue is used)
+*
+* @param client - The RpgClientEngine instance
+* @param timestamp - Optional timestamp to use for the tick (default: Date.now())
+* @returns Promise that resolves when the tick is complete
+*
+* @example
+* ```ts
+* import { nextTick } from '@rpgjs/testing'
+*
+* const client = await fixture.createClient()
+*
+* // Manually advance the game by one tick
+* await nextTick(client.client, Date.now())
+* ```
+*/
 async function nextTick(client, timestamp) {
-  if (!client) {
-    throw new Error("nextTick: client parameter is required");
-  }
-  const delta = 16;
-  const websocket = client.webSocket;
-  if (!websocket) {
-    throw new Error("nextTick: websocket not found in client");
-  }
-  const server = websocket.getServer();
-  if (!server) {
-    throw new Error("nextTick: server not found");
-  }
-  const serverMap = server.subRoom;
-  if (!serverMap) {
-    return;
-  }
-  for (const player of serverMap.getPlayers()) {
-    if (player.pendingInputs && player.pendingInputs.length > 0) {
-      await serverMap.processInput(player.id);
-    }
-  }
-  serverMap.nextTick(delta);
-  for (const player of serverMap.getPlayers()) {
-    if (player && typeof player.syncChanges === "function") {
-      player.syncChanges();
-    }
-  }
-  await new Promise((resolve) => setTimeout(resolve, 0));
-  const sceneMap = client.sceneMap;
-  if (sceneMap && typeof sceneMap.stepPredictionTick === "function") {
-    sceneMap.stepPredictionTick();
-  }
+	if (!client) throw new Error("nextTick: client parameter is required");
+	const delta = 16;
+	const websocket = client.webSocket;
+	if (!websocket) throw new Error("nextTick: websocket not found in client");
+	const server = websocket.getServer();
+	if (!server) throw new Error("nextTick: server not found");
+	const serverMap = server.subRoom;
+	if (!serverMap) return;
+	for (const player of serverMap.getPlayers()) if (player.pendingInputs && player.pendingInputs.length > 0) await serverMap.processInput(player.id);
+	serverMap.nextTick(delta);
+	for (const player of serverMap.getPlayers()) if (player && typeof player.syncChanges === "function") player.syncChanges();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	const sceneMap = client.sceneMap;
+	if (sceneMap && typeof sceneMap.stepPredictionTick === "function") sceneMap.stepPredictionTick();
 }
+/**
+* Wait for synchronization to complete on the client
+*
+* This function waits for the client to receive and process synchronization data
+* from the server. It monitors the `playersReceived$` and `eventsReceived$` observables
+* in the RpgClientEngine to determine when synchronization is complete.
+*
+* ## Design
+*
+* - Uses `combineLatest` to wait for both `playersReceived$` and `eventsReceived$` to be `true`
+* - Filters to only proceed when both are `true`
+* - Includes a timeout to prevent waiting indefinitely
+* - Resets the observables to `false` before waiting to ensure we catch the next sync
+*
+* @param client - The RpgClientEngine instance
+* @param timeout - Maximum time to wait in milliseconds (default: 1000ms)
+* @returns Promise that resolves when synchronization is complete
+* @throws Error if timeout is exceeded
+*
+* @example
+* ```ts
+* import { waitForSync } from '@rpgjs/testing'
+*
+* const client = await fixture.createClient()
+*
+* // Wait for sync to complete
+* await waitForSync(client.client)
+*
+* // Now you can safely test client-side state
+* expect(client.client.sceneMap.players()).toBeDefined()
+* ```
+*/
 async function waitForSync(client, timeout = 1e3) {
-  if (!client) {
-    throw new Error("waitForSync: client parameter is required");
-  }
-  const playersReceived$ = client.playersReceived$;
-  const eventsReceived$ = client.eventsReceived$;
-  if (!playersReceived$ || !eventsReceived$) {
-    throw new Error(
-      "waitForSync: playersReceived$ or eventsReceived$ not found in client"
-    );
-  }
-  const playersAlreadyTrue = playersReceived$.getValue ? playersReceived$.getValue() === true : false;
-  const eventsAlreadyTrue = eventsReceived$.getValue ? eventsReceived$.getValue() === true : false;
-  if (playersAlreadyTrue && eventsAlreadyTrue) {
-    return;
-  }
-  playersReceived$.next(false);
-  eventsReceived$.next(false);
-  const syncComplete$ = combineLatest([
-    playersReceived$.pipe(filter((received) => received === true)),
-    eventsReceived$.pipe(filter((received) => received === true))
-  ]).pipe(take(1));
-  const timeoutPromise = new Promise((_, reject) => {
-    setTimeout(() => {
-      reject(
-        new Error(
-          `waitForSync: Timeout after ${timeout}ms. Synchronization did not complete.`
-        )
-      );
-    }, timeout);
-  });
-  await Promise.race([firstValueFrom(syncComplete$), timeoutPromise]);
+	if (!client) throw new Error("waitForSync: client parameter is required");
+	const playersReceived$ = client.playersReceived$;
+	const eventsReceived$ = client.eventsReceived$;
+	if (!playersReceived$ || !eventsReceived$) throw new Error("waitForSync: playersReceived$ or eventsReceived$ not found in client");
+	const playersAlreadyTrue = playersReceived$.getValue ? playersReceived$.getValue() === true : false;
+	const eventsAlreadyTrue = eventsReceived$.getValue ? eventsReceived$.getValue() === true : false;
+	if (playersAlreadyTrue && eventsAlreadyTrue) return;
+	playersReceived$.next(false);
+	eventsReceived$.next(false);
+	const syncComplete$ = combineLatest([playersReceived$.pipe(filter((received) => received === true)), eventsReceived$.pipe(filter((received) => received === true))]).pipe(take(1));
+	const timeoutPromise = new Promise((_, reject) => {
+		setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`waitForSync: Timeout after ${timeout}ms. Synchronization did not complete.`));
+		}, timeout);
+	});
+	await Promise.race([firstValueFrom(syncComplete$), timeoutPromise]);
 }
+/**
+* Wait for complete synchronization cycle (server sync + client receive)
+*
+* This function performs a complete synchronization cycle:
+* 1. Triggers a game tick using `nextTick()` which calls `syncChanges()` on all players
+* 2. Waits for the client to receive and process the synchronization data
+*
+* This is useful when you need to ensure that server-side changes are fully
+* synchronized to the client before testing client-side state.
+*
+* ## Design
+*
+* - Calls `nextTick()` to trigger server-side sync
+* - Waits for client to receive sync data using `waitForSync()`
+* - Ensures complete synchronization cycle is finished
+*
+* @param player - The RpgPlayer instance (optional, will sync all players if not provided)
+* @param client - The RpgClientEngine instance
+* @param timeout - Maximum time to wait in milliseconds (default: 1000ms)
+* @returns Promise that resolves when synchronization is complete
+* @throws Error if timeout is exceeded
+*
+* @example
+* ```ts
+* import { waitForSyncComplete } from '@rpgjs/testing'
+*
+* const client = await fixture.createClient()
+* const player = client.player
+*
+* // Make a server-side change
+* player.addItem('potion', 5)
+*
+* // Wait for sync to complete
+* await waitForSyncComplete(player, client.client)
+*
+* // Now you can safely test client-side state
+* const clientPlayer = client.client.sceneMap.players()[player.id]
+* expect(clientPlayer.items()).toBeDefined()
+* ```
+*/
 async function waitForSyncComplete(player, client, timeout = 1e3) {
-  if (!client) {
-    throw new Error("waitForSyncComplete: client parameter is required");
-  }
-  const playersReceived$ = client.playersReceived$;
-  const eventsReceived$ = client.eventsReceived$;
-  if (playersReceived$ && eventsReceived$) {
-    playersReceived$.next(false);
-    eventsReceived$.next(false);
-  }
-  await nextTick(client);
-  await waitForSync(client, timeout);
+	if (!client) throw new Error("waitForSyncComplete: client parameter is required");
+	const playersReceived$ = client.playersReceived$;
+	const eventsReceived$ = client.eventsReceived$;
+	if (playersReceived$ && eventsReceived$) {
+		playersReceived$.next(false);
+		eventsReceived$.next(false);
+	}
+	await nextTick(client);
+	await waitForSync(client, timeout);
 }
-
+//#endregion
 export { clear, nextTick, provideTestingLoadMap, testing, waitForSync, waitForSyncComplete };
-//# sourceMappingURL=index.js.map
+
+//# sourceMappingURL=index.js.map