Class NetcodeIntegrationTest
The default Netcode for GameObjects integration test helper class
Inherited Members
Namespace: Unity.Netcode.TestHelpers.Runtime
Assembly: solution.dll
Syntax
public abstract class NetcodeIntegrationTestConstructors
| Name | Description |
|---|---|
| NetcodeIntegrationTest() | Default constructor |
| 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) { } } |
Fields
| Name | Description |
|---|---|
| NetcodeLogAssert | |
| k_DefaultTickRate | |
| m_ClientNetworkManagers | |
| 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. |
| 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] |
| m_PlayerPrefab | |
| m_ServerNetworkManager | |
| m_TargetFrameRate | |
| m_UseHost | |
| s_DefaultWaitForTick | |
| 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 |
| s_GlobalTimeoutHelper |
Properties
| Name | Description |
|---|---|
| LogAllMessages | |
| NumberOfClients | |
| TotalClients | |
| m_BypassConnectionTimeout | When set to true, this will bypass the entire wait for clients to connect process. |
| 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:
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. |
| m_EnableVerboseDebug | |
| 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. |
| 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. |
Methods
| Name | Description |
|---|---|
| AssertOnTimeout(string, TimeoutHelper) | Just a helper function to avoid having to write the entire assert just to check if you timed out. |
| CanClientsLoad() | Override this method to control when clients can fake-load a scene. |
| CanClientsUnload() | Override this method to control when clients can fake-unload a scene. |
| CanDestroyNetworkObject(NetworkObject) | Override this to filter out the NetworkObjects that you want to allow to persist between integration tests. DestroySceneNetworkObjects() ShutdownAndCleanUp() |
| CanStartServerAndClients() | Override this method and return false in order to be able to manually control when the server and clients are started. |
| ClientNetworkManagerPostStartInit() | |
| CreateAndStartNewClient() | This will create, start, and connect a new client while in the middle of an integration test. |
| CreateAndStartNewClientWithTimeTravel() | This will create, start, and connect a new client while in the middle of an integration test. |
| 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. |
| CreateServerAndClients() | Will create NumberOfClients number of clients. To create a specific number of clients CreateServerAndClients(int) |
| CreateServerAndClients(int) | Creates the server and clients |
| DeRegisterSceneManagerHandler() | De-Registers from the CanClientsLoad and CanClientsUnload events of the ClientSceneHandler (default is IntegrationTestSceneHandler). |
| DeregisterNetworkObject(ulong, ulong) | |
| DeregisterNetworkObject(NetworkObject) | |
| DestroySceneNetworkObjects() | Destroys all NetworkObjects at the end of a test cycle. |
| EnableMessageLogging() | For debugging purposes, this will turn on verbose logging of all messages and batches sent and received |
| OnCanSceneCleanUpUnload(Scene) | |
| OnCreatePlayerPrefab() | Override this to add components or adjustments to the default player prefab m_PlayerPrefab |
| OnInlineSetup() | Called before creating and starting the server and clients Note: For AllTests and PerTest mode integration tests. For those two modes, if you want to have access to the server or client NetworkManagers then override OnServerAndClientsCreated(). m_ServerNetworkManager and m_ClientNetworkManagers |
| OnInlineTearDown() | |
| OnNewClientCreated(NetworkManager) | CreateAndStartNewClient Only Invoked when the newly created client has been created |
| OnNewClientStarted(NetworkManager) | CreateAndStartNewClient Only Invoked when the newly created client has been created and started |
| OnNewClientStartedAndConnected(NetworkManager) | CreateAndStartNewClient Only Invoked when the newly created client has been created, started, and connected to the server-host. |
| 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. |
| OnPlayerPrefabGameObjectCreated() | Invoked immediately after the player prefab GameObject is created prior to adding a NetworkObject component |
| OnServerAndClientsConnected() | Invoked after the server and clients have started and verified their connections with each other. |
| 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. |
| OnSetIntegrationTestMode() | The very first thing invoked during the OneTimeSetup() that determines how this integration test handles NetworkManager instantiation and destruction. NetcodeIntegrationTest.NetworkManagerInstatiationMode Override this method to change the default mode: AllTests |
| OnSetVerboseDebug() | Override this and return true if you need to troubleshoot a hard to track bug within an integration test. |
| OnSetup() | Called before creating and starting the server and clients Note: For AllTests and PerTest mode integration tests. For those two modes, if you want to have access to the server or client NetworkManagers then override OnServerAndClientsCreated(). m_ServerNetworkManager and m_ClientNetworkManagers |
| OnStartedServerAndClients() | Invoked after the server and clients have started. Note: No connection verification has been done at this point |
| OnTearDown() | Note: For PerTest mode this is called before ShutdownAndCleanUp. |
| OnTimeTravelServerAndClientsConnected() | Invoked after the server and clients have started and verified their connections with each other. |
| OnTimeTravelStartedServerAndClients() | Invoked after the server and clients have started. Note: No connection verification has been done at this point |
| OneTimeSetup() | |
| OneTimeTearDown() | |
| RegisterNetworkObject(NetworkObject) | |
| RegisterSceneManagerHandler() | Registers the CanClientsLoad and CanClientsUnload events of the ClientSceneHandler. The default is: IntegrationTestSceneHandler. |
| SetUp() | |
| ShouldWaitForNewClientToConnect(NetworkManager) | CreateAndStartNewClient Only Override this method to bypass the waiting for a client to connect. |
| ShutdownAndCleanUp() | This shuts down all NetworkManager instances registered via the NetcodeIntegrationTestHelpers class and cleans up the test runner scene of any left over NetworkObjects. DestroySceneNetworkObjects() |
| 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. |
| SpawnObject(GameObject, NetworkManager, bool) | Overloaded method SpawnObject(NetworkObject, NetworkManager, bool) |
| SpawnObjects(GameObject, NetworkManager, int, bool) | Overloaded method SpawnObjects(NetworkObject, NetworkManager, int, bool) |
| StartServerAndClients() | This starts the server and clients as long as CanStartServerAndClients() returns true. |
| StartServerAndClientsWithTimeTravel() | This starts the server and clients as long as CanStartServerAndClients() returns true. |
| StopOneClient(NetworkManager, bool) | This will stop a client while in the middle of an integration test |
| StopOneClientWithTimeTravel(NetworkManager, bool) | This will stop a client while in the middle of an integration test |
| TearDown() | |
| 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) |
| TimeTravelToNextTick() | Helper function to time travel exactly one tick's worth of time at the current frame and tick rates. |
| VerboseDebug(string) | Used to display the various integration test stages and can be used to log verbose information for troubleshooting an integration test. |
| WaitForClientsConnectedOrTimeOut() | Overloaded method that just passes in all clients to WaitForClientsConnectedOrTimeOut(NetworkManager[]) |
| 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. |
| WaitForClientsConnectedOrTimeOutWithTimeTravel() | Overloaded method that just passes in all clients to WaitForClientsConnectedOrTimeOut(NetworkManager[]) Uses time travel to simulate this for the given number of frames, simulating delta times at the application frame rate. |
| 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. |
| 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 |
| WaitForConditionOrTimeOut(IConditionalPredicate, TimeoutHelper) | This version accepts an IConditionalPredicate implementation to provide more flexibility for checking complex conditional cases. |
| 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. |
| 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. |
| WaitForTicks(NetworkManager, int) | Yields until specified amount of network ticks and the expected number of frames has been passed. |