@rpgjs/testing 4.2.2 → 5.0.0-alpha.25

package/src/index.ts

@@ -1,267 +1,617 @@
-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, race, timer, firstValueFrom } from "rxjs";
 
-type PositionMap = string | Position
-
-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>,
-
-    /**
-     * 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>
-
-    /**
-     * Get server
-     * 
-     * @prop {RpgServerEngine} server
-     * @memberof FixtureTesting
-     */
-    server: RpgServerEngine
-
-    /**
-     * 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>
+/**
+ * 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,
+        }
+    })
 }
 
-let server: RpgServerEngine
-let clients: RpgClientEngine[]
+/**
+ * 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: [] }
+    }
 
-function changeMap(client: RpgClientEngine, server: RpgServerEngine, mapId: string, position?: PositionMap): Promise<void> {
-    return new Promise(async (resolve: any) => {
-        let player = RpgWorld.getPlayer(client.playerId)
+    // 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
+    )
 
-        const beforeLoading = () => {
-            client.PIXI.utils.clearTextureCache()
-        }
+    const serverModules: RpgServer[] = []
+    const clientModules: RpgClient[] = []
+
+    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 }
+    }
 
-        const afterLoading = () => {
-            client.nextFrame(0) 
-            RpgPlugin.off(HookClient.BeforeSceneLoading, beforeLoading)
-            RpgPlugin.off(HookClient.AfterSceneLoading, afterLoading)
-            resolve()
+    // 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>()
+
+    modules.forEach((provider: any) => {
+        if (!provider || typeof provider !== 'object' || !('meta' in provider) || !('useValue' in provider)) {
+            return
         }
 
-        RpgPlugin.on(HookClient.BeforeSceneLoading, beforeLoading)
-        RpgPlugin.on(HookClient.AfterSceneLoading, afterLoading)
+        const { useValue } = provider
         
-        await player.changeMap(mapId, position)
+        // Skip if we've already processed this useValue (same module, different provider for server/client)
+        if (seenUseValues.has(useValue)) {
+            return
+        }
+
+        // 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)
+            }
+        }
     })
+
+    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>}
- * @example
+ * 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
+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 serverClass = createServer({
+        ...serverConfig,
+        providers: [
+            provideServerModules(serverModules),
+            ...(serverConfig.providers || [])
+        ]
     })
-    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)
-        }
-    }
-
-    const _changeMap = function (client: RpgClientEngine, mapId: string, position?: PositionMap) {
-        return changeMap(client, server, mapId, position)
-    }
-
+    
+    // Store created instances for cleanup
+    const createdClients: Array<{
+        context: any;
+        clientEngine: RpgClientEngine;
+        websocket: AbstractWebsocket;
+        server?: any;
+    }> = []
+    
     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
+        async createClient() {
+            // 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
+            
+            const context = await startGame(
+                mergeConfig({
+                    ...clientConfig,
+                    providers: [
+                        provideClientGlobalConfig({}),
+                        ...(hasLoadMap ? [] : [provideTestingLoadMap()]), // Add only if not already provided
+                        provideClientModules(clientModules),
+                        ...(clientConfig.providers || [])
+                    ]
+                }, {
+                    providers: [provideRpg(serverClass)],
+                })
+            )
+            const websocket = inject<AbstractWebsocket>(WebSocketToken) as any
+            const clientEngine = inject<RpgClientEngine>(RpgClientEngine)
+            const playerId = clientEngine.playerId
+            if (!playerId) {
+                throw new Error('Player ID is not available')
+            }
+            const playerIdString: string = playerId
+            
+            // Get server instance
+            const server = websocket.getServer()
+            
+            // Disable auto tick for unit tests (manual control via nextTick)
+            // The map will be available after the player connects, so we disable it asynchronously
+            setTimeout(() => {
+                try {
+                    const serverMap = server?.subRoom as any
+                    if (serverMap && typeof serverMap.setAutoTick === 'function') {
+                        serverMap.setAutoTick(false)
+                    }
+                } catch (error) {
+                    // Ignore errors if map is not ready yet
+                }
+            }, 0)
+            
+            // Store instance for cleanup (both locally and globally)
+            const clientInstance = {
+                context,
+                clientEngine,
+                websocket,
+                server
+            }
+            createdClients.push(clientInstance)
+            globalFixtures.push(clientInstance)
+            
+            return {
+                get server() {
+                    return  websocket.getServer()
+                },
+                socket: websocket.getSocket(),
+                client: clientEngine,
+                playerId: playerIdString,
+                get player(): RpgPlayer {
+                    return this.server.subRoom.players()[playerIdString] as RpgPlayer
+                },
+                /**
+                 * Wait for player to be on a specific map
+                 * 
+                 * This utility function polls the player's current map until it matches
+                 * the expected map ID, or throws an error if the timeout is exceeded.
+                 * 
+                 * @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> {
+                    const startTime = Date.now()
+
+                    while (Date.now() - startTime < timeout) {
+                        const currentMap = this.player.getCurrentMap()
+                        if (currentMap?.id === expectedMapId) {
+                            return this.player
+                        }
+                        await new Promise(resolve => setTimeout(resolve, 50)) // Wait 50ms before next check
+                    }
+                    
+                    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)
+                }
+            }
         },
-        server: engine,
-        changeMap: _changeMap
+        /**
+         * 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() {
+            // Use the global clear function
+            clear()
+        }
     }
 }
 
 /**
- * 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>`
+    // 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 = 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 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
 }
 
 /**
- * @title Wait a moment
- * @method waitUntil(promise)
- * @param {Promise<any>} promise
- * @returns {Promise<any>}
- * @since 4.0.0
- * @memberof Testing
- * @example
+ * 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
- * await waitUntil(
- *  player.moveRoutes([Move.right()])
- * )
+ * 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 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 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
+    ])
+}
+
+/**
+ * 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()
+ * ```
+ */
+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)
 }