@rpgjs/testing 4.3.0 → 5.0.0-alpha.26

package/src/index.ts

@@ -1,267 +1,692 @@
-import { HookClient, ModuleType, RpgPlugin } from '@rpgjs/common'
-import { entryPoint, RpgServerEngine, RpgMap, RpgWorld, RpgPlayer } from '@rpgjs/server'
-import { entryPoint as entryPointClient, RpgClientEngine } from '@rpgjs/client'
-import { ObjectFixtureList, Position } from '@rpgjs/types'
-import { MockSocketIo } from 'simple-room'
-
-const { serverIo, ClientIo } = MockSocketIo
-
-type ClientTesting = {
-    client: RpgClientEngine,
-    socket: any,
-    playerId: string
-    player: RpgPlayer
+import { mergeConfig, Provider } from "@signe/di";
+import {
+  provideRpg,
+  startGame,
+  provideClientModules,
+  provideLoadMap,
+  provideClientGlobalConfig,
+  inject,
+  WebSocketToken,
+  AbstractWebsocket,
+  RpgClientEngine,
+  RpgClient,
+  LoadMapToken,
+} from "@rpgjs/client";
+import {
+  createServer,
+  provideServerModules,
+  RpgServer,
+  RpgPlayer,
+} from "@rpgjs/server";
+import { h, Container } from "canvasengine";
+import { clearInject as clearClientInject } from "@rpgjs/client";
+import { clearInject as clearServerInject } from "@rpgjs/server";
+import { combineLatest, filter, take, firstValueFrom, Subject, map, throwError, race, timer, switchMap } from "rxjs";
+
+/**
+ * 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()]
+ * })
+ * ```
+ */
+export function provideTestingLoadMap() {
+  return provideLoadMap((id: string) => {
+    return {
+      id,
+      data: {
+        width: 1024,
+        height: 768,
+        hitboxes: [],
+        params: {},
+      },
+      component: h(Container),
+      width: 1024,
+      height: 768,
+    };
+  });
 }
 
-type PositionMap = string | Position
+/**
+ * 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: any[]): {
+  serverModules: RpgServer[];
+  clientModules: RpgClient[];
+} {
+  if (!modules || modules.length === 0) {
+    return { serverModules: [], clientModules: [] };
+  }
 
-interface Testing {
-    /**
-     * Allows you to create a client and get fixtures to manipulate it during tests
-     * 
-     * Returns:
-     * 
-     * ```ts
-     * {
-     *      client: RpgClientEngine,
-     *      socket: any,
-     *      playerId: string
-     *      player: RpgPlayer
-     * }
-     * ```
-     * 
-     * @title Create Client
-     * @method createClient()
-     * @returns {Promise<ClientTesting>}
-     * @memberof FixtureTesting
-     */
-    createClient(): Promise<ClientTesting>,
+  // Check if first item is a provider (has meta and useValue properties)
+  const isProviderArray = modules.some(
+    (item: any) =>
+      item && typeof item === "object" && "meta" in item && "useValue" in item
+  );
 
-    /**
-     * Create another client, add it to the map and send the information to the first client
-     * 
-     * @title Add Other Client In Map
-     * @method addOtherClientInMap(firstClient,mapId,position?)
-     * @param {RpgClientEngine} firstClient
-     * @param {string} mapId
-     * @param {Position | string} [position]
-     * @returns {Promise<ClientTesting>}
-     * @since 3.2.0
-     * @memberof FixtureTesting
-     */
-    addOtherClientInMap(firstClient: RpgClientEngine, mapId: string, position?: PositionMap): Promise<ClientTesting>
+  const serverModules: RpgServer[] = [];
+  const clientModules: RpgClient[] = [];
 
-    /**
-     * Get server
-     * 
-     * @prop {RpgServerEngine} server
-     * @memberof FixtureTesting
-     */
-    server: RpgServerEngine
+  if (!isProviderArray) {
+    // Direct module objects, extract server and client separately
+    modules.forEach((module: any) => {
+      if (module && typeof module === "object") {
+        if (module.server) {
+          serverModules.push(module.server);
+        }
+        if (module.client) {
+          clientModules.push(module.client);
+        }
+      }
+    });
+    return { serverModules, clientModules };
+  }
 
-    /**
-     * Allows you to change the map. This function on the tests also allows to render with PIXI on the client side
-     * 
-     * @title Change Map
-     * @method changeMap(client,mapId,position?)
-     * @param {RpgClientEngine} client
-     * @param {string} mapId
-     * @param {Position | string} [position]
-     * @returns {Promise<void>}
-     * @memberof FixtureTesting
-     */
-    changeMap(client: RpgClientEngine, mapId: string, position?: PositionMap): Promise<void>
-}
+  // Extract modules from createModule providers
+  // createModule returns providers where useValue contains the original { server, client } object
+  // We need to group providers by their useValue to reconstruct the original modules
+  const seenUseValues = new Set<any>();
 
-let server: RpgServerEngine
-let clients: RpgClientEngine[]
+  modules.forEach((provider: any) => {
+    if (
+      !provider ||
+      typeof provider !== "object" ||
+      !("meta" in provider) ||
+      !("useValue" in provider)
+    ) {
+      return;
+    }
 
-function changeMap(client: RpgClientEngine, server: RpgServerEngine, mapId: string, position?: PositionMap): Promise<void> {
-    return new Promise(async (resolve: any) => {
-        let player = RpgWorld.getPlayer(client.playerId)
+    const { useValue } = provider;
 
-        const beforeLoading = () => {
-            client.PIXI.utils.clearTextureCache()
-        }
+    // Skip if we've already processed this useValue (same module, different provider for server/client)
+    if (seenUseValues.has(useValue)) {
+      return;
+    }
 
-        const afterLoading = () => {
-            client.nextFrame(0) 
-            RpgPlugin.off(HookClient.BeforeSceneLoading, beforeLoading)
-            RpgPlugin.off(HookClient.AfterSceneLoading, afterLoading)
-            resolve()
-        }
+    // Check if useValue has server or client properties (it's a module object)
+    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);
+      }
+    }
+  });
 
-        RpgPlugin.on(HookClient.BeforeSceneLoading, beforeLoading)
-        RpgPlugin.on(HookClient.AfterSceneLoading, afterLoading)
-        
-        await player.changeMap(mapId, position)
-    })
+  return { serverModules, clientModules };
 }
 
+// Global storage for all created fixtures and clients (for clear() function)
+const globalFixtures: Array<{
+  context: any;
+  clientEngine: RpgClientEngine;
+  websocket: AbstractWebsocket;
+  server?: any;
+}> = [];
+
+
 /**
- * Allows you to test modules
- * 
- * @title Testing
- * @method testing(modules,optionsServer?,optionsClient?)
- * @param {ModuleType[]} modules
- * @param {object} [optionsServer]
- * @param {object} [optionsClient]
- * @returns {Promise<FixtureTesting>}
+ * 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
- * import { testing } from '@rpgjs/testing';
- * import { beforeEach } from 'vitest';
- * 
- *  beforeEach(async () => {
- *      const fixture = await testing([
- *          {
- *              server: RpgServerModule
- *          },
- *      ]);
- *      const clientFixture = await fixture.createClient();
- *      currentPlayer = clientFixture.player;
- * });
- * 
- * @memberof Testing
+ * // 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)
+ * ```
  */
-export async function testing(modules: ModuleType[], optionsServer: any = {}, optionsClient: any = {}): Promise<Testing> {
-    RpgPlugin.clear()
-    const engine = await entryPoint(modules, {
-        io: serverIo,
-        standalone: true,
-        disableAuth: true,
-        ...optionsServer
-    })
-    engine.start(null, false)
-    server = engine
-    clients = []
-
-    const createClient = async function createClient() {
-        const client = entryPointClient(modules, {
-            io: new ClientIo(),
-            standalone: true,
-            ...optionsClient
-        })
-        await client.start({
-            renderLoop: false
-        })
-        clients.push(client)
-        client.renderer.transitionMode = 0
-        const playerId = client.playerId
-        return {
-            client,
-            socket: client.socket,
-            playerId,
-            player: RpgWorld.getPlayer(playerId)
-        }
-    }
+export async function testing(
+  modules: ({ server?: RpgServer; client?: RpgClient } | Provider)[] = [],
+  clientConfig: any = {},
+  serverConfig: any = {}
+) {
+  // Normalize modules to extract server/client from providers if needed
+  const { serverModules, clientModules } = normalizeModules(modules as any[]);
 
-    const _changeMap = function (client: RpgClientEngine, mapId: string, position?: PositionMap) {
-        return changeMap(client, server, mapId, position)
-    }
+  // Subject to emit map change events when onJoinMap is triggered
+  const mapChangeSubject = new Subject<{ mapId: string; player: RpgPlayer }>();
 
-    return {
-        createClient,
-        async addOtherClientInMap(firstClient: RpgClientEngine, mapId: string, position?: PositionMap) {
-            const clientFixture = await createClient()
-            const client = clientFixture.client
-            await _changeMap(client, mapId, position)
-            await nextTick(firstClient)
-            return clientFixture
+  const serverClass = createServer({
+    ...serverConfig,
+    providers: [
+      provideServerModules([
+        ...serverModules,
+        {
+          player: {
+            onJoinMap(player: RpgPlayer, map: any) {
+              // Emit map change event to RxJS Subject
+              const mapId = map?.id;
+              if (mapId) {
+                mapChangeSubject.next({ mapId, player });
+              }
+            }
+          }
         },
-        server: engine,
-        changeMap: _changeMap
-    }
+      ]),
+      ...(serverConfig.providers || []),
+    ],
+  });
+
+  // Check if LoadMapToken is already provided in clientConfig.providers
+  // (provideLoadMap returns an array with LoadMapToken)
+  const hasLoadMap =
+    clientConfig.providers?.some((provider: any) => {
+      if (Array.isArray(provider)) {
+        return provider.some((p: any) => p?.provide === LoadMapToken);
+      }
+      return provider?.provide === LoadMapToken;
+    }) || false;
+
+  await startGame(
+    mergeConfig(
+      {
+        ...clientConfig,
+        providers: [
+          provideClientGlobalConfig({}),
+          ...(hasLoadMap ? [] : [provideTestingLoadMap()]), // Add only if not already provided
+          provideClientModules(clientModules),
+          ...(clientConfig.providers || []),
+        ],
+      },
+      {
+        providers: [provideRpg(serverClass, { env: { TEST: "true" } })],
+      }
+    )
+  );
+  const websocket = inject<AbstractWebsocket>(WebSocketToken) as any;
+  const clientEngine = inject<RpgClientEngine>(RpgClientEngine);
+
+  return {
+    async createClient() {
+      return {
+        socket: websocket.getSocket(),
+        client: clientEngine,
+        get playerId() {
+          return Object.keys(websocket.getServer().subRoom.players())[0];
+        },
+        get player(): RpgPlayer {
+          return websocket.getServer().subRoom.players()[this.playerId] as RpgPlayer;
+        },
+        /**
+         * 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: string,
+          timeout = 5000
+        ): Promise<RpgPlayer> {
+          // Check if already on the expected map
+          const currentMap = this.player.getCurrentMap();
+          if (currentMap?.id === expectedMapId) {
+            return this.player;
+          }
+
+          // Create observable that filters map changes for the expected map ID
+          const mapChange$ = mapChangeSubject.pipe(
+            filter((event) => event.mapId === expectedMapId),
+            take(1),
+            map((event) => event.player)
+          );
+
+          // Create timeout observable that throws an error
+          const timeout$ = timer(timeout).pipe(
+            take(1),
+            switchMap(() => {
+              const currentMap = this.player.getCurrentMap();
+              return throwError(() => new Error(
+                `Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. ` +
+                  `Current map: ${currentMap?.id || "null"}`
+              ));
+            })
+          );
+
+          // Race between map change and timeout
+          try {
+            const result = await firstValueFrom(race([mapChange$, timeout$]));
+            return result as RpgPlayer;
+          } catch (error) {
+            if (error instanceof Error) {
+              throw error;
+            }
+            const currentMap = this.player.getCurrentMap();
+            throw new Error(
+              `Timeout: Player did not reach map ${expectedMapId} within ${timeout}ms. ` +
+                `Current map: ${currentMap?.id || "null"}`
+            );
+          }
+        },
+        /**
+         * Manually trigger a game tick for processing inputs and physics
+         *
+         * This method is a convenience wrapper around the exported nextTick() function.
+         *
+         * @param timestamp - Optional timestamp to use for the tick (default: Date.now())
+         * @returns Promise that resolves when the tick is complete
+         *
+         * @example
+         * ```ts
+         * const client = await fixture.createClient()
+         *
+         * // Manually advance the game by one tick
+         * await client.nextTick()
+         * ```
+         */
+        async nextTick(timestamp?: number): Promise<void> {
+          return nextTick(this.client, timestamp);
+        },
+      };
+    },
+    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() {
+      this.server.subRoom.applySyncToClient();
+      await waitForSync(clientEngine);
+    },
+  };
 }
 
 /**
- * Clear caches. Use it after the end of each test
- * 
+ * 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'
- * import { afterEach } from 'vitest'
- * 
+ *
  * afterEach(() => {
- *      clear()
+ *   clear()
  * })
  * ```
- * 
- * @title Clear
- * @method clear()
- * @returns {void}
- * @memberof Testing
  */
-export function clear(): void {
-    server?.world.clear()
-    clients?.forEach(client => client.reset())
-    RpgMap.buffer.clear()
-    RpgPlugin.clear()
-    serverIo.clear()
-    serverIo.events.clear()
-    window.document.body.innerHTML = `<div id="rpg"></div>`
+export async function clear(): Promise<void> {
+
+  // Wait for the next tick to ensure all promises are resolved
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  // Clean up all created client and server instances from all fixtures
+  for (const client of globalFixtures) {
+    try {
+      // Clear client engine
+      if (
+        client.clientEngine &&
+        typeof (client.clientEngine as any).clear === "function"
+      ) {
+        (client.clientEngine as any).clear();
+      }
+
+      // Clear server map (subRoom)
+      const serverMap = client.server?.subRoom as any;
+      if (serverMap && typeof serverMap.clear === "function") {
+        serverMap.clear();
+      }
+    } catch (error) {
+      // Silently ignore cleanup errors
+      console.warn("Error during cleanup:", error);
+    }
+  }
+
+  // Clear the global fixtures array
+  globalFixtures.length = 0;
+
+  // Clear client context injection
+  try {
+    clearClientInject();
+  } catch (error) {
+    console.warn("Error clearing client inject:", error);
+  }
+
+  // Clear server context injection
+  try {
+    clearServerInject();
+  } catch (error) {
+    console.warn("Error clearing server inject:", error);
+  }
+
+  // Reset DOM
+  if (typeof window !== "undefined" && window.document) {
+    window.document.body.innerHTML = `<div id="rpg"></div>`;
+  }
 }
 
 /**
- * Allows you to make a tick:
- * 1. on server
- * 2. server sends data to client
+ * 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
- * 
- * @title Next Tick
- * @method nextTick(client,timestamp?)
- * @param {RpgClientEngine} client
- * @param {number} [timestamp=0] A predefined timestamp
- * @returns {Promise<ObjectFixtureList>}
- * @memberof Testing
+ * 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())
+ * ```
+ */
+export async function nextTick(
+  client: RpgClientEngine,
+  timestamp?: number
+): Promise<void> {
+  if (!client) {
+    throw new Error("nextTick: client parameter is required");
+  }
+
+  const tickTimestamp = timestamp ?? Date.now();
+  const delta = 16; // 16ms for 60fps
+
+  // Get server instance from client context
+  const websocket = (client as any).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");
+  }
+
+  // Get server map (subRoom)
+  const serverMap = server.subRoom as any;
+  if (!serverMap) {
+    return;
+  }
+
+  // 1. On server: Process inputs for all players
+  for (const player of serverMap.getPlayers()) {
+    if (player.pendingInputs && player.pendingInputs.length > 0) {
+      await serverMap.processInput(player.id);
+    }
+  }
+
+  // 2. Run physics tick on server map
+  if (typeof serverMap.runFixedTicks === "function") {
+    serverMap.runFixedTicks(delta);
+  }
+
+  // 3. Server sends data to client - trigger sync for all players
+  // The sync is triggered by calling syncChanges() on each player
+  for (const player of serverMap.getPlayers()) {
+    if (player && typeof (player as any).syncChanges === "function") {
+      (player as any).syncChanges();
+    }
+  }
+
+  // 4. Client retrieves data and performs reconciliation
+  // The sync data will be received by the client through the websocket
+  // We need to wait a bit for the sync data to be processed
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  // 5. Run physics tick on client map (performs client-side prediction)
+  const sceneMap = (client as any).sceneMap;
+  if (sceneMap && typeof sceneMap.stepPredictionTick === "function") {
+    sceneMap.stepPredictionTick();
+  }
+
+  // 6. Trigger VueJS tick if Vue is used (handled by CanvasEngine internally)
+  // CanvasEngine handles this automatically through its tick system
+}
+
+/**
+ * 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()
+ * ```
  */
-export async function nextTick(client: RpgClientEngine, timestamp = 0): Promise<ObjectFixtureList> {
-    server.nextTick(timestamp)
-    await server.send()
-    return new Promise((resolve: any) => {
-        client.objects.subscribe(async (objects) => {
-            await client.processInput()
-            client.nextFrame(timestamp)
-            await client.vueInstance.$nextTick()
-            resolve(objects)
-        })
-    })
+export async function waitForSync(
+  client: RpgClientEngine,
+  timeout: number = 1000
+): Promise<void> {
+  if (!client) {
+    throw new Error("waitForSync: client parameter is required");
+  }
+
+  // Access private observables via type assertion
+  const playersReceived$ = (client as any).playersReceived$ as any;
+  const eventsReceived$ = (client as any).eventsReceived$ as any;
+
+  if (!playersReceived$ || !eventsReceived$) {
+    throw new Error(
+      "waitForSync: playersReceived$ or eventsReceived$ not found in client"
+    );
+  }
+
+  // Check if observables are already true - if so, sync has already arrived, don't reset
+  const playersAlreadyTrue = playersReceived$.getValue
+    ? playersReceived$.getValue() === true
+    : false;
+  const eventsAlreadyTrue = eventsReceived$.getValue
+    ? eventsReceived$.getValue() === true
+    : false;
+
+  // If both observables are already true, sync has already completed - return immediately
+  if (playersAlreadyTrue && eventsAlreadyTrue) {
+    return;
+  }
+
+  // Reset observables to false to ensure we catch the next sync
+  // Note: This is only needed when waitForSync is called standalone.
+  // When called from waitForSyncComplete, observables are already reset before nextTick
+  playersReceived$.next(false);
+  eventsReceived$.next(false);
+
+  // Wait for both observables to be true
+  const syncComplete$ = combineLatest([
+    playersReceived$.pipe(filter((received) => received === true)),
+    eventsReceived$.pipe(filter((received) => received === true)),
+  ]).pipe(take(1));
+
+  // Create a timeout promise
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    setTimeout(() => {
+      reject(
+        new Error(
+          `waitForSync: Timeout after ${timeout}ms. Synchronization did not complete.`
+        )
+      );
+    }, timeout);
+  });
+
+  // Race between sync completion and timeout
+  await Promise.race([firstValueFrom(syncComplete$), timeoutPromise]);
 }
 
 /**
- * @title Wait a moment
- * @method waitUntil(promise)
- * @param {Promise<any>} promise
- * @returns {Promise<any>}
- * @since 4.0.0
- * @memberof Testing
+ * 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
- * await waitUntil(
- *  player.moveRoutes([Move.right()])
- * )
+ * 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()
  * ```
  */
-export function waitUntil(promise: Promise<any>): Promise<any> {
-    let tick = 0
-    let finish = false
-    return new Promise((resolve: any, reject: any) => {
-        promise.then(() => {
-            finish = true
-            resolve()
-        }).catch(reject)
-        const timeout = () => {
-            setTimeout(() => {
-                if (!finish) {
-                    tick++
-                    server.nextTick(tick)
-                    timeout()
-                }
-            }, 50)
-        }
-        timeout()
-    })
-}
+export async function waitForSyncComplete(
+  player: RpgPlayer | null,
+  client: RpgClientEngine,
+  timeout: number = 1000
+): Promise<void> {
+  if (!client) {
+    throw new Error("waitForSyncComplete: client parameter is required");
+  }
+
+  // Reset observables BEFORE calling nextTick to ensure we catch the sync that will be sent
+  // This prevents race condition where sync arrives before we start waiting
+  const playersReceived$ = (client as any).playersReceived$ as any;
+  const eventsReceived$ = (client as any).eventsReceived$ as any;
+  if (playersReceived$ && eventsReceived$) {
+    playersReceived$.next(false);
+    eventsReceived$.next(false);
+  }
+
+  // Trigger sync by calling nextTick (which calls syncChanges on all players)
+  await nextTick(client);
+
+  // Wait for client to receive and process the sync
+  await waitForSync(client, timeout);
+}