Playmode tests


The Unity Editor supports some testing features that can be used to automate certain quality control processes. One particular feature, called Playmode Tests allows tests to be written against the application that run in coroutines and can therefore be fully scripted.

How it works

PlayMode tests run in a different way to unit tests, supporting coroutines. They are run using the Unity Test Runner in the Unity Editor.


By using the Avatar recording feature, VR users can be simulated in a test, which allows interaction testing to be automated.

How to create a new playmode test

  1. Copy and rename the file Assets\ImmerseSDK\Testing\Scripts\NewPlayModeTest.cs as a starting point for the new test.
  • Delete the existing tests in the file so that customised methods can be added.
  • Ensure each of the tests have the following attributes:
    [UnityTest] - This allows the test to run as a coroutine
    [Timeout(PlayModeTestUtilities.Seconds30)] - a different constant can be specified for longer timeouts.
    [PrebuildSetup(typeof(PlayModeTestsSetup))] - this ensures that all the scenes in the project are available for testing at run time.

Note: The test is a coroutine, so we have to wait for things to load / start-up.

How to run playmode test(s)

Tests can be run in the Unity Editor by selecting Playmode in the Test Runner and running the relevant test(s).


  • Editor scripts cannot be accessed when running PlayMode tests
  • Ensure the correct scenes are available in the Build Settings when the player is built for the tests. The SDK automatically adds all scenes in the project to the Build List when running tests.
  • Be aware of the assets and scenes being used for testing. The preferred way is to create all GameObjects programmatically if possible (Unity will create them with cheap shaders).
  • Do not expect the rendering to look like the real app - logic is being tested, not how things look!
  • If Unity is being run on a continuous integration machine, it will most likely run in "headless mode", which only gives access to a "software graphics device" or NULL device, so lots of functions are not available or stubbed out.
  • Only Offline mode is supported. See Offline builds.
  • Access is unavailable to Steam or VR hardware, so they must be "mocked" up. For this, a ScriptedAvatar feature is included, which will automatically be created by the SDK when running Playmode tests.
  • The Immerse SDK uses many code constructs (such as singletons and static variables) which disallows a clean restart. The best way is to follow the instructions above on how to create a new scene.
  • Unity's testing framework is based on NUnit, and follows the same system for writing and marking test methods. Unfortunately, because a real-time rendering system is being used, some of the Setup/Teardown methods won't work as expected (for instance, making them coroutines is not currently supported). So be careful!

To take care of some of these issues and provide helper code to set up the test environment, the Immerse SDK provides tools including an Avatar recording system that can record the head/controller positions and input which can be used in tests.

Updated 11 months ago

Playmode tests

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.