Commit af571a61 authored by BlackAngle233's avatar BlackAngle233
Browse files

212

parent 1d9b5391
# Vector2EqualityComparer # Vector2EqualityComparer
Use this class to compare two [Vector2](https://docs.unity3d.com/ScriptReference/Vector2.html) objects for equality with [NUnit](http://www.nunit.org/) constraints. Use the static `Vector2EqualityComparer.Instance` to have the calculation error value set to default 0.0001f. For any other error value, instantiate a new comparer object with the [one argument constructor](#constructors). Use this class to compare two [Vector2](https://docs.unity3d.com/ScriptReference/Vector2.html) objects for equality with [NUnit](http://www.nunit.org/) constraints. Use the static `Vector2EqualityComparer.Instance` to have the calculation error value set to default 0.0001f. For any other error value, instantiate a new comparer object with the [one argument constructor](#constructors).
## Static properties ## Static properties
| Syntax | Description | | Syntax | Description |
| ---------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ |
| `Instance` | A comparer instance with the default error value set to 0.0001f. | | `Instance` | A comparer instance with the default error value set to 0.0001f. |
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| -------------------------------------- | ---------------------------------------------- | | -------------------------------------- | ---------------------------------------------- |
| `Vector2EqualityComparer(float error)` | Creates an instance with a custom error value. | | `Vector2EqualityComparer(float error)` | Creates an instance with a custom error value. |
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------ | ------------------------------------------------------------ |
| `Equals(Vector2 expected, Vector2 actual)` | Compares the `actual` and `expected` `Vector2` objects for equality using the [Utils.AreFloatsEqual](./reference-test-utils.md) method. | | `Equals(Vector2 expected, Vector2 actual)` | Compares the `actual` and `expected` `Vector2` objects for equality using the [Utils.AreFloatsEqual](./reference-test-utils.md) method. |
## Example ## Example
```c# ```c#
[TestFixture] [TestFixture]
public class Vector2Test public class Vector2Test
{ {
[Test] [Test]
public void VerifyThat_TwoVector2ObjectsAreEqual() public void VerifyThat_TwoVector2ObjectsAreEqual()
{ {
// Custom calculation error // Custom calculation error
var actual = new Vector2(10e-7f, 10e-7f); var actual = new Vector2(10e-7f, 10e-7f);
var expected = new Vector2(0f, 0f); var expected = new Vector2(0f, 0f);
var comparer = new Vector2EqualityComparer(10e-6f); var comparer = new Vector2EqualityComparer(10e-6f);
Assert.That(actual, Is.EqualTo(expected).Using(comparer)); Assert.That(actual, Is.EqualTo(expected).Using(comparer));
//Default error 0.0001f //Default error 0.0001f
actual = new Vector2(0.01f, 0.01f); actual = new Vector2(0.01f, 0.01f);
expected = new Vector2(0.01f, 0.01f); expected = new Vector2(0.01f, 0.01f);
Assert.That(actual, Is.EqualTo(expected).Using(Vector2EqualityComparer.Instance)); Assert.That(actual, Is.EqualTo(expected).Using(Vector2EqualityComparer.Instance));
} }
} }
``` ```
# Vector3EqualityComparer # Vector3EqualityComparer
Use this class to compare two [Vector3](https://docs.unity3d.com/ScriptReference/Vector3.html) objects for equality with `NUnit` constraints. Call `Vector3EqualityComparer.Instance` comparer to perform a comparison with the default calculation error value 0.0001f. To specify a different error value, use the [one argument constructor](#constructors) to instantiate a new comparer. Use this class to compare two [Vector3](https://docs.unity3d.com/ScriptReference/Vector3.html) objects for equality with `NUnit` constraints. Call `Vector3EqualityComparer.Instance` comparer to perform a comparison with the default calculation error value 0.0001f. To specify a different error value, use the [one argument constructor](#constructors) to instantiate a new comparer.
## Static properties ## Static properties
| Syntax | Description | | Syntax | Description |
| ---------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ |
| `Instance` | A comparer instance with the default calculation error value equal to 0.0001f. | | `Instance` | A comparer instance with the default calculation error value equal to 0.0001f. |
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| --------------------------------------------- | ---------------------------------------------- | | --------------------------------------------- | ---------------------------------------------- |
| `Vector3EqualityComparer(float allowedError)` | Creates an instance with a custom error value. | | `Vector3EqualityComparer(float allowedError)` | Creates an instance with a custom error value. |
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ----------------------------------------------- | ------------------------------------------------------------ | | ----------------------------------------------- | ------------------------------------------------------------ |
| `bool Equals(Vector3 expected, Vector3 actual)` | Compares the `actual` and `expected` `Vector3` objects for equality using [Utils.AreFloatsEqual](http://todo) to compare the `x`, `y`, and `z` attributes of `Vector3`. | | `bool Equals(Vector3 expected, Vector3 actual)` | Compares the `actual` and `expected` `Vector3` objects for equality using [Utils.AreFloatsEqual](http://todo) to compare the `x`, `y`, and `z` attributes of `Vector3`. |
## Example ## Example
```c# ```c#
[TestFixture] [TestFixture]
public class Vector3Test public class Vector3Test
{ {
[Test] [Test]
public void VerifyThat_TwoVector3ObjectsAreEqual() public void VerifyThat_TwoVector3ObjectsAreEqual()
{ {
// Custom error 10e-6f // Custom error 10e-6f
var actual = new Vector3(10e-8f, 10e-8f, 10e-8f); var actual = new Vector3(10e-8f, 10e-8f, 10e-8f);
var expected = new Vector3(0f, 0f, 0f); var expected = new Vector3(0f, 0f, 0f);
var comparer = new Vector3EqualityComparer(10e-6f); var comparer = new Vector3EqualityComparer(10e-6f);
Assert.That(actual, Is.EqualTo(expected).Using(comparer)); Assert.That(actual, Is.EqualTo(expected).Using(comparer));
//Default error 0.0001f //Default error 0.0001f
actual = new Vector3(0.01f, 0.01f, 0f); actual = new Vector3(0.01f, 0.01f, 0f);
expected = new Vector3(0.01f, 0.01f, 0f); expected = new Vector3(0.01f, 0.01f, 0f);
Assert.That(actual, Is.EqualTo(expected).Using(Vector3EqualityComparer.Instance)); Assert.That(actual, Is.EqualTo(expected).Using(Vector3EqualityComparer.Instance));
} }
} }
``` ```
# Vector4EqualityComparer # Vector4EqualityComparer
Use this class to compare two [Vector4](https://docs.unity3d.com/ScriptReference/Vector4.html) objects for equality with [NUnit](http://www.nunit.org/) constraints. Call `Vector4EqualityComparer.Instance` to perform comparisons using default calculation error value 0.0001f. To set a custom test value, instantiate a new comparer using the [one argument constructor](#constructor). Use this class to compare two [Vector4](https://docs.unity3d.com/ScriptReference/Vector4.html) objects for equality with [NUnit](http://www.nunit.org/) constraints. Call `Vector4EqualityComparer.Instance` to perform comparisons using default calculation error value 0.0001f. To set a custom test value, instantiate a new comparer using the [one argument constructor](#constructor).
## Static Properties ## Static Properties
| Syntax | Description | | Syntax | Description |
| ---------------------------------- | ------------------------------------------------------------ | | ---------------------------------- | ------------------------------------------------------------ |
| `Vector4EqualityComparer Instance` | A comparer instance with the default calculation error value set to 0.0001f. | | `Vector4EqualityComparer Instance` | A comparer instance with the default calculation error value set to 0.0001f. |
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| --------------------------------------------- | ---------------------------------------------- | | --------------------------------------------- | ---------------------------------------------- |
| `Vector4EqualityComparer(float allowedError)` | Creates an instance with a custom error value. | | `Vector4EqualityComparer(float allowedError)` | Creates an instance with a custom error value. |
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------------ | ------------------------------------------------------------ |
| `bool Equals(Vector4 expected, Vector4 actual);` | Compares the `actual` and `expected` `Vector4` objects for equality using [Utils.AreFloatsEqual](http://todo) to compare the `x`, `y`, `z`, and `w` attributes of `Vector4`. | | `bool Equals(Vector4 expected, Vector4 actual);` | Compares the `actual` and `expected` `Vector4` objects for equality using [Utils.AreFloatsEqual](http://todo) to compare the `x`, `y`, `z`, and `w` attributes of `Vector4`. |
## Example ## Example
```c# ```c#
[TestFixture] [TestFixture]
public class Vector4Test public class Vector4Test
{ {
[Test] [Test]
public void VerifyThat_TwoVector4ObjectsAreEqual() public void VerifyThat_TwoVector4ObjectsAreEqual()
{ {
// Custom error 10e-6f // Custom error 10e-6f
var actual = new Vector4(0, 0, 1e-6f, 1e-6f); var actual = new Vector4(0, 0, 1e-6f, 1e-6f);
var expected = new Vector4(1e-6f, 0f, 0f, 0f); var expected = new Vector4(1e-6f, 0f, 0f, 0f);
var comparer = new Vector4EqualityComparer(10e-6f); var comparer = new Vector4EqualityComparer(10e-6f);
Assert.That(actual, Is.EqualTo(expected).Using(comparer)); Assert.That(actual, Is.EqualTo(expected).Using(comparer));
// Default error 0.0001f // Default error 0.0001f
actual = new Vector4(0.01f, 0.01f, 0f, 0f); actual = new Vector4(0.01f, 0.01f, 0f, 0f);
expected = new Vector4(0.01f, 0.01f, 0f, 0f); expected = new Vector4(0.01f, 0.01f, 0f, 0f);
Assert.That(actual, Is.EqualTo(expected).Using(Vector4EqualityComparer.Instance)); Assert.That(actual, Is.EqualTo(expected).Using(Vector4EqualityComparer.Instance));
} }
} }
``` ```
# Custom assertion # Custom assertion
A test fails if Unity logs a message other than a regular log or warning message. Use [LogAssert](#logassert) to check for an expected message in the log so that the test does not fail when Unity logs the message. A test fails if Unity logs a message other than a regular log or warning message. Use [LogAssert](#logassert) to check for an expected message in the log so that the test does not fail when Unity logs the message.
Use `LogAssert.Expect` before running the code under test, as the check for expected logs runs at the end of each frame. Use `LogAssert.Expect` before running the code under test, as the check for expected logs runs at the end of each frame.
A test also reports a failure, if an expected message does not appear, or if Unity does not log any regular log or warning messages. A test also reports a failure, if an expected message does not appear, or if Unity does not log any regular log or warning messages.
## Example ## Example
```c# ```c#
[Test] [Test]
public void LogAssertExample() public void LogAssertExample()
{ {
// Expect a regular log message // Expect a regular log message
LogAssert.Expect(LogType.Log, "Log message"); LogAssert.Expect(LogType.Log, "Log message");
// The test fails without the following expected log message // The test fails without the following expected log message
Debug.Log("Log message"); Debug.Log("Log message");
// An error log // An error log
Debug.LogError("Error message"); Debug.LogError("Error message");
// Without expecting an error log, the test would fail // Without expecting an error log, the test would fail
LogAssert.Expect(LogType.Error, "Error message"); LogAssert.Expect(LogType.Error, "Error message");
} }
``` ```
## LogAssert ## LogAssert
`LogAssert` lets you expect Unity log messages that would otherwise cause the test to fail. `LogAssert` lets you expect Unity log messages that would otherwise cause the test to fail.
### Static properties ### Static properties
| Syntax | Description | | Syntax | Description |
| ---------------------------- | ------------------------------------------------------------ | | ---------------------------- | ------------------------------------------------------------ |
| `bool ignoreFailingMessages` | Set this property to `true` to prevent unexpected error log messages from triggering an assertion. By default, it is `false`. | | `bool ignoreFailingMessages` | Set this property to `true` to prevent unexpected error log messages from triggering an assertion. By default, it is `false`. |
### Static Methods ### Static Methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `void Expect(LogType type, string message);` `void Expect(LogType type, Regex message);` | Verifies that a log message of a specified type appears in the log. A test won’t fail from an expected error, assertion, or exception log message. It does fail if an expected message does not appear in the log. | | `void Expect(LogType type, string message);` `void Expect(LogType type, Regex message);` | Verifies that a log message of a specified type appears in the log. A test won’t fail from an expected error, assertion, or exception log message. It does fail if an expected message does not appear in the log. |
| `void NoUnexpectedReceived();` | Triggers an assertion when receiving any log messages and fails the test if some are unexpected messages. If multiple tests need to check for no received unexpected logs, consider using the [TestMustExpectAllLogs](./reference-attribute-testmustexpectalllogs.md) attribute instead. | | `void NoUnexpectedReceived();` | Triggers an assertion when receiving any log messages and fails the test if some are unexpected messages. If multiple tests need to check for no received unexpected logs, consider using the [TestMustExpectAllLogs](./reference-attribute-testmustexpectalllogs.md) attribute instead. |
### Expect string message ### Expect string message
`void Expect(LogType type, string message);` `void Expect(LogType type, string message);`
#### Parameters #### Parameters
| Syntax | Description | | Syntax | Description |
| ---------------- | ------------------------------------------------------------ | | ---------------- | ------------------------------------------------------------ |
| `LogType type` | A type of log to expect. It can take one of the [LogType enum](https://docs.unity3d.com/ScriptReference/LogType.html) values. | | `LogType type` | A type of log to expect. It can take one of the [LogType enum](https://docs.unity3d.com/ScriptReference/LogType.html) values. |
| `string message` | A string value that should equate to the expected message. | | `string message` | A string value that should equate to the expected message. |
### Expect Regex message ### Expect Regex message
`void Expect(LogType type, Regex message);` `void Expect(LogType type, Regex message);`
#### Parameters #### Parameters
| Syntax | Description | | Syntax | Description |
| --------------- | ------------------------------------------------------------ | | --------------- | ------------------------------------------------------------ |
| `LogType type` | A type of log to expect. It can take one of the [LogType enum](https://docs.unity3d.com/ScriptReference/LogType.html) values. | | `LogType type` | A type of log to expect. It can take one of the [LogType enum](https://docs.unity3d.com/ScriptReference/LogType.html) values. |
| `Regex message` | A regular expression pattern to match the expected message. | | `Regex message` | A regular expression pattern to match the expected message. |
\ No newline at end of file
# Custom attributes # Custom attributes
As a part of UTF’s public API we provide the following attributes: As a part of UTF’s public API we provide the following attributes:
* [ConditionalIgnore attribute](./reference-attribute-conditionalignore.md) * [ConditionalIgnore attribute](./reference-attribute-conditionalignore.md)
* [PostBuildCleanup attribute](./reference-setup-and-cleanup.md#prebuildsetup-and-postbuildcleanup) * [PostBuildCleanup attribute](./reference-setup-and-cleanup.md#prebuildsetup-and-postbuildcleanup)
* [PrebuildSetup attribute](./reference-setup-and-cleanup.md#prebuildsetup-and-postbuildcleanup) * [PrebuildSetup attribute](./reference-setup-and-cleanup.md#prebuildsetup-and-postbuildcleanup)
* [TestMustExpectAllLogs attribute](./reference-attribute-testmustexpectalllogs.md) * [TestMustExpectAllLogs attribute](./reference-attribute-testmustexpectalllogs.md)
* [TestPlayerBuildModifier attribute](./reference-attribute-testplayerbuildmodifier.md) * [TestPlayerBuildModifier attribute](./reference-attribute-testplayerbuildmodifier.md)
* [TestRunCallback attribute](./reference-attribute-testruncallback.md) * [TestRunCallback attribute](./reference-attribute-testruncallback.md)
* [UnityPlatform attribute](./reference-attribute-unityplatform.md) * [UnityPlatform attribute](./reference-attribute-unityplatform.md)
* [UnitySetUp attribute](./reference-actions-outside-tests.md#unitysetup-and-unityteardown) * [UnitySetUp attribute](./reference-actions-outside-tests.md#unitysetup-and-unityteardown)
* [UnityTearDown attribute](./reference-actions-outside-tests.md#unitysetup-and-unityteardown) * [UnityTearDown attribute](./reference-actions-outside-tests.md#unitysetup-and-unityteardown)
* [UnityTest attribute](./reference-attribute-unitytest.md) * [UnityTest attribute](./reference-attribute-unitytest.md)
# Custom constraints # Custom constraints
`NUnit` allows you to write test assertions in a more descriptive and human readable way using the [Assert.That](https://github.com/nunit/docs/wiki/Assertions) mechanism, where the first parameter is an object under test and the second parameter describes conditions that the object has to meet. `NUnit` allows you to write test assertions in a more descriptive and human readable way using the [Assert.That](https://github.com/nunit/docs/wiki/Assertions) mechanism, where the first parameter is an object under test and the second parameter describes conditions that the object has to meet.
## Is ## Is
We’ve extended `NUnit` API with a custom constraint type and declared an overlay `Is` class. To resolve ambiguity between the original implementation and the custom one you must explicitly declare it with a using statement or via addressing through the full type name `UnityEngine.TestTools.Constraints.Is`. We’ve extended `NUnit` API with a custom constraint type and declared an overlay `Is` class. To resolve ambiguity between the original implementation and the custom one you must explicitly declare it with a using statement or via addressing through the full type name `UnityEngine.TestTools.Constraints.Is`.
### Static Methods ### Static Methods
| Syntax | Description | | Syntax | Description |
| -------------------- | ------------------------------------------------------------ | | -------------------- | ------------------------------------------------------------ |
| `AllocatingGCMemory` | A constraint type that invokes the delegate you provide as the parameter of `Assert.That` and checks whether it causes any GC memory allocations. It passes if any GC memory is allocated and fails if not. | | `AllocatingGCMemory` | A constraint type that invokes the delegate you provide as the parameter of `Assert.That` and checks whether it causes any GC memory allocations. It passes if any GC memory is allocated and fails if not. |
## Example ## Example
```c# ```c#
using Is = UnityEngine.TestTools.Constraints.Is; using Is = UnityEngine.TestTools.Constraints.Is;
class MyTestClass class MyTestClass
{ {
[Test] [Test]
public void MyTest() public void MyTest()
{ {
Assert.That(() => { Assert.That(() => {
var i = new int[500]; var i = new int[500];
}, Is.AllocatingGCMemory()); }, Is.AllocatingGCMemory());
} }
} }
``` ```
# Custom equality comparers # Custom equality comparers
To enable easier verification of custom Unity type values in your tests we provide you with some custom equality comparers: To enable easier verification of custom Unity type values in your tests we provide you with some custom equality comparers:
* [ColorEqualityComparer](./reference-comparer-color.md) * [ColorEqualityComparer](./reference-comparer-color.md)
* [FloatEqualityComparer](./reference-comparer-float.md) * [FloatEqualityComparer](./reference-comparer-float.md)
* [QuaternionEqualityComparer](./reference-comparer-quaternion.md) * [QuaternionEqualityComparer](./reference-comparer-quaternion.md)
* [Vector2EqualityComparer](./reference-comparer-vector2.md) * [Vector2EqualityComparer](./reference-comparer-vector2.md)
* [Vector3EqualityComparer](./reference-comparer-vector3.md) * [Vector3EqualityComparer](./reference-comparer-vector3.md)
* [Vector4EqualityComparer](./reference-comparer-vector4.md) * [Vector4EqualityComparer](./reference-comparer-vector4.md)
Use these classes to compare two objects of the same type for equality within the range of a given tolerance using [NUnit ](https://github.com/nunit/docs/wiki/Constraints)or [custom constraints](./reference-custom-constraints.md) . Call Instance to apply the default calculation error value to the comparison. To set a specific error value, instantiate a new comparer object using a one argument constructor `ctor(float error)`. Use these classes to compare two objects of the same type for equality within the range of a given tolerance using [NUnit ](https://github.com/nunit/docs/wiki/Constraints)or [custom constraints](./reference-custom-constraints.md) . Call Instance to apply the default calculation error value to the comparison. To set a specific error value, instantiate a new comparer object using a one argument constructor `ctor(float error)`.
## Static properties ## Static properties
| Syntax | Description | | Syntax | Description |
| ---------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ |
| `Instance` | A singleton instance of the comparer with a predefined default error value. | | `Instance` | A singleton instance of the comparer with a predefined default error value. |
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| ------------------- | ------------------------------------------------------------ | | ------------------- | ------------------------------------------------------------ |
| `ctor(float error)` | Creates an instance of comparer with a custom error `value.allowedError`. The relative error to be considered while comparing two values. | | `ctor(float error)` | Creates an instance of comparer with a custom error `value.allowedError`. The relative error to be considered while comparing two values. |
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------ | ------------------------------------------------------------ | | ------------------------------------ | ------------------------------------------------------------ |
| `bool Equals(T expected, T actual);` | Compares the actual and expected objects for equality using a custom comparison mechanism. Returns `true` if expected and actual objects are equal, otherwise it returns `false`. | | `bool Equals(T expected, T actual);` | Compares the actual and expected objects for equality using a custom comparison mechanism. Returns `true` if expected and actual objects are equal, otherwise it returns `false`. |
# Custom yield instructions # Custom yield instructions
By implementing this interface below, you can define custom yield instructions in **Edit Mode** tests. By implementing this interface below, you can define custom yield instructions in **Edit Mode** tests.
## IEditModeTestYieldInstruction ## IEditModeTestYieldInstruction
In an Edit Mode test, you can use `IEditModeTestYieldInstruction` interface to implement your own instruction. There are also a couple of commonly used implementations available: In an Edit Mode test, you can use `IEditModeTestYieldInstruction` interface to implement your own instruction. There are also a couple of commonly used implementations available:
- [EnterPlayMode](#enterplaymode) - [EnterPlayMode](#enterplaymode)
- [ExitPlayMode](#exitplaymode) - [ExitPlayMode](#exitplaymode)
- [RecompileScripts](./reference-recompile-scripts.md) - [RecompileScripts](./reference-recompile-scripts.md)
- [WaitForDomainReload](./reference-wait-for-domain-reload.md) - [WaitForDomainReload](./reference-wait-for-domain-reload.md)
## Example ## Example
```c# ```c#
[UnityTest] [UnityTest]
public IEnumerator PlayOnAwakeDisabled_DoesntPlayWhenEnteringPlayMode() public IEnumerator PlayOnAwakeDisabled_DoesntPlayWhenEnteringPlayMode()
{ {
var videoPlayer = PrefabUtility.InstantiatePrefab(m_VideoPlayerPrefab.GetComponent<VideoPlayer>()) as VideoPlayer; var videoPlayer = PrefabUtility.InstantiatePrefab(m_VideoPlayerPrefab.GetComponent<VideoPlayer>()) as VideoPlayer;
videoPlayer.playOnAwake = false; videoPlayer.playOnAwake = false;
yield return new EnterPlayMode(); yield return new EnterPlayMode();
var videoPlayerGO = GameObject.Find(m_VideoPlayerPrefab.name); var videoPlayerGO = GameObject.Find(m_VideoPlayerPrefab.name);
Assert.IsFalse(videoPlayerGO.GetComponent<VideoPlayer>().isPlaying); Assert.IsFalse(videoPlayerGO.GetComponent<VideoPlayer>().isPlaying);
yield return new ExitPlayMode(); yield return new ExitPlayMode();
Object.DestroyImmediate(GameObject.Find(m_VideoPlayerPrefab.name)); Object.DestroyImmediate(GameObject.Find(m_VideoPlayerPrefab.name));
} }
``` ```
## Properties ## Properties
| Syntax | Description | | Syntax | Description |
| ---------------------------- | ------------------------------------------------------------ | | ---------------------------- | ------------------------------------------------------------ |
| `bool ExpectDomainReload` | Returns `true` if the instruction expects a domain reload to occur. | | `bool ExpectDomainReload` | Returns `true` if the instruction expects a domain reload to occur. |
| `bool ExpectedPlaymodeState` | Returns `true` if the instruction expects the Unity Editor to be in **Play Mode**. | | `bool ExpectedPlaymodeState` | Returns `true` if the instruction expects the Unity Editor to be in **Play Mode**. |
## Methods ## Methods
| Syntax | Description | | Syntax | Description |
| ----------------------- | ------------------------------------------------------------ | | ----------------------- | ------------------------------------------------------------ |
| `IEnumerator Perform()` | Used to define multi-frame operations performed when instantiating a yield instruction. | | `IEnumerator Perform()` | Used to define multi-frame operations performed when instantiating a yield instruction. |
## EnterPlayMode ## EnterPlayMode
* Implements `IEditModeTestYieldInstruction`. Creates a yield instruction to enter Play Mode. * Implements `IEditModeTestYieldInstruction`. Creates a yield instruction to enter Play Mode.
* When creating an Editor test that uses the `UnityTest` attribute, use this to trigger the Editor to enter Play Mode. * When creating an Editor test that uses the `UnityTest` attribute, use this to trigger the Editor to enter Play Mode.
* Throws an exception if the Editor is already in Play Mode or if there is a [script compilation error](https://support.unity3d.com/hc/en-us/articles/205930539-How-do-I-interpret-a-compiler-error-). * Throws an exception if the Editor is already in Play Mode or if there is a [script compilation error](https://support.unity3d.com/hc/en-us/articles/205930539-How-do-I-interpret-a-compiler-error-).
## ExitPlayMode ## ExitPlayMode
* Implements `IEditModeTestYieldInstruction`. A new instance of the class is a yield instruction to exit Play Mode. * Implements `IEditModeTestYieldInstruction`. A new instance of the class is a yield instruction to exit Play Mode.
* Throws an exception if the Editor is not in Play Mode. * Throws an exception if the Editor is not in Play Mode.
# ExecutionSettings # ExecutionSettings
The `ExecutionSettings` is a set of filters and other settings provided when running a set of tests from the [TestRunnerApi](./reference-test-runner-api.md). The `ExecutionSettings` is a set of filters and other settings provided when running a set of tests from the [TestRunnerApi](./reference-test-runner-api.md).
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| ----------------------------------------------------- | -------------------------------------------------------- | | ----------------------------------------------------- | -------------------------------------------------------- |
| `ExecutionSettings(params Filter[] filtersToExecute)` | Creates an instance with a given set of filters, if any. | | `ExecutionSettings(params Filter[] filtersToExecute)` | Creates an instance with a given set of filters, if any. |
## Fields ## Fields
| Syntax | Description | | Syntax | Description |
| ---------------------------- | ------------------------------------------------------------ | | ---------------------------- | ------------------------------------------------------------ |
| `Filter[] filters` | A collection of [Filters](./reference-filter.md) to execute tests on. | | `Filter[] filters` | A collection of [Filters](./reference-filter.md) to execute tests on. |
| `ITestRunSettings overloadTestRunSettings` | An instance of [ITestRunSettings](./reference-itest-run-settings.md) to set up before running tests on a Player. | | `ITestRunSettings overloadTestRunSettings` | An instance of [ITestRunSettings](./reference-itest-run-settings.md) to set up before running tests on a Player. |
| `bool runSynchronously` | If true, the call to `Execute()` will run tests synchronously, guaranteeing that all tests have finished running by the time the call returns. Note that this is only supported for EditMode tests, and that tests which take multiple frames (i.e. `[UnityTest]` tests, or tests with `[UnitySetUp]` or `[UnityTearDown]` scaffolding) will be filtered out. | | `bool runSynchronously` | If true, the call to `Execute()` will run tests synchronously, guaranteeing that all tests have finished running by the time the call returns. Note that this is only supported for EditMode tests, and that tests which take multiple frames (i.e. `[UnityTest]` tests, or tests with `[UnitySetUp]` or `[UnityTearDown]` scaffolding) will be filtered out. |
| 'int playerHeartbeatTimeout' | The time, in seconds, the editor should wait for heartbeats after starting a test run on a player. This defaults to 10 minutes. | | 'int playerHeartbeatTimeout' | The time, in seconds, the editor should wait for heartbeats after starting a test run on a player. This defaults to 10 minutes. |
\ No newline at end of file
# Filter # Filter
The filter class provides the [TestRunnerApi](./reference-test-runner-api.md) with a specification of what tests to run when [running tests programmatically](./extension-run-tests.md). The filter class provides the [TestRunnerApi](./reference-test-runner-api.md) with a specification of what tests to run when [running tests programmatically](./extension-run-tests.md).
## Fields ## Fields
| Syntax | Description | | Syntax | Description |
| ----------------------------- | ------------------------------------------------------------ | | ----------------------------- | ------------------------------------------------------------ |
| `TestMode testMode` | An enum flag that specifies if **Edit Mode** or **Play Mode** tests should run. Applying both Edit Mode and Play Mode is currently not supported when running tests from the API. | | `TestMode testMode` | An enum flag that specifies if **Edit Mode** or **Play Mode** tests should run. Applying both Edit Mode and Play Mode is currently not supported when running tests from the API. |
| `string[] testNames` | The full name of the tests to match the filter. This is usually in the format `FixtureName.TestName`. If the test has test arguments, then include them in parenthesis. E.g. `MyTestClass2.MyTestWithMultipleValues(1)`. | | `string[] testNames` | The full name of the tests to match the filter. This is usually in the format `FixtureName.TestName`. If the test has test arguments, then include them in parenthesis. E.g. `MyTestClass2.MyTestWithMultipleValues(1)`. |
| `string[] groupNames` | The same as `testNames`, except that it allows for Regex. This is useful for running specific fixtures or namespaces. E.g. `"^MyNamespace\\."` Runs any tests where the top namespace is `MyNamespace`. | | `string[] groupNames` | The same as `testNames`, except that it allows for Regex. This is useful for running specific fixtures or namespaces. E.g. `"^MyNamespace\\."` Runs any tests where the top namespace is `MyNamespace`. |
| `string[] categoryNames` | The name of a [Category](https://nunit.org/docs/2.2.7/category.html) to include in the run. Any test or fixtures runs that have a `Category` matching the string. | | `string[] categoryNames` | The name of a [Category](https://nunit.org/docs/2.2.7/category.html) to include in the run. Any test or fixtures runs that have a `Category` matching the string. |
| `string[] assemblyNames` | The name of assemblies included in the run. That is the assembly name, without the .dll file extension. E.g., `MyTestAssembly`. | | `string[] assemblyNames` | The name of assemblies included in the run. That is the assembly name, without the .dll file extension. E.g., `MyTestAssembly`. |
| `BuildTarget? targetPlatform` | The [BuildTarget](https://docs.unity3d.com/ScriptReference/BuildTarget.html) platform to run the test on. If set to `null`, then the Editor is the target for the tests. | | `BuildTarget? targetPlatform` | The [BuildTarget](https://docs.unity3d.com/ScriptReference/BuildTarget.html) platform to run the test on. If set to `null`, then the Editor is the target for the tests. |
# ICallbacks # ICallbacks
An interface for receiving callbacks when running tests. All test runs invoke the callbacks until the next domain reload. An interface for receiving callbacks when running tests. All test runs invoke the callbacks until the next domain reload.
The `RunStarted` method runs when the whole test run starts. Then the `TestStarted` method runs with information about the tests it is about to run on an assembly level. Afterward, it runs on a test fixture level and then on the individual test. If the test is a [parameterized test](./https://github.com/nunit/docs/wiki/Parameterized-Tests), then it is also invoked for each parameter combination. After each part of the test tree have completed running, the corresponding `TestFinished` method runs with the test result. At the end of the run, the `RunFinished` event runs with the test result. The `RunStarted` method runs when the whole test run starts. Then the `TestStarted` method runs with information about the tests it is about to run on an assembly level. Afterward, it runs on a test fixture level and then on the individual test. If the test is a [parameterized test](./https://github.com/nunit/docs/wiki/Parameterized-Tests), then it is also invoked for each parameter combination. After each part of the test tree have completed running, the corresponding `TestFinished` method runs with the test result. At the end of the run, the `RunFinished` event runs with the test result.
An extended version of the callback, [IErrorCallbacks](./reference-ierror-callbacks.md), extends this `ICallbacks` to receive calls when a run fails due to a build error. An extended version of the callback, [IErrorCallbacks](./reference-ierror-callbacks.md), extends this `ICallbacks` to receive calls when a run fails due to a build error.
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ---------------------------------------------- | ------------------------------------------------------------ | | ---------------------------------------------- | ------------------------------------------------------------ |
| `void RunStarted(ITestAdaptor testsToRun)` | Invoked when the test run starts. The [ITestAdaptor](./reference-itest-adaptor.md) represents the tree of tests to run. | | `void RunStarted(ITestAdaptor testsToRun)` | Invoked when the test run starts. The [ITestAdaptor](./reference-itest-adaptor.md) represents the tree of tests to run. |
| `void RunFinished(ITestResultAdaptor result)` | Invoked when the test run finishes. The [ITestResultAdaptor](./reference-itest-result-adaptor.md) represents the results of the set of tests that have run. | | `void RunFinished(ITestResultAdaptor result)` | Invoked when the test run finishes. The [ITestResultAdaptor](./reference-itest-result-adaptor.md) represents the results of the set of tests that have run. |
| `void TestStarted(ITestAdaptor test)` | Invoked on each node of the test tree, as that part of the tree starts to run. | | `void TestStarted(ITestAdaptor test)` | Invoked on each node of the test tree, as that part of the tree starts to run. |
| `void TestFinished(ITestResultAdaptor result)` | Invoked on each node of the test tree once that part of the test tree has finished running. The [ITestResultAdaptor](./reference-itest-result-adaptor.md) represents the results of the current node of the test tree. | | `void TestFinished(ITestResultAdaptor result)` | Invoked on each node of the test tree once that part of the test tree has finished running. The [ITestResultAdaptor](./reference-itest-result-adaptor.md) represents the results of the current node of the test tree. |
## Example ## Example
An example that sets up a listener on the API. The listener prints the number of failed tests after the run has finished: An example that sets up a listener on the API. The listener prints the number of failed tests after the run has finished:
``` C# ``` C#
public void SetupListeners() public void SetupListeners()
{ {
var api = ScriptableObject.CreateInstance<TestRunnerApi>(); var api = ScriptableObject.CreateInstance<TestRunnerApi>();
api.RegisterCallbacks(new MyCallbacks()); api.RegisterCallbacks(new MyCallbacks());
} }
private class MyCallbacks : ICallbacks private class MyCallbacks : ICallbacks
{ {
public void RunStarted(ITestAdaptor testsToRun) public void RunStarted(ITestAdaptor testsToRun)
{ {
} }
public void RunFinished(ITestResultAdaptor result) public void RunFinished(ITestResultAdaptor result)
{ {
Debug.Log(string.Format("Run finished {0} test(s) failed.", result.FailCount)); Debug.Log(string.Format("Run finished {0} test(s) failed.", result.FailCount));
} }
public void TestStarted(ITestAdaptor test) public void TestStarted(ITestAdaptor test)
{ {
} }
public void TestFinished(ITestResultAdaptor result) public void TestFinished(ITestResultAdaptor result)
{ {
} }
} }
``` ```
\ No newline at end of file
# IErrorCallbacks # IErrorCallbacks
An extended version of the [ICallbacks](./reference-icallbacks.md), which get invoked if the test run fails due to a build error or if any [IPrebuildSetup](./reference-setup-and-cleanup.md) has a failure. An extended version of the [ICallbacks](./reference-icallbacks.md), which get invoked if the test run fails due to a build error or if any [IPrebuildSetup](./reference-setup-and-cleanup.md) has a failure.
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ---------------------------- | ------------------------------------------------------------------- | | ---------------------------- | ------------------------------------------------------------------- |
| void OnError(string message) | The error message detailing the reason for the run to fail. | | void OnError(string message) | The error message detailing the reason for the run to fail. |
# ITestAdaptor # ITestAdaptor
`ITestAdaptor` is a representation of a node in the test tree implemented as a wrapper around the [NUnit](http://www.nunit.org/) [ITest](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITest.cs) interface. `ITestAdaptor` is a representation of a node in the test tree implemented as a wrapper around the [NUnit](http://www.nunit.org/) [ITest](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITest.cs) interface.
## Properties ## Properties
| Syntax | Description | | Syntax | Description |
| ---------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ |
| `string Id` | The ID of the test tree node. The ID can change if you add new tests to the suite. Use `UniqueName`, if you want to have a more permanent point of reference. | | `string Id` | The ID of the test tree node. The ID can change if you add new tests to the suite. Use `UniqueName`, if you want to have a more permanent point of reference. |
| `string Name` | The name of the test. E.g., `MyTest`. | | `string Name` | The name of the test. E.g., `MyTest`. |
| `string FullName` | The full name of the test. E.g., `MyNamespace.MyTestClass.MyTest`. | | `string FullName` | The full name of the test. E.g., `MyNamespace.MyTestClass.MyTest`. |
| `int TestCaseCount` | The total number of test cases in the node and all sub-nodes. | | `int TestCaseCount` | The total number of test cases in the node and all sub-nodes. |
| `bool HasChildren` | Whether the node has any children. | | `bool HasChildren` | Whether the node has any children. |
| `bool IsSuite` | Whether the node is a test suite/fixture. | | `bool IsSuite` | Whether the node is a test suite/fixture. |
| `IEnumerable<ITestAdaptor> Children` | The child nodes. | | `IEnumerable<ITestAdaptor> Children` | The child nodes. |
| `ITestAdaptor Parent` | The parent node, if any. | | `ITestAdaptor Parent` | The parent node, if any. |
| `int TestCaseTimeout` | The test case timeout in milliseconds. Note that this value is only available on TestFinished. | | `int TestCaseTimeout` | The test case timeout in milliseconds. Note that this value is only available on TestFinished. |
| `ITypeInfo TypeInfo` | The type of test class as an `NUnit` [ITypeInfo](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITypeInfo.cs). If the node is not a test class, then the value is `null`. | | `ITypeInfo TypeInfo` | The type of test class as an `NUnit` [ITypeInfo](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITypeInfo.cs). If the node is not a test class, then the value is `null`. |
| `IMethodInfo Method` | The [Nunit IMethodInfo](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) of the test method. If the node is not a test method, then the value is `null`. | | `IMethodInfo Method` | The [Nunit IMethodInfo](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/IMethodInfo.cs) of the test method. If the node is not a test method, then the value is `null`. |
| `string[] Categories` | An array of the categories applied to the test or fixture. | | `string[] Categories` | An array of the categories applied to the test or fixture. |
| `bool IsTestAssembly` | Whether the node represents a test assembly. | | `bool IsTestAssembly` | Whether the node represents a test assembly. |
| `RunState RunState` | The run state of the test node. Either `NotRunnable`, `Runnable`, `Explicit`, `Skipped`, or `Ignored`. | | `RunState RunState` | The run state of the test node. Either `NotRunnable`, `Runnable`, `Explicit`, `Skipped`, or `Ignored`. |
| `string Description` | The description of the test. | | `string Description` | The description of the test. |
| `string SkipReason` | The skip reason. E.g., if ignoring the test. | | `string SkipReason` | The skip reason. E.g., if ignoring the test. |
| `string ParentId` | The ID of the parent node. | | `string ParentId` | The ID of the parent node. |
| `string ParentFullName` | The full name of the parent node. | | `string ParentFullName` | The full name of the parent node. |
| `string UniqueName` | A unique generated name for the test node. E.g., `Tests.dll/MyNamespace/MyTestClass/[Tests][MyNamespace.MyTestClass.MyTest]`. | | `string UniqueName` | A unique generated name for the test node. E.g., `Tests.dll/MyNamespace/MyTestClass/[Tests][MyNamespace.MyTestClass.MyTest]`. |
| `string ParentUniqueName` | A unique name of the parent node. E.g., `Tests.dll/MyNamespace/[Tests][MyNamespace.MyTestClass][suite]`. | | `string ParentUniqueName` | A unique name of the parent node. E.g., `Tests.dll/MyNamespace/[Tests][MyNamespace.MyTestClass][suite]`. |
| `int ChildIndex` | The child index of the node in its parent. | | `int ChildIndex` | The child index of the node in its parent. |
| `TestMode TestMode` | The mode of the test. Either **Edit Mode** or **Play Mode**. | | `TestMode TestMode` | The mode of the test. Either **Edit Mode** or **Play Mode**. |
> **Note**: Some properties are not available when receiving the test tree as a part of a test result coming from a standalone Player, such as `TypeInfo` and `Method`. > **Note**: Some properties are not available when receiving the test tree as a part of a test result coming from a standalone Player, such as `TypeInfo` and `Method`.
\ No newline at end of file
# ITestResultAdaptor # ITestResultAdaptor
The `ITestResultAdaptor` is the representation of the test results for a node in the test tree implemented as a wrapper around the [NUnit](http://www.nunit.org/) [ITest](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITestResults.cs) interface. The `ITestResultAdaptor` is the representation of the test results for a node in the test tree implemented as a wrapper around the [NUnit](http://www.nunit.org/) [ITest](https://github.com/nunit/nunit/blob/master/src/NUnitFramework/framework/Interfaces/ITestResults.cs) interface.
## Properties ## Properties
| Syntax | Description | | Syntax | Description |
| ---------- | ------------------------------------------------------------ | | ---------- | ------------------------------------------------------------ |
| `ITestAdaptor Test` | The test details of the test result tree node as a [TestAdaptor](./reference-itest-adaptor.md). | | `ITestAdaptor Test` | The test details of the test result tree node as a [TestAdaptor](./reference-itest-adaptor.md). |
| `string Name` | The name of the test node. | | `string Name` | The name of the test node. |
| `string FullName` | Gets the full name of the test result | | `string FullName` | Gets the full name of the test result |
| `string ResultState` | The state of the result as a string. E.g., `Success`, `Skipped`, `Failure`, `Explicit`, `Cancelled`. | | `string ResultState` | The state of the result as a string. E.g., `Success`, `Skipped`, `Failure`, `Explicit`, `Cancelled`. |
| `TestStatus TestStatus` | The status of the test as an enum. Either `Inconclusive`, `Skipped`, `Passed`, or `Failed`. | | `TestStatus TestStatus` | The status of the test as an enum. Either `Inconclusive`, `Skipped`, `Passed`, or `Failed`. |
| `double Duration` | Gets the elapsed time for running the test in seconds. | | `double Duration` | Gets the elapsed time for running the test in seconds. |
| `DateTime StartTime` | Gets or sets the time the test started running. | | `DateTime StartTime` | Gets or sets the time the test started running. |
| `DateTime EndTime` | Gets or sets the time the test finished running. | | `DateTime EndTime` | Gets or sets the time the test finished running. |
| `string Message` | Gets the message associated with a test failure or with not running the test | | `string Message` | Gets the message associated with a test failure or with not running the test |
| `string StackTrace` | Gets any stack trace associated with an error or failure. Not available in the [Compact Framework](https://en.wikipedia.org/wiki/.NET_Compact_Framework) 1.0. | | `string StackTrace` | Gets any stack trace associated with an error or failure. Not available in the [Compact Framework](https://en.wikipedia.org/wiki/.NET_Compact_Framework) 1.0. |
| `int AssertCount` | Gets the number of asserts that ran during the test and all its children. | | `int AssertCount` | Gets the number of asserts that ran during the test and all its children. |
| `int FailCount` | Gets the number of test cases that failed when running the test and all its children. | | `int FailCount` | Gets the number of test cases that failed when running the test and all its children. |
| `int PassCount` | Gets the number of test cases that passed when running the test and all its children. | | `int PassCount` | Gets the number of test cases that passed when running the test and all its children. |
| `int SkipCount` | Gets the number of test cases skipped when running the test and all its children. | | `int SkipCount` | Gets the number of test cases skipped when running the test and all its children. |
| `int InconclusiveCount` | Gets the number of test cases that were inconclusive when running the test and all its children. | | `int InconclusiveCount` | Gets the number of test cases that were inconclusive when running the test and all its children. |
| `bool HasChildren` | Indicates whether this result has any child results. Accessing HasChildren should not force the creation of the Children collection in classes implementing this interface. | | `bool HasChildren` | Indicates whether this result has any child results. Accessing HasChildren should not force the creation of the Children collection in classes implementing this interface. |
| `IEnumerable<ITestResultAdaptor> Children` | Gets the collection of child results. | | `IEnumerable<ITestResultAdaptor> Children` | Gets the collection of child results. |
| `string Output` | Gets any text output written to this result. | | `string Output` | Gets any text output written to this result. |
| `TNode ToXml` | Gets the test results as an `NUnit` XML node. Use this to save the results to an XML file. | | `TNode ToXml` | Gets the test results as an `NUnit` XML node. Use this to save the results to an XML file. |
# ITestRunSettings # ITestRunSettings
`ITestRunSettings` lets you set any of the global settings right before building a Player for a test run and then reverts the settings afterward. `ITestRunSettings` lets you set any of the global settings right before building a Player for a test run and then reverts the settings afterward.
`ITestRunSettings` implements [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable), and runs after building the Player with tests. `ITestRunSettings` implements [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable), and runs after building the Player with tests.
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ---------------- | ------------------------------------------------------------ | | ---------------- | ------------------------------------------------------------ |
| `void Apply()` | A method called before building the Player. | | `void Apply()` | A method called before building the Player. |
| `void Dispose()` | A method called after building the Player or if the build failed. | | `void Dispose()` | A method called after building the Player or if the build failed. |
## Example ## Example
The following example sets the iOS SDK version to be the simulator SDK and resets it to the original value after the run. The following example sets the iOS SDK version to be the simulator SDK and resets it to the original value after the run.
``` C# ``` C#
public class MyTestSettings : ITestRunSettings public class MyTestSettings : ITestRunSettings
{ {
private iOSSdkVersion originalSdkVersion; private iOSSdkVersion originalSdkVersion;
public void Apply() public void Apply()
{ {
originalSdkVersion = PlayerSettings.iOS.sdkVersion; originalSdkVersion = PlayerSettings.iOS.sdkVersion;
PlayerSettings.iOS.sdkVersion = iOSSdkVersion.SimulatorSDK; PlayerSettings.iOS.sdkVersion = iOSSdkVersion.SimulatorSDK;
} }
public void Dispose() public void Dispose()
{ {
PlayerSettings.iOS.sdkVersion = originalSdkVersion; PlayerSettings.iOS.sdkVersion = originalSdkVersion;
} }
} }
``` ```
\ No newline at end of file
# RecompileScripts # RecompileScripts
`RecompileScripts` is an [IEditModeTestYieldInstruction](./reference-custom-yield-instructions.md) that you can yield in Edit Mode tests. It lets you trigger a recompilation of scripts in the Unity Editor. `RecompileScripts` is an [IEditModeTestYieldInstruction](./reference-custom-yield-instructions.md) that you can yield in Edit Mode tests. It lets you trigger a recompilation of scripts in the Unity Editor.
## Constructors ## Constructors
| Syntax | Description | | Syntax | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `RecompileScripts(bool expectScriptCompilation = true, bool expectScriptCompilationSuccess = true)` | Creates a new instance of the `RecompileScripts` yield instruction. The parameter `expectScriptCompilation` indicates if you expect a script compilation to start (defaults to true). If a script compilation does not start and `expectScriptCompilation` is `true`, then it throws an exception. | | `RecompileScripts(bool expectScriptCompilation = true, bool expectScriptCompilationSuccess = true)` | Creates a new instance of the `RecompileScripts` yield instruction. The parameter `expectScriptCompilation` indicates if you expect a script compilation to start (defaults to true). If a script compilation does not start and `expectScriptCompilation` is `true`, then it throws an exception. |
## Example ## Example
``` C@ ``` C@
[UnitySetUp] [UnitySetUp]
public IEnumerator SetUp() public IEnumerator SetUp()
{ {
using (var file = File.CreateText("Assets/temp/myScript.cs")) using (var file = File.CreateText("Assets/temp/myScript.cs"))
{ {
file.Write("public class ATempClass { }"); file.Write("public class ATempClass { }");
} }
AssetDatabase.Refresh(); AssetDatabase.Refresh();
yield return new RecompileScripts(); yield return new RecompileScripts();
} }
``` ```
\ No newline at end of file
# Setup and cleanup at build time # Setup and cleanup at build time
In some cases, it is relevant to perform changes to Unity or the file system before building the tests. In the same way, it may be necessary to clean up such changes after the test run. In response to such needs, you can incorporate the pre-build setup and post-build cleanup concepts into your tests in one of the following ways: In some cases, it is relevant to perform changes to Unity or the file system before building the tests. In the same way, it may be necessary to clean up such changes after the test run. In response to such needs, you can incorporate the pre-build setup and post-build cleanup concepts into your tests in one of the following ways:
1. Via implementation of `IPrebuildSetup` and `IPostBuildCleanup` interfaces by a test class. 1. Via implementation of `IPrebuildSetup` and `IPostBuildCleanup` interfaces by a test class.
2. Via applying the `PrebuildSetup` attribute and `PostBuildCleanup` attribute on your test class, one of the tests or the test assembly, providing a class name that implements the corresponding interface as an argument (fx `[PrebuildSetup("MyTestSceneSetup")]`). 2. Via applying the `PrebuildSetup` attribute and `PostBuildCleanup` attribute on your test class, one of the tests or the test assembly, providing a class name that implements the corresponding interface as an argument (fx `[PrebuildSetup("MyTestSceneSetup")]`).
## Execution order ## Execution order
All setups run in a deterministic order one after another. The first to run are the setups defined with attributes. Then any test class implementing the interface runs, in alphabetical order inside their namespace, which is the same order as the tests run. All setups run in a deterministic order one after another. The first to run are the setups defined with attributes. Then any test class implementing the interface runs, in alphabetical order inside their namespace, which is the same order as the tests run.
> **Note**: Cleanup runs right away for a standalone test run, but only after related tests run in the Unity Editor. > **Note**: Cleanup runs right away for a standalone test run, but only after related tests run in the Unity Editor.
## PrebuildSetup and PostBuildCleanup ## PrebuildSetup and PostBuildCleanup
Both `PrebuildSetup` and `PostBuildCleanup` attributes run if the respective test or test class is in the current test run. The test is included either by running all tests or setting a [filter](./workflow-create-test.md#filters) that includes the test. If multiple tests reference the same pre-built setup or post-build cleanup, then it only runs once. Both `PrebuildSetup` and `PostBuildCleanup` attributes run if the respective test or test class is in the current test run. The test is included either by running all tests or setting a [filter](./workflow-create-test.md#filters) that includes the test. If multiple tests reference the same pre-built setup or post-build cleanup, then it only runs once.
## IPrebuildSetup ## IPrebuildSetup
Implement this interface if you want to define a set of actions to run as a pre-build step. Implement this interface if you want to define a set of actions to run as a pre-build step.
### Public methods ### Public methods
| Syntax | Description | | Syntax | Description |
| -------------- | ------------------------------------------------------------ | | -------------- | ------------------------------------------------------------ |
| `void Setup()` | Implement this method to call actions automatically before the build process. | | `void Setup()` | Implement this method to call actions automatically before the build process. |
## IPostBuildCleanup ## IPostBuildCleanup
Implement this interface if you want to define a set of actions to execute as a post-build step. Cleanup runs right away for a standalone test run, but only after all the tests run within the Editor. Implement this interface if you want to define a set of actions to execute as a post-build step. Cleanup runs right away for a standalone test run, but only after all the tests run within the Editor.
### Public methods ### Public methods
| Syntax | Description | | Syntax | Description |
| ---------------- | ------------------------------------------------------------ | | ---------------- | ------------------------------------------------------------ |
| `void Cleanup()` | Implement this method to specify actions that should run as a post-build cleanup step. | | `void Cleanup()` | Implement this method to specify actions that should run as a post-build cleanup step. |
## Example ## Example
```c# ```c#
[TestFixture] [TestFixture]
public class CreateSpriteTest : IPrebuildSetup public class CreateSpriteTest : IPrebuildSetup
{ {
Texture2D m_Texture; Texture2D m_Texture;
Sprite m_Sprite; Sprite m_Sprite;
public void Setup() public void Setup()
{ {
#if UNITY_EDITOR #if UNITY_EDITOR
var spritePath = "Assets/Resources/Circle.png"; var spritePath = "Assets/Resources/Circle.png";
var ti = UnityEditor.AssetImporter.GetAtPath(spritePath) as UnityEditor.TextureImporter; var ti = UnityEditor.AssetImporter.GetAtPath(spritePath) as UnityEditor.TextureImporter;
ti.textureCompression = UnityEditor.TextureImporterCompression.Uncompressed; ti.textureCompression = UnityEditor.TextureImporterCompression.Uncompressed;
ti.SaveAndReimport(); ti.SaveAndReimport();
#endif #endif
} }
[SetUp] [SetUp]
public void SetUpTest() public void SetUpTest()
{ {
m_Texture = Resources.Load<Texture2D>("Circle"); m_Texture = Resources.Load<Texture2D>("Circle");
} }
[Test] [Test]
public void WhenNullTextureIsPassed_CreateShouldReturnNullSprite() public void WhenNullTextureIsPassed_CreateShouldReturnNullSprite()
{ {
// Check with Valid Texture. // Check with Valid Texture.
LogAssert.Expect(LogType.Log, "Circle Sprite Created"); LogAssert.Expect(LogType.Log, "Circle Sprite Created");
Sprite.Create(m_Texture, new Rect(0, 0, m_Texture.width, m_Texture.height), new Vector2(0.5f, 0.5f)); Sprite.Create(m_Texture, new Rect(0, 0, m_Texture.width, m_Texture.height), new Vector2(0.5f, 0.5f));
Debug.Log("Circle Sprite Created"); Debug.Log("Circle Sprite Created");
// Check with NULL Texture. Should return NULL Sprite. // Check with NULL Texture. Should return NULL Sprite.
m_Sprite = Sprite.Create(null, new Rect(0, 0, m_Texture.width, m_Texture.heig`t), new Vector2(0.5f, 0.5f)); m_Sprite = Sprite.Create(null, new Rect(0, 0, m_Texture.width, m_Texture.heig`t), new Vector2(0.5f, 0.5f));
Assert.That(m_Sprite, Is.Null, "Sprite created with null texture should be null"); Assert.That(m_Sprite, Is.Null, "Sprite created with null texture should be null");
} }
} }
``` ```
> **Tip**: Use `#if UNITY_EDITOR` if you want to access Editor only APIs, but the setup/cleanup is inside a **Play Mode** assembly. > **Tip**: Use `#if UNITY_EDITOR` if you want to access Editor only APIs, but the setup/cleanup is inside a **Play Mode** assembly.
# TestRunnerApi # TestRunnerApi
The `TestRunnerApi` retrieves and runs tests programmatically from code inside the project, or inside other packages. `TestRunnerApi` is a [ScriptableObject](https://docs.unity3d.com/ScriptReference/ScriptableObject.html). The `TestRunnerApi` retrieves and runs tests programmatically from code inside the project, or inside other packages. `TestRunnerApi` is a [ScriptableObject](https://docs.unity3d.com/ScriptReference/ScriptableObject.html).
You can initialize the API like this: You can initialize the API like this:
```c# ```c#
var testRunnerApi = ScriptableObject.CreateInstance<TestRunnerApi>(); var testRunnerApi = ScriptableObject.CreateInstance<TestRunnerApi>();
``` ```
> **Note**: You can subscribe and receive test results in one instance of the API, even if the run starts from another instance. > **Note**: You can subscribe and receive test results in one instance of the API, even if the run starts from another instance.
The `TestRunnerApi` supports the following workflows: The `TestRunnerApi` supports the following workflows:
* [How to run tests programmatically](./extension-run-tests.md) * [How to run tests programmatically](./extension-run-tests.md)
* [How to get test results](./extension-get-test-results.md) * [How to get test results](./extension-get-test-results.md)
* [How to retrieve the list of tests](./extension-retrieve-test-list.md) * [How to retrieve the list of tests](./extension-retrieve-test-list.md)
## Public methods ## Public methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------ | ------------------------------------------------------------ |
| `void Execute(ExecutionSettings executionSettings)` | Starts a test run with a given set of [ExecutionSettings](./reference-execution-settings.md). | | `void Execute(ExecutionSettings executionSettings)` | Starts a test run with a given set of [ExecutionSettings](./reference-execution-settings.md). |
| `void RegisterCallbacks(ICallbacks testCallbacks, int priority = 0)` | Sets up a given instance of [ICallbacks](./reference-icallbacks.md) to be invoked on test runs. | | `void RegisterCallbacks(ICallbacks testCallbacks, int priority = 0)` | Sets up a given instance of [ICallbacks](./reference-icallbacks.md) to be invoked on test runs. |
| `void UnregisterCallbacks(ICallbacks testCallbacks)` | Unregisters an instance of ICallbacks to no longer receive callbacks from test runs. | | `void UnregisterCallbacks(ICallbacks testCallbacks)` | Unregisters an instance of ICallbacks to no longer receive callbacks from test runs. |
| `void RetrieveTestList(TestMode testMode, Action<ITestAdaptor> callback)` | Retrieve the full test tree as [ITestAdaptor](./reference-itest-adaptor.md) for a given test mode. | | `void RetrieveTestList(TestMode testMode, Action<ITestAdaptor> callback)` | Retrieve the full test tree as [ITestAdaptor](./reference-itest-adaptor.md) for a given test mode. |
\ No newline at end of file
# Test Utils # Test Utils
This contains test utility functions for float value comparison and creating primitives. This contains test utility functions for float value comparison and creating primitives.
## Static Methods ## Static Methods
| Syntax | Description | | Syntax | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ | | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `bool AreFloatsEqual(float expected, float actual, float allowedRelativeError)` | Relative epsilon comparison of two float values for equality. `allowedRelativeError` is the relative error to be used in relative epsilon comparison. The relative error is the absolute error divided by the magnitude of the exact value. Returns `true` if the actual value is equivalent to the expected value. | | `bool AreFloatsEqual(float expected, float actual, float allowedRelativeError)` | Relative epsilon comparison of two float values for equality. `allowedRelativeError` is the relative error to be used in relative epsilon comparison. The relative error is the absolute error divided by the magnitude of the exact value. Returns `true` if the actual value is equivalent to the expected value. |
| `bool AreFloatsEqualAbsoluteError(float expected, float actual, float allowedAbsoluteError)` | Compares two floating point numbers for equality under the given absolute tolerance. `allowedAbsoluteError` is the permitted error tolerance. Returns `true` if the actual value is equivalent to the expected value under the given tolerance. | | `bool AreFloatsEqualAbsoluteError(float expected, float actual, float allowedAbsoluteError)` | Compares two floating point numbers for equality under the given absolute tolerance. `allowedAbsoluteError` is the permitted error tolerance. Returns `true` if the actual value is equivalent to the expected value under the given tolerance. |
| `GameObject CreatePrimitive( type)` | Creates a [GameObject](https://docs.unity3d.com/ScriptReference/GameObject.html) with a primitive [MeshRenderer](https://docs.unity3d.com/ScriptReference/MeshRenderer.html). This is an analogue to the [GameObject.CreatePrimitive](https://docs.unity3d.com/ScriptReference/GameObject.CreatePrimitive.html), but creates a primitive `MeshRenderer` with a fast [Shader](https://docs.unity3d.com/ScriptReference/Shader.html) instead of the default built-in `Shader`, optimized for testing performance. `type` is the [primitive type](https://docs.unity3d.com/ScriptReference/PrimitiveType.html) of the required `GameObject`. Returns a `GameObject` with primitive `MeshRenderer` and [Collider](https://docs.unity3d.com/ScriptReference/Collider.html). | | `GameObject CreatePrimitive( type)` | Creates a [GameObject](https://docs.unity3d.com/ScriptReference/GameObject.html) with a primitive [MeshRenderer](https://docs.unity3d.com/ScriptReference/MeshRenderer.html). This is an analogue to the [GameObject.CreatePrimitive](https://docs.unity3d.com/ScriptReference/GameObject.CreatePrimitive.html), but creates a primitive `MeshRenderer` with a fast [Shader](https://docs.unity3d.com/ScriptReference/Shader.html) instead of the default built-in `Shader`, optimized for testing performance. `type` is the [primitive type](https://docs.unity3d.com/ScriptReference/PrimitiveType.html) of the required `GameObject`. Returns a `GameObject` with primitive `MeshRenderer` and [Collider](https://docs.unity3d.com/ScriptReference/Collider.html). |
## Example ## Example
```c# ```c#
[TestFixture] [TestFixture]
class UtilsTests class UtilsTests
{ {
[Test] [Test]
public void ChechThat_FloatsAreEqual() public void ChechThat_FloatsAreEqual()
{ {
float expected = 10e-8f; float expected = 10e-8f;
float actual = 0f; float actual = 0f;
float allowedRelativeError = 10e-6f; float allowedRelativeError = 10e-6f;
Assert.That(Utils.AreFloatsEqual(expected, actual, allowedRelativeError), Is.True); Assert.That(Utils.AreFloatsEqual(expected, actual, allowedRelativeError), Is.True);
} }
[Test] [Test]
public void ChechThat_FloatsAreAbsoluteEqual() public void ChechThat_FloatsAreAbsoluteEqual()
{ {
float expected = 0f; float expected = 0f;
float actual = 10e-6f; float actual = 10e-6f;
float error = 10e-5f; float error = 10e-5f;
Assert.That(Utils.AreFloatsEqualAbsoluteError(expected, actual, error), Is.True); Assert.That(Utils.AreFloatsEqualAbsoluteError(expected, actual, error), Is.True);
} }
} }
``` ```
# MonoBehaviour tests # MonoBehaviour tests
`MonoBehaviourTest` is a [coroutine](https://docs.unity3d.com/ScriptReference/Coroutine.html) and a helper for writing [MonoBehaviour](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html) tests. `MonoBehaviourTest` is a [coroutine](https://docs.unity3d.com/ScriptReference/Coroutine.html) and a helper for writing [MonoBehaviour](https://docs.unity3d.com/ScriptReference/MonoBehaviour.html) tests.
Yield a `MonoBehaviourTest` when using the `UnityTest` attribute to instantiate the `MonoBehaviour` you wish to test and wait for it to finish running. Implement the `IMonoBehaviourTest` interface on the `MonoBehaviour` to state when the test completes. Yield a `MonoBehaviourTest` when using the `UnityTest` attribute to instantiate the `MonoBehaviour` you wish to test and wait for it to finish running. Implement the `IMonoBehaviourTest` interface on the `MonoBehaviour` to state when the test completes.
## Example ## Example
```c# ```c#
[UnityTest] [UnityTest]
public IEnumerator MonoBehaviourTest_Works() public IEnumerator MonoBehaviourTest_Works()
{ {
yield return new MonoBehaviourTest<MyMonoBehaviourTest>(); yield return new MonoBehaviourTest<MyMonoBehaviourTest>();
} }
public class MyMonoBehaviourTest : MonoBehaviour, IMonoBehaviourTest public class MyMonoBehaviourTest : MonoBehaviour, IMonoBehaviourTest
{ {
private int frameCount; private int frameCount;
public bool IsTestFinished public bool IsTestFinished
{ {
get { return frameCount > 10; } get { return frameCount > 10; }
} }
void Update() void Update()
{ {
frameCount++; frameCount++;
} }
} }
``` ```
## MonoBehaviourTest&lt;T&gt; ## MonoBehaviourTest&lt;T&gt;
This is a wrapper that allows running tests on `MonoBehaviour` scripts. Inherits from [CustomYieldInstruction](https://docs.unity3d.com/ScriptReference/CustomYieldInstruction.html). This is a wrapper that allows running tests on `MonoBehaviour` scripts. Inherits from [CustomYieldInstruction](https://docs.unity3d.com/ScriptReference/CustomYieldInstruction.html).
### Properties ### Properties
| Syntax | Description | | Syntax | Description |
| ----------------------- | ------------------------------------------------------------ | | ----------------------- | ------------------------------------------------------------ |
| `T component` | A `MonoBehaviour` component created for the test and attached to the test’s [GameObject](https://docs.unity3d.com/ScriptReference/GameObject.html). | | `T component` | A `MonoBehaviour` component created for the test and attached to the test’s [GameObject](https://docs.unity3d.com/ScriptReference/GameObject.html). |
| `GameObject gameObject` | A `GameObject` created as a container for the test component. | | `GameObject gameObject` | A `GameObject` created as a container for the test component. |
| `bool keepWaiting` | (Inherited) Returns `true` if the test is not finished yet, which keeps the coroutine suspended. | | `bool keepWaiting` | (Inherited) Returns `true` if the test is not finished yet, which keeps the coroutine suspended. |
## IMonoBehaviourTest ## IMonoBehaviourTest
An interface implemented by a `MonoBehaviour` test. An interface implemented by a `MonoBehaviour` test.
### Properties ### Properties
| Syntax | Description | | Syntax | Description |
| --------------------- | ----------------------------------------------- | | --------------------- | ----------------------------------------------- |
| `bool IsTestFinished` | Indicates when the test is considered finished. | | `bool IsTestFinished` | Indicates when the test is considered finished. |
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment