Class NetcodeIntegrationTest
The default Netcode for GameObjects integration test helper class
Inheritance
NetcodeIntegrationTest
Assembly: Unity.Netcode.TestHelpers.Runtime.dll
Syntax
public abstract class NetcodeIntegrationTest
Constructors
NetcodeIntegrationTest()
Declaration
public NetcodeIntegrationTest()
NetcodeIntegrationTest(NetworkTopologyTypes)
Declaration
public NetcodeIntegrationTest(NetworkTopologyTypes networkTopologyType)
Parameters
NetcodeIntegrationTest(NetworkTopologyTypes, HostOrServer)
Declaration
public NetcodeIntegrationTest(NetworkTopologyTypes networkTopologyType, NetcodeIntegrationTest.HostOrServer hostOrServer)
Parameters
NetcodeIntegrationTest(HostOrServer)
Optional Host or Server integration tests
Constructor that allows you To break tests up as a host
and a server.
Example: Decorate your child derived class with TestFixture
and then create a constructor at the child level.
Don't forget to set your constructor public, else Unity will
give you a hard to decipher error
[TestFixture(HostOrServer.Host)]
[TestFixture(HostOrServer.Server)]
public class MyChildClass : NetcodeIntegrationTest
{
public MyChildClass(HostOrServer hostOrServer) : base(hostOrServer)
}
Declaration
public NetcodeIntegrationTest(NetcodeIntegrationTest.HostOrServer hostOrServer)
Parameters
Fields
NetcodeLogAssert
Declaration
public NetcodeLogAssert NetcodeLogAssert
Field Value
k_DefaultTickRate
Declaration
protected const uint k_DefaultTickRate = 30
Field Value
k_DefaultTimeoutPeriod
Used to determine if a NetcodeIntegrationTest is currently running to
determine how clients will load scenes
Declaration
protected const float k_DefaultTimeoutPeriod = 8
Field Value
k_TickFrequency
Declaration
protected const float k_TickFrequency = 0.033333335
Field Value
m_ClientNetworkManagers
Declaration
protected NetworkManager[] m_ClientNetworkManagers
Field Value
m_CreateServerFirst
Set this to false to create the clients first.
Note: If you are using scene placed NetworkObjects or doing any form of scene testing and
get prefab hash id "soft synchronization" errors, then set this to false and run your test
again. This is a work-around until we can resolve some issues with NetworkManagerOwner and
NetworkManager.Singleton.
Declaration
protected bool m_CreateServerFirst
Field Value
m_DistributedAuthority
Declaration
protected bool m_DistributedAuthority
Field Value
m_NetworkTopologyType
Declaration
protected NetworkTopologyTypes m_NetworkTopologyType
Field Value
m_PlayerNetworkObjects
Contains each client relative set of player NetworkObject instances
[Client Relative set of player instances][The player instance ClientId][The player instance's NetworkObject]
Example:
To get the player instance with a ClientId of 3 that was instantiated (relative) on the player instance with a ClientId of 2
m_PlayerNetworkObjects[2][3]
Declaration
protected Dictionary<ulong, Dictionary<ulong, NetworkObject>> m_PlayerNetworkObjects
Field Value
m_PlayerPrefab
Declaration
protected GameObject m_PlayerPrefab
Field Value
m_ServerNetworkManager
Declaration
protected NetworkManager m_ServerNetworkManager
Field Value
m_TargetFrameRate
Declaration
protected int m_TargetFrameRate
Field Value
m_UseHost
Declaration
Field Value
s_DefaultWaitForTick
Declaration
protected static WaitForSecondsRealtime s_DefaultWaitForTick
Field Value
s_GlobalNetworkObjects
Registered list of all NetworkObjects spawned.
Format is as follows:
[ClientId-side where this NetworkObject instance resides][NetworkObjectId][NetworkObject]
Where finding the NetworkObject with a NetworkObjectId of 10 on ClientId of 2 would be:
s_GlobalNetworkObjects[2][10]
To find the client or server player objects please see:
m_PlayerNetworkObjects
Declaration
protected static Dictionary<ulong, Dictionary<ulong, NetworkObject>> s_GlobalNetworkObjects
Field Value
s_GlobalTimeoutHelper
Declaration
protected static TimeoutHelper s_GlobalTimeoutHelper
Field Value
Properties
LogAllMessages
Declaration
protected virtual bool LogAllMessages { get; }
Property Value
NumberOfClients
Declaration
protected abstract int NumberOfClients { get; }
Property Value
TotalClients
Declaration
protected int TotalClients { get; }
Property Value
m_BypassConnectionTimeout
When set to true, this will bypass the entire
wait for clients to connect process.
Declaration
protected bool m_BypassConnectionTimeout { get; set; }
Property Value
m_EnableTimeTravel
Enables "Time Travel" within the test, which swaps the time provider for the SDK from Unity's
Time class to MockTimeProvider, and also swaps the transport implementation
from UnityTransport to MockTransport.
This enables five important things that help with both performance and determinism of tests that involve a
lot of time and waiting:
- It allows time to move in a completely deterministic way (testing that something happens after n seconds,
the test will always move exactly n seconds with no chance of any variability in the timing),
- It allows skipping periods of time without actually waiting that amount of time, while still simulating
SDK frames as if that time were passing,
- It dissociates the SDK's update loop from Unity's update loop, allowing us to simulate SDK frame updates
without waiting for Unity to process things like physics, animation, and rendering that aren't relevant to
the test,
- It dissociates the SDK's messaging system from the networking hardware, meaning there's no delay between
a message being sent and it being received, allowing us to deterministically rely on the message being
received within specific time frames for the test, and
- It allows tests to be written without the use of coroutines, which not only improves the test's runtime,
but also results in easier-to-read callstacks and removes the possibility for an assertion to result in the
test hanging.
When time travel is enabled, the following methods become available:
TimeTravel(double, int): Simulates a specific number of frames passing over a specific time period
TimeTravelToNextTick(): Skips forward to the next tick, siumlating at the current application frame rate
WaitForConditionOrTimeOutWithTimeTravel(Func<bool>, int): Simulates frames at the application frame rate until the given condition is true
WaitForMessageReceivedWithTimeTravel<T>(List<NetworkManager>, ReceiptType): Simulates frames at the application frame rate until the required message is received
WaitForMessagesReceivedWithTimeTravel(List<Type>, List<NetworkManager>, ReceiptType): Simulates frames at the application frame rate until the required messages are received
StartServerAndClientsWithTimeTravel(): Starts a server and client and allows them to connect via simulated frames
CreateAndStartNewClientWithTimeTravel(): Creates a client and waits for it to connect via simulated frames
WaitForClientsConnectedOrTimeOutWithTimeTravel(NetworkManager[]) Simulates frames at the application frame rate until the given clients are connected
StopOneClientWithTimeTravel(NetworkManager, bool): Stops a client and simulates frames until it's fully disconnected.
When time travel is enabled, NetcodeIntegrationTest will automatically use these in its methods
when doing things like automatically connecting clients during SetUp.
Additionally, the following methods replace their non-time-travel equivalents with variants that are not coroutines:
OnTimeTravelStartedServerAndClients() - called when server and clients are started
OnTimeTravelServerAndClientsConnected() - called when server and clients are connected
Note that all of the non-time travel functions can still be used even when time travel is enabled - this is
sometimes needed for, e.g., testing NetworkAnimator, where the unity update loop needs to run to process animations.
However, it's VERY important to note here that, because the SDK will not be operating based on real-world time
but based on the frozen time that's locked in from MockTimeProvider, actions that pass 10 seconds apart by
real-world clock time will be perceived by the SDK as having happened simultaneously if you don't call
TimeTravel(double) to cover the equivalent time span in the mock time provider.
(Calling TimeTravel(double) instead of TimeTravel(double, int)
will move time forward without simulating any frames, which, in the case where real-world time has passed,
is likely more desirable). In most cases, this desynch won't affect anything, but it is worth noting that
it happens just in case a tested system depends on both the unity update loop happening and time moving forward.
Declaration
protected virtual bool m_EnableTimeTravel { get; }
Property Value
m_EnableVerboseDebug
Declaration
protected bool m_EnableVerboseDebug { get; set; }
Property Value
m_SetupIsACoroutine
If this is false, SetUp will call OnInlineSetUp instead of OnSetUp.
This is a performance advantage when not using the coroutine functionality, as a coroutine that
has no yield instructions in it will nonetheless still result in delaying the continuation of the
method that called it for a full frame after it returns.
Declaration
protected virtual bool m_SetupIsACoroutine { get; }
Property Value
m_TearDownIsACoroutine
If this is false, TearDown will call OnInlineTearDown instead of OnTearDown.
This is a performance advantage when not using the coroutine functionality, as a coroutine that
has no yield instructions in it will nonetheless still result in delaying the continuation of the
method that called it for a full frame after it returns.
Declaration
protected virtual bool m_TearDownIsACoroutine { get; }
Property Value
Methods
AssertOnTimeout(string, TimeoutHelper)
Just a helper function to avoid having to write the entire assert just to check if you
timed out.
Declaration
protected void AssertOnTimeout(string timeOutErrorMessage, TimeoutHelper assignedTimeoutHelper = null)
Parameters
CanClientsLoad()
Override this method to control when clients
can fake-load a scene.
Declaration
protected virtual bool CanClientsLoad()
Returns
CanClientsUnload()
Override this method to control when clients
can fake-unload a scene.
Declaration
protected virtual bool CanClientsUnload()
Returns
CanDestroyNetworkObject(NetworkObject)
Declaration
protected virtual bool CanDestroyNetworkObject(NetworkObject networkObject)
Parameters
| Type |
Name |
Description |
| NetworkObject |
networkObject |
the network object in question to be destroyed
|
Returns
CanStartServerAndClients()
Override this method and return false in order to be able
to manually control when the server and clients are started.
Declaration
protected virtual bool CanStartServerAndClients()
Returns
ClientNetworkManagerPostStartInit()
Declaration
protected void ClientNetworkManagerPostStartInit()
Declaration
protected void ConfigureFramesPerTick()
CoroutineShutdownAndCleanUp()
Declaration
protected IEnumerator CoroutineShutdownAndCleanUp()
Returns
CreateAndStartNewClient()
This will create, start, and connect a new client while in the middle of an
integration test.
Declaration
protected IEnumerator CreateAndStartNewClient()
Returns
| Type |
Description |
| IEnumerator |
An IEnumerator to be used in a coroutine for asynchronous execution.
|
CreateAndStartNewClientWithTimeTravel()
This will create, start, and connect a new client while in the middle of an
integration test.
Declaration
protected void CreateAndStartNewClientWithTimeTravel()
CreateNetworkObjectPrefab(string)
Creates a basic NetworkObject test prefab, assigns it to a new
NetworkPrefab entry, and then adds it to the server and client(s)
NetworkManagers' NetworkConfig.NetworkPrefab lists.
Declaration
protected GameObject CreateNetworkObjectPrefab(string baseName)
Parameters
| Type |
Name |
Description |
| string |
baseName |
the basic name to be used for each instance
|
Returns
| Type |
Description |
| GameObject |
NetworkObject of the GameObject assigned to the new NetworkPrefab entry
|
CreateServerAndClients()
Declaration
protected void CreateServerAndClients()
CreateServerAndClients(int)
Creates the server and clients
Declaration
protected void CreateServerAndClients(int numberOfClients)
Parameters
| Type |
Name |
Description |
| int |
numberOfClients |
The number of client instances to create
|
DeRegisterSceneManagerHandler()
De-Registers from the CanClientsLoad and CanClientsUnload events of the
ClientSceneHandler (default is IntegrationTestSceneHandler).
Declaration
protected void DeRegisterSceneManagerHandler()
DeregisterNetworkObject(ulong, ulong)
Declaration
public static void DeregisterNetworkObject(ulong localClientId, ulong networkObjectId)
Parameters
| Type |
Name |
Description |
| ulong |
localClientId |
|
| ulong |
networkObjectId |
|
DeregisterNetworkObject(NetworkObject)
Declaration
public static void DeregisterNetworkObject(NetworkObject networkObject)
Parameters
DestroySceneNetworkObjects()
Destroys all NetworkObjects at the end of a test cycle.
Declaration
protected void DestroySceneNetworkObjects()
EnableMessageLogging()
For debugging purposes, this will turn on verbose logging of all messages and batches sent and received
Declaration
protected void EnableMessageLogging()
GetFrameRate()
Declaration
protected virtual int GetFrameRate()
Returns
GetTickRate()
Declaration
protected virtual uint GetTickRate()
Returns
OnCanSceneCleanUpUnload(Scene)
Declaration
protected bool OnCanSceneCleanUpUnload(Scene scene)
Parameters
| Type |
Name |
Description |
| Scene |
scene |
|
Returns
OnCreatePlayerPrefab()
Override this to add components or adjustments to the default player prefab
m_PlayerPrefab
Declaration
protected virtual void OnCreatePlayerPrefab()
OnGetNetworkTopologyType()
Declaration
protected virtual NetworkTopologyTypes OnGetNetworkTopologyType()
Returns
OnInlineSetup()
Declaration
protected virtual void OnInlineSetup()
OnInlineTearDown()
Declaration
protected virtual void OnInlineTearDown()
OnNewClientCreated(NetworkManager)
CreateAndStartNewClient Only
Invoked when the newly created client has been created
Declaration
protected virtual void OnNewClientCreated(NetworkManager networkManager)
Parameters
| Type |
Name |
Description |
| NetworkManager |
networkManager |
The NetworkManager instance of the client.
|
OnNewClientStarted(NetworkManager)
CreateAndStartNewClient Only
Invoked when the newly created client has been created and started
Declaration
protected virtual void OnNewClientStarted(NetworkManager networkManager)
Parameters
| Type |
Name |
Description |
| NetworkManager |
networkManager |
The NetworkManager instance of the client.
|
OnNewClientStartedAndConnected(NetworkManager)
CreateAndStartNewClient Only
Invoked when the newly created client has been created, started, and connected
to the server-host.
Declaration
protected virtual void OnNewClientStartedAndConnected(NetworkManager networkManager)
Parameters
| Type |
Name |
Description |
| NetworkManager |
networkManager |
The NetworkManager instance of the client.
|
OnOneTimeSetup()
Declaration
protected virtual void OnOneTimeSetup()
OnOneTimeTearDown()
Override this method to do handle cleaning up once the test(s)
within the child derived class have completed
Note: For AllTests mode
this is called before ShutdownAndCleanUp.
Declaration
protected virtual void OnOneTimeTearDown()
OnPlayerPrefabGameObjectCreated()
Invoked immediately after the player prefab GameObject is created
prior to adding a NetworkObject component
Declaration
protected virtual void OnPlayerPrefabGameObjectCreated()
OnServerAndClientsConnected()
Invoked after the server and clients have started and verified
their connections with each other.
Declaration
protected virtual IEnumerator OnServerAndClientsConnected()
Returns
OnServerAndClientsCreated()
This is invoked before the server and client(s) are started.
Override this method if you want to make any adjustments to their
NetworkManager instances.
Declaration
protected virtual void OnServerAndClientsCreated()
OnSetIntegrationTestMode()
Declaration
protected virtual NetcodeIntegrationTest.NetworkManagerInstatiationMode OnSetIntegrationTestMode()
Returns
OnSetVerboseDebug()
Override this and return true if you need
to troubleshoot a hard to track bug within an
integration test.
Declaration
protected virtual bool OnSetVerboseDebug()
Returns
OnSetup()
Declaration
protected virtual IEnumerator OnSetup()
Returns
OnStartedServerAndClients()
Invoked after the server and clients have started.
Note: No connection verification has been done at this point
Declaration
protected virtual IEnumerator OnStartedServerAndClients()
Returns
OnTearDown()
Note: For PerTest mode
this is called before ShutdownAndCleanUp.
Declaration
protected virtual IEnumerator OnTearDown()
Returns
OnTimeTravelServerAndClientsConnected()
Invoked after the server and clients have started and verified
their connections with each other.
Declaration
protected virtual void OnTimeTravelServerAndClientsConnected()
OnTimeTravelStartedServerAndClients()
Invoked after the server and clients have started.
Note: No connection verification has been done at this point
Declaration
protected virtual void OnTimeTravelStartedServerAndClients()
OneTimeSetup()
Declaration
[OneTimeSetUp]
public void OneTimeSetup()
OneTimeTearDown()
Declaration
[OneTimeTearDown]
public void OneTimeTearDown()
RegisterNetworkObject(NetworkObject)
Declaration
public static void RegisterNetworkObject(NetworkObject networkObject)
Parameters
RegisterSceneManagerHandler()
Declaration
protected void RegisterSceneManagerHandler()
SetDistributedAuthorityProperties(NetworkManager)
Declaration
protected void SetDistributedAuthorityProperties(NetworkManager networkManager)
Parameters
SetTimeTravelSimulatedDropRate(float)
Declaration
protected void SetTimeTravelSimulatedDropRate(float dropRatePercent)
Parameters
| Type |
Name |
Description |
| float |
dropRatePercent |
|
SetTimeTravelSimulatedLatency(float)
Declaration
protected void SetTimeTravelSimulatedLatency(float latencySeconds)
Parameters
| Type |
Name |
Description |
| float |
latencySeconds |
|
SetTimeTravelSimulatedLatencyJitter(float)
Declaration
protected void SetTimeTravelSimulatedLatencyJitter(float jitterSeconds)
Parameters
| Type |
Name |
Description |
| float |
jitterSeconds |
|
SetUp()
Declaration
public IEnumerator SetUp()
Returns
ShouldCheckForSpawnedPlayers()
Declaration
protected virtual bool ShouldCheckForSpawnedPlayers()
Returns
ShouldWaitForNewClientToConnect(NetworkManager)
CreateAndStartNewClient Only
Override this method to bypass the waiting for a client to connect.
Declaration
protected virtual bool ShouldWaitForNewClientToConnect(NetworkManager networkManager)
Parameters
| Type |
Name |
Description |
| NetworkManager |
networkManager |
The NetworkManager instance of the client.
|
Returns
| Type |
Description |
| bool |
True if the test should wait for the client to connect; otherwise, false.
|
ShutdownAndCleanUp()
Declaration
protected void ShutdownAndCleanUp()
SimulateOneFrame()
Simulates one SDK frame. This can be used even without TimeTravel, though it's of somewhat less use
without TimeTravel, as, without the mock transport, it will likely not provide enough time for any
sent messages to be received even if called dozens of times.
Declaration
public static void SimulateOneFrame()
SpawnObject(GameObject, NetworkManager, bool)
Overloaded method SpawnObject(NetworkObject, NetworkManager, bool)
Declaration
protected GameObject SpawnObject(GameObject prefabGameObject, NetworkManager owner, bool destroyWithScene = false)
Parameters
Returns
SpawnObjects(GameObject, NetworkManager, int, bool)
Declaration
protected List<GameObject> SpawnObjects(GameObject prefabGameObject, NetworkManager owner, int count, bool destroyWithScene = false)
Parameters
Returns
SpawnPlayerObject(GameObject, NetworkManager, bool)
Overloaded method SpawnObject(NetworkObject, NetworkManager, bool)
Declaration
protected GameObject SpawnPlayerObject(GameObject prefabGameObject, NetworkManager owner, bool destroyWithScene = false)
Parameters
Returns
StartServerAndClients()
Declaration
protected IEnumerator StartServerAndClients()
Returns
StartServerAndClientsWithTimeTravel()
Declaration
protected void StartServerAndClientsWithTimeTravel()
StopOneClient(NetworkManager, bool)
This will stop a client while in the middle of an integration test
Declaration
protected IEnumerator StopOneClient(NetworkManager networkManager, bool destroy = false)
Parameters
Returns
StopOneClientWithTimeTravel(NetworkManager, bool)
This will stop a client while in the middle of an integration test
Declaration
protected void StopOneClientWithTimeTravel(NetworkManager networkManager, bool destroy = false)
Parameters
TearDown()
Declaration
public IEnumerator TearDown()
Returns
TimeTravel(double, int)
Simulate a number of frames passing over a specific amount of time.
The delta time simulated for each frame will be evenly divided as time/numFrames
This will only simulate the netcode update loop, as well as update events on
NetworkBehaviour instances, and will not simulate any Unity update processes (physics, etc)
Declaration
protected static void TimeTravel(double amountOfTimeInSeconds, int numFramesToSimulate)
Parameters
| Type |
Name |
Description |
| double |
amountOfTimeInSeconds |
The total amount of time to simulate, in seconds
|
| int |
numFramesToSimulate |
The number of frames to distribute the time across
|
TimeTravelAdvanceTick()
Helper function to time travel exactly one tick's worth of time at the current frame and tick rates.
This is NetcodeIntegrationTest instance relative and will automatically adjust based on GetFrameRate()
and GetTickRate().
Declaration
protected void TimeTravelAdvanceTick()
TimeTravelToNextTick()
Helper function to time travel exactly one tick's worth of time at the current frame and tick rates.
** Is based on the global k_DefaultTickRate and is not local to each NetcodeIntegrationTest instance **
Declaration
public static void TimeTravelToNextTick()
UseCMBService()
Declaration
protected virtual bool UseCMBService()
Returns
VerboseDebug(string)
Used to display the various integration test
stages and can be used to log verbose information
for troubleshooting an integration test.
Declaration
protected void VerboseDebug(string msg)
Parameters
| Type |
Name |
Description |
| string |
msg |
The debug message to be logged when verbose debugging is enabled
|
WaitForClientsConnectedOrTimeOut()
Declaration
protected IEnumerator WaitForClientsConnectedOrTimeOut()
Returns
WaitForClientsConnectedOrTimeOut(NetworkManager[])
Validates that all remote clients (i.e. non-server) detect they are connected
to the server and that the server reflects the appropriate number of clients
have connected or it will time out.
Declaration
protected IEnumerator WaitForClientsConnectedOrTimeOut(NetworkManager[] clientsToCheck)
Parameters
| Type |
Name |
Description |
| NetworkManager[] |
clientsToCheck |
An array of clients to be checked
|
Returns
WaitForClientsConnectedOrTimeOutWithTimeTravel()
Declaration
protected bool WaitForClientsConnectedOrTimeOutWithTimeTravel()
Returns
WaitForClientsConnectedOrTimeOutWithTimeTravel(NetworkManager[])
Validates that all remote clients (i.e. non-server) detect they are connected
to the server and that the server reflects the appropriate number of clients
have connected or it will time out. Uses time travel to simulate this
for the given number of frames, simulating delta times at the application frame rate.
Declaration
protected bool WaitForClientsConnectedOrTimeOutWithTimeTravel(NetworkManager[] clientsToCheck)
Parameters
| Type |
Name |
Description |
| NetworkManager[] |
clientsToCheck |
An array of clients to be checked
|
Returns
WaitForConditionOrTimeOut(Func<bool>, TimeoutHelper)
Waits for the function condition to return true or it will time out.
This will operate at the current m_ServerNetworkManager.NetworkConfig.TickRate
and allow for a unique TimeoutHelper handler (if none then it uses the default)
Notes: This provides more stability when running integration tests that could be
impacted by:
-how the integration test is being executed (i.e. in editor or in a stand alone build)
-potential platform performance issues (i.e. VM is throttled or maxed)
Note: For more complex tests, ConditionalPredicateBase and the overloaded
version of this method
Declaration
public static IEnumerator WaitForConditionOrTimeOut(Func<bool> checkForCondition, TimeoutHelper timeOutHelper = null)
Parameters
Returns
WaitForConditionOrTimeOut(IConditionalPredicate, TimeoutHelper)
This version accepts an IConditionalPredicate implementation to provide
more flexibility for checking complex conditional cases.
Declaration
public static IEnumerator WaitForConditionOrTimeOut(IConditionalPredicate conditionalPredicate, TimeoutHelper timeOutHelper = null)
Parameters
Returns
WaitForConditionOrTimeOutWithTimeTravel(Func<bool>, int)
Waits for the function condition to return true or it will time out. Uses time travel to simulate this
for the given number of frames, simulating delta times at the application frame rate.
Declaration
public bool WaitForConditionOrTimeOutWithTimeTravel(Func<bool> checkForCondition, int maxTries = 60)
Parameters
| Type |
Name |
Description |
| Func<bool> |
checkForCondition |
|
| int |
maxTries |
|
Returns
WaitForConditionOrTimeOutWithTimeTravel(IConditionalPredicate, int)
This version accepts an IConditionalPredicate implementation to provide
more flexibility for checking complex conditional cases. Uses time travel to simulate this
for the given number of frames, simulating delta times at the application frame rate.
Declaration
public bool WaitForConditionOrTimeOutWithTimeTravel(IConditionalPredicate conditionalPredicate, int maxTries = 60)
Parameters
Returns
WaitForTicks(NetworkManager, int)
Yields until specified amount of network ticks and the expected number of frames has been passed.
Declaration
protected IEnumerator WaitForTicks(NetworkManager networkManager, int count)
Parameters
Returns