Class NetcodeIntegrationTestHelpers

Provides helpers for running multi instance tests.

Inheritance

object

NetcodeIntegrationTestHelpers

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Unity.Netcode.TestHelpers.Runtime

Assembly: Unity.Netcode.Runtime.Tests.dll

Syntax

public static class NetcodeIntegrationTestHelpers

Fields

DefaultMinFrames

Defines the minimum number of frames to execute before WaitForCondition(Func<bool>, ResultWrapper<bool>, float, int) completes.

Declaration

public const int DefaultMinFrames = 1

Field Value

Type	Description
int

DefaultTimeout

Defines the default timeout for WaitForCondition(Func<bool>, ResultWrapper<bool>, float, int).

Declaration

public const float DefaultTimeout = 4

Field Value

Type	Description
float

Properties

IsNetcodeIntegrationTestRunning

When true a netcode test is in progress.

Declaration

public static bool IsNetcodeIntegrationTestRunning { get; }

Property Value

Type	Description
bool

NetworkManagerInstances

A list of all NetworkManager instances created for a test.

Declaration

public static List<NetworkManager> NetworkManagerInstances { get; }

Property Value

Type	Description
List<NetworkManager>

Methods

CleanUpHandlers()

Call this to clean up the IntegrationTestSceneHandler and destroy the s_CoroutineRunner. Note: If deriving from NetcodeIntegrationTest or using Destroy() then you typically won't need to do this.

Declaration

public static void CleanUpHandlers()

Create(int, out NetworkManager, out NetworkManager[], int, bool, bool, bool)

Creates NetworkingManagers and configures them for use in a multi instance setting.

Declaration

public static bool Create(int clientCount, out NetworkManager server, out NetworkManager[] clients, int targetFrameRate = 60, bool serverFirst = true, bool useMockTransport = false, bool useCmbService = false)

Parameters

Type	Name	Description
int	clientCount	The amount of clients
NetworkManager	server	The server NetworkManager
NetworkManager[]	clients	The clients NetworkManagers
int	targetFrameRate	The targetFrameRate of the Unity engine to use while the multi instance helper is running. Will be reset on shutdown.
bool	serverFirst	This determines if the server or clients will be instantiated first (defaults to server first)
bool	useMockTransport	When true, uses mock transport for testing, otherwise uses real transport. Default value is false
bool	useCmbService	If true, all clients will be created with a connection to a locally hosted da service. The server transport will use a mock transport as it is not needed.

Returns

Type	Description
bool	Returns true if the server and client instances were successfully created and configured, otherwise false

CreateNetworkObjectPrefab(string, NetworkManager, params NetworkManager[])

This will create and register a NetworkPrefab instance for all NetworkManager instances.
*** Invoke this method before starting any of the NetworkManager instances ***.

Declaration

public static GameObject CreateNetworkObjectPrefab(string baseName, NetworkManager authorityNetworkManager, params NetworkManager[] clients)

Parameters

Type	Name	Description
string	baseName	The base name of the network prefab. Keep it short as additional information will be added to this name.
NetworkManager	authorityNetworkManager	The authority NetworkManager (i.e. server, host, or session owner)
NetworkManager[]	clients	The clients that should also have this NetworkPrefab instance added to their network prefab list.

Returns

Type	Description
GameObject	The prefab's root GameObject

Remarks

When using a DistributedAuthority network topology, the authority NetworkManager can be within the clients array of NetworkManager instances.

CreateNewClients(int, out NetworkManager[], bool, bool)

Used to add a client to the already existing list of clients

Declaration

public static bool CreateNewClients(int clientCount, out NetworkManager[] clients, bool useMockTransport = false, bool useCmbService = false)

Parameters

Type	Name	Description
int	clientCount	The amount of clients
NetworkManager[]	clients	Output array containing the created NetworkManager instances
bool	useMockTransport	When true, uses mock transport for testing, otherwise uses real transport. Default value is false
bool	useCmbService	If true, each client will be created with transport configured to connect to a locally hosted da service

Returns

Type	Description
bool	Returns true if the clients were successfully created and configured, otherwise false.

CreateServer(bool)

Creates and configures a new server instance for integration testing.

Declaration

public static NetworkManager CreateServer(bool mockTransport = false)

Parameters

Type	Name	Description
bool	mockTransport	When true, uses mock transport for testing, otherwise uses real transport. Default value is false

Returns

Type	Description
NetworkManager	The created server NetworkManager instance.

Destroy()

Should always be invoked when finished with a single unit test (i.e. during TearDown)

Declaration

public static void Destroy()

GetNetworkObjectByRepresentation(Func<NetworkObject, bool>, NetworkManager, ResultWrapper<NetworkObject>, bool, float)

Gets a NetworkObject instance as it's represented by a certain peer.

Declaration

public static IEnumerator GetNetworkObjectByRepresentation(Func<NetworkObject, bool> predicate, NetworkManager representation, NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject> result, bool failIfNull = true, float timeout = 4)

Parameters

Type	Name	Description
Func<NetworkObject, bool>	predicate	The predicate used to filter for your target NetworkObject
NetworkManager	representation	The representation to get the object from
NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject>	result	The result
bool	failIfNull	Whether or not to fail if no object is found and result is null
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

GetNetworkObjectByRepresentation(ulong, NetworkManager, ResultWrapper<NetworkObject>, bool, float)

Gets a NetworkObject instance as it's represented by a certain peer.

Declaration

public static IEnumerator GetNetworkObjectByRepresentation(ulong networkObjectId, NetworkManager representation, NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject> result, bool failIfNull = true, float timeout = 4)

Parameters

Type	Name	Description
ulong	networkObjectId	The networkObjectId to get
NetworkManager	representation	The representation to get the object from
NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject>	result	The result
bool	failIfNull	Whether or not to fail if no object is found and result is null
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

GetNetworkObjectByRepresentationWithTimeTravel(Func<NetworkObject, bool>, NetworkManager, ResultWrapper<NetworkObject>, bool, int)

Gets a NetworkObject instance as it's represented by a certain peer.

Declaration

public static void GetNetworkObjectByRepresentationWithTimeTravel(Func<NetworkObject, bool> predicate, NetworkManager representation, NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject> result, bool failIfNull = true, int maxTries = 60)

Parameters

Type	Name	Description
Func<NetworkObject, bool>	predicate	The predicate used to filter for your target NetworkObject
NetworkManager	representation	The representation to get the object from
NetcodeIntegrationTestHelpers.ResultWrapper<NetworkObject>	result	The result
bool	failIfNull	Whether or not to fail if no object is found and result is null
int	maxTries	The max frames to wait for

GetNextGlobalIdHashValue()

Returns the next GlobalObjectIdHash value to use when spawning NetworkObjects during a test.

Declaration

public static uint GetNextGlobalIdHashValue()

Returns

Type	Description
uint	The GlobsalObjectIdHash value as an uint.

MakeNetworkObjectTestPrefab(NetworkObject, uint)

Normally we would only allow player prefabs to be set to a prefab. Not runtime created objects. In order to prevent having a Resource folder full of a TON of prefabs that we have to maintain, MultiInstanceHelper has a helper function that lets you mark a runtime created object to be treated as a prefab by the Netcode. That's how we can get away with creating the player prefab at runtime without it being treated as a SceneObject or causing other conflicts with the Netcode.

Declaration

public static void MakeNetworkObjectTestPrefab(NetworkObject networkObject, uint globalObjectIdHash = 0)

Parameters

Type	Name	Description
NetworkObject	networkObject	The networkObject to be treated as Prefab
uint	globalObjectIdHash	The GlobalObjectId to force

MarkAsSceneObjectRoot(GameObject, NetworkManager, NetworkManager[])

Deprecated an not used.

Declaration

[Obsolete("This method is no longer valid or used.", false)]
public static void MarkAsSceneObjectRoot(GameObject networkObjectRoot, NetworkManager server, NetworkManager[] clients)

Parameters

Type	Name	Description
GameObject	networkObjectRoot	GameObject
NetworkManager	server	NetworkManager
NetworkManager[]	clients	An array of NetworkManagers

RefreshAllPrefabInstances(NetworkObject, Action)

This method is no longer used.

Declaration

[Obsolete("This method is deprecated and no longer used", false)]
public static void RefreshAllPrefabInstances(NetworkObject networkObject, Action scenesProcessed)

Parameters

Type	Name	Description
NetworkObject	networkObject	NetworkObject
Action	scenesProcessed	Action

RegisterHandlers(NetworkManager, bool)

Call this to register scene validation and the IntegrationTestSceneHandler Note: If deriving from NetcodeIntegrationTest or using Destroy() then you typically won't need to call this.

Declaration

public static void RegisterHandlers(NetworkManager networkManager, bool serverSideSceneManager = false)

Parameters

Type	Name	Description
NetworkManager	networkManager	The NetworkManager registering handlers.
bool	serverSideSceneManager	When true, the NetworkManager will register as the scene manager handler.

RegisterNetcodeIntegrationTest(bool)

Can be invoked to register prior to starting a test.

Declaration

public static void RegisterNetcodeIntegrationTest(bool registered)

Parameters

Type	Name	Description
bool	registered	true or false

SetRefreshAllPrefabsCallback(Action)

This method is no longer used.

Declaration

[Obsolete("This method is deprecated and no longer used", false)]
public static void SetRefreshAllPrefabsCallback(Action scenesProcessed)

Parameters

Type	Name	Description
Action	scenesProcessed	Action

Start(bool, NetworkManager, NetworkManager[], BeforeClientStartCallback, bool)

Starts NetworkManager instances created by the Create method.

Declaration

public static bool Start(bool host, NetworkManager server, NetworkManager[] clients, NetcodeIntegrationTestHelpers.BeforeClientStartCallback callback = null, bool startServer = true)

Parameters

Type	Name	Description
bool	host	Whether or not to create a Host instead of Server
NetworkManager	server	The Server NetworkManager
NetworkManager[]	clients	The Clients NetworkManager
NetcodeIntegrationTestHelpers.BeforeClientStartCallback	callback	called immediately after server is started and before client(s) are started
bool	startServer	true to start it false to not start it.

Returns

Type	Description
bool	true if all instances started successfully, false otherwise

StartOneClient(NetworkManager)

Starts one single client and makes sure to register the required hooks and handlers

Declaration

public static void StartOneClient(NetworkManager clientToStart)

Parameters

Type	Name	Description
NetworkManager	clientToStart	The NetworkManager instance to start

Remarks

Do not call this function directly. Use CreateAndStartNewClient() instead.

StopOneClient(NetworkManager, bool)

Stops one single client and makes sure to cleanup any static variables in this helper

Declaration

public static void StopOneClient(NetworkManager clientToStop, bool destroy = true)

Parameters

Type	Name	Description
NetworkManager	clientToStop	The NetworkManager instance to stop
bool	destroy	When true, destroys the GameObject, when false, only shuts down the network connection. Default value is true

WaitForClientConnected(NetworkManager, ResultWrapper<bool>, float)

Waits on the client side to be connected.

Declaration

public static IEnumerator WaitForClientConnected(NetworkManager client, NetcodeIntegrationTestHelpers.ResultWrapper<bool> result = null, float timeout = 4)

Parameters

Type	Name	Description
NetworkManager	client	The client
NetcodeIntegrationTestHelpers.ResultWrapper<bool>	result	The result. If null, it will automatically assert
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

WaitForClientConnectedToServer(NetworkManager, ResultWrapper<bool>, float)

Waits on the server side for 1 client to be connected

Declaration

public static IEnumerator WaitForClientConnectedToServer(NetworkManager server, NetcodeIntegrationTestHelpers.ResultWrapper<bool> result = null, float timeout = 4)

Parameters

Type	Name	Description
NetworkManager	server	The server
NetcodeIntegrationTestHelpers.ResultWrapper<bool>	result	The result. If null, it will automatically assert
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

WaitForClientsConnected(NetworkManager[], ResultWrapper<bool>, float)

Similar to WaitForClientConnected, this waits for multiple clients to be connected.

Declaration

public static IEnumerator WaitForClientsConnected(NetworkManager[] clients, NetcodeIntegrationTestHelpers.ResultWrapper<bool> result = null, float timeout = 4)

Parameters

Type	Name	Description
NetworkManager[]	clients	The clients to be connected
NetcodeIntegrationTestHelpers.ResultWrapper<bool>	result	The result. If null, it will automatically assert
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

WaitForClientsConnectedToServer(NetworkManager, int, ResultWrapper<bool>, float)

Waits on the server side for 1 client to be connected

Declaration

public static IEnumerator WaitForClientsConnectedToServer(NetworkManager server, int clientCount = 1, NetcodeIntegrationTestHelpers.ResultWrapper<bool> result = null, float timeout = 4)

Parameters

Type	Name	Description
NetworkManager	server	The server
int	clientCount	The number of clients.
NetcodeIntegrationTestHelpers.ResultWrapper<bool>	result	The result. If null, it will automatically assert
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout

Returns

Type	Description
IEnumerator	IEnumerator

WaitForCondition(Func<bool>, ResultWrapper<bool>, float, int)

Waits for a predicate condition to be met

Declaration

public static IEnumerator WaitForCondition(Func<bool> predicate, NetcodeIntegrationTestHelpers.ResultWrapper<bool> result = null, float timeout = 4, int minFrames = 1)

Parameters

Type	Name	Description
Func<bool>	predicate	The predicate to wait for
NetcodeIntegrationTestHelpers.ResultWrapper<bool>	result	The result. If null, it will fail if the predicate is not met
float	timeout	Maximum time in seconds to wait for connection. Defaults to DefaultTimeout
int	minFrames	The min frames to wait for

Returns

Type	Description
IEnumerator	IEnumerator