Responsible in Unity

Supported Unity versions

  • 2019, 2020: Fully supported. CI is periodically updated to run on the latest releases, but might lag behind a bit. Please report any issues you find.
  • 2021: There was a change in async/await behavior around Unity 2021.3, which subtly changes the execution timing of canceled tasks. This now works differently from both standard .NET runtimes and earlier Unity versions. Due to this, and Responsible not being actively used on 2021 (as far as I know), the probability for there being some issues with 2021 is more likely than with older versions. Please report any issues you find.
  • No TECH stream releases are tested, but feel free to report issues you find, and they might get fixed. However, ensuring correct functionality on 2021 is a higher priority right now.

Overview

Responsible was originally written for Unity, and only later ported to .NET standard, so there are many things already set up for getting started.

To start using Responsible, you'll need to

  • install the package,
  • reference the Responsible assembly from your test assemblies, and
  • set up your tests using UnityTestInstructionExecutor.

Installation

OpenUMP is the recommended way of installing Responsible in Unity.

Using OpenUPM

After setting up OpenUMP, you can add Responsible to your project by running

openupm add com.beatwaves.responsible

Direct Unity Package Manager Reference

Select the version you want to use from releases, and add the following to Packages/manifest.json

"com.beatwaves.responsible": "https://github.com/sbergen/Responsible.git?path=/com.beatwaves.responsible#vX.Y.Z"

replacing X.Y.Z with the version you want to use.

Without the Package Manager

If you can't or don't want to use the package manager, you can also directly incorporate the com.beatwaves.responsible directory into your project. This could be done manually, or e.g. with a symlink and git submodule.

Referencing the Assembly

With either installation option, you'll end up with an assembly called Responsible, with the UNITY_INCLUDE_TESTS define constraint. To use Responsible, simply reference this from your test assemblies.

Examples

For a simple example of a basic test setup, there's an example project with some basic tests included. This sample game can be installed from the Unity Package Manager, and is also symlinked into the main Unity project in this repository, for convenience.

The library itself also has extensive test coverage, which may be used as more extensive examples of usage. Note that these tests live outside of the package, so that they do not get included into projects referencing Responsible. (This has to do with undocumented reasons related to using "type": "tests" in package.json).

Unity Error Log Handling

The Unity Tests Runner will fail tests on logged errors. While running a test instruction, Responsible will intercept this process, by listening to logged errors, and overriding the default behavior. The following points are worth noting:

  • If you are expecting an error, you must call UnityTestInstructionExecutor.ExpectLog instead of only calling UnityEngine.LogAssert.Expect.
  • Logging errors from any other thread but the main thread should mostly be handled, but might be slightly unreliable depending on timing. As test instructions are executed on the main thread, it's impossible to always attribute a logged error to the correct test instruction.
  • LogAssert.ignoreFailingMessages is respected at the time of logging.

Test Operation State Editor Window

By using the Editor window available under Window -> Responsible -> Operation State, you can observe the progress of your tests executing. The contents of the window updates in real time and matches the output produced on failures, except for the operation stack and stack trace.

Screenshot of Unity Operation State Window