Skip to content

Commit 6a06683

Browse files
FejZaFejZa
committed
Update test task docs
1 parent e11cd24 commit 6a06683

File tree

1 file changed

+108
-92
lines changed

1 file changed

+108
-92
lines changed

‎docs/02-tasks/08-unity-test-task.md

Lines changed: 108 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -6,179 +6,195 @@ sidebar_label: Unity Test Task
66

77
# About the Unity Test Task
88

9-
This task is used for running unit tests in your project. Test results will output into a test results file and the file path is provided for uploading and processing. You can find the task when editing your pipeline by searching for the name `Unity Test`.
9+
This task is used for running unit tests in your project. Test results will output into a test results file and the file path is provided for uploading and processing.
1010

11-
---
11+
## Syntax
1212

13-
## Inputs
13+
```yaml
14+
# Unity Get Project Version Task V1
15+
# Get the project's Unity version
16+
- task: UnityTestTask@1
17+
inputs:
18+
testMode: editMode
19+
```
1420
15-
This task supports input variables for configuration.
21+
## Inputs
1622
1723
### testMode
1824
1925
The mode you want to run tests in.
2026
21-
**Required**: Yes
22-
23-
**Default Value**: editMode
27+
| YAML | Classic Editor | Required | Default |
28+
|----------------------------|-------------------------------|----------|---------|
29+
| `testMode` | Test mode | Yes | editMode |
2430

2531
#### Options:
2632

2733
| Value | Description |
2834
| -------- | ------------------------------------------------------------------------------------ |
29-
| editMode | Runs tests in edit mode, edit mode tests include the Unity Editor assembly and APIs. |
30-
| playMode | Runs tests in play mode. |
35+
| editMode | Runs tests in edit mode, edit mode tests include the Unity Editor assembly and APIs |
36+
| playMode | Runs tests in play mode |
3137

3238
### unityEditorsPathMode
3339

3440
For the task to run successfully it needs to know where Unity installations are located at on the agent. This input lets you configure,
3541
where the task should look for installations.
3642

37-
**Required**: Yes
38-
39-
**Default Value**: unityHub
43+
| YAML | Classic Editor | Required | Default |
44+
|----------------------------|-------------------------------|----------|---------|
45+
| `unityEditorsPathMode` | Unity editors location | Yes | default |
4046

4147
#### Options:
4248

4349
| Value | Description |
4450
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
45-
| unityHub | Uses the Unity Hub default installation path. |
51+
| default | Uses the Unity Hub default installation path |
4652
| environmentVariable | Expects an environment variable `UNITYHUB_EDITORS_FOLDER_LOCATION` to exist on the agent and specifying where to find editor installations. |
47-
| specify | Let's you specify a custom path where to lookup editor installations using the input `customUnityEditorsPath`. |
53+
| specify | Let's you specify a custom path where to lookup editor installations using the input `customUnityEditorsPath` |
4854

4955
### customUnityEditorsPath
5056

51-
If you are using a custom buld agent you may want to specify a custom path to specify where to look for Unity installations. This input lets you do that.
52-
Make sure to set `unityEditorsPathMode` to `specify` for this input to take effect.
57+
Should you have configured `unityEditorsPathMode` to `specify`, this input is used to read your custom path.
5358

54-
**Required**: Yes, if `unityEditorsPathMode` set to `specify`
59+
| YAML | Classic Editor | Required | Default |
60+
|----------------------------|-------------------------------|----------|---------|
61+
| `customUnityEditorsPath` | Editors folder location | Yes, if `unityEditorsPathMode` is `specify` | - |
5562

56-
**Default Value**: -
63+
### versionSelectionMode
5764

58-
### unityProjectPath
65+
This input defines how to determine the Unity version required to build the project on in the context of this task, which Unity editor version to install and / or actigvate a license with.
66+
67+
| YAML | Classic Editor | Required | Default |
68+
|----------------------------|-------------------------------|----------|---------|
69+
| `versionSelectionMode` | Unity version | Yes | project |
70+
71+
#### Options:
72+
73+
| Value | Description |
74+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
75+
| project | Uses exactly the Unity version that the project was last opened with |
76+
| specify | Let's you specify a Unity version to work with. See also input `version` |
5977

60-
Enter the directory path to the Unity project. If no value is entered, the project is assumed to be in the repository root.
78+
### version
6179

62-
**Required**: No
80+
The version of the Unity editor to work with, e.g. `6000.0.30f1`. You can determine the version for your project using the `ProjectVersion.txt` file within your project's `ProjectSettings` folder.
6381

64-
**Default Value**: -
82+
| YAML | Classic Editor | Required | Default |
83+
|----------------------------|-------------------------------|----------|---------|
84+
| `version` | Version | Yes, if `versionSelectionMode` is `specify` | - |
85+
86+
### unityProjectPath
87+
88+
Enter the directory path to the Unity project. If no value is entered, the project is assumed to be in the repository root. Use this input, if your Unity project is nested within subfolders within your repository.
89+
90+
| YAML | Classic Editor | Required | Default |
91+
|----------------------------|-------------------------------|----------|---------|
92+
| `unityProjectPath` | Unity project path | No | - |
6593

6694
### testCategory
6795

6896
A semicolon-separated list of test categories to include in the run. If using both testFilter and testCategory, then tests only run that matches both.
6997

70-
**Required**: No
71-
72-
**Default Value**: -
98+
| YAML | Classic Editor | Required | Default |
99+
|----------------------------|-------------------------------|----------|---------|
100+
| `testCategory` | Test category | No | - |
73101

74102
### testFilter
75103

76104
A semicolon-separated list of test names to run, or a regular expression pattern to match tests by their full name.
77105

78-
**Required**: No
79-
80-
**Default Value**: -
106+
| YAML | Classic Editor | Required | Default |
107+
|----------------------------|-------------------------------|----------|---------|
108+
| `testFilter` | Test filter | No | - |
81109

82110
### batchMode
83111

84112
If set, Unity runs in batch mode and disables any UI and popups to fully eliminate the need for human intervention. Note that you cannot use batch mode when testing UI.
85113

86-
**Required**: No
114+
| YAML | Classic Editor | Required | Default |
115+
|----------------------------|-------------------------------|----------|---------|
116+
| `batchMode` | Batch mode | No | true |
87117

88-
**Default Value**: true
118+
#### Options:
119+
120+
| Value | Description |
121+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
122+
| true | Runs Unity in batch mode |
123+
| false | Runs Unity with GUI |
89124

90125
### acceptApiUpdate
91126

92127
If set, the Unity API updater will run before running tests and update any obsolete API usage.
93128

94-
**Required**: No
129+
| YAML | Classic Editor | Required | Default |
130+
|----------------------------|-------------------------------|----------|---------|
131+
| `acceptApiUpdate` | Batch mode | No | false |
132+
133+
#### Options:
95134

96-
**Default Value**: false
135+
| Value | Description |
136+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
137+
| true | Runs API Updater |
138+
| false | Does not run API Updater |
97139

98140
### noPackageManager
99141

100142
If set, the Unity Package Manager is disabled for the time of task execution.
101143

102-
**Required**: No
103-
104-
**Default Value**: false
105-
106-
### testResultsPath
144+
| YAML | Classic Editor | Required | Default |
145+
|----------------------------|-------------------------------|----------|---------|
146+
| `noPackageManager` | Disable Unity package manager | No | false |
107147

108-
Tells the task where to output test results. Path can be relative to repository root or absolute.
148+
#### Options:
109149

110-
**Required**: No
150+
| Value | Description |
151+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
152+
| true | Disabled the package manager |
153+
| false | Does not disable the package manager |
111154

112-
**Default Value**: Test Results
155+
### noGraphics
113156

114-
### additionalCmdArgs
157+
When set, Unity does not initialize the graphics device. You can then run automated workflows on machines that don't have a GPU.
115158

116-
Specify command line arguments to pass to the Unity process when running the task.
159+
| YAML | Classic Editor | Required | Default |
160+
|----------------------------|-------------------------------|----------|---------|
161+
| `noGraphics` | No graphics | No | true |
117162

118-
:::warning
163+
#### Options:
119164

120-
Many command line arguments the build task will already set for you. If you find you are missing any advanced or custom command line arguments, only then you should
121-
specify them using this input. For most use cases and projects you will not need to add any additional command line arguments.
165+
| Value | Description |
166+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
167+
| true | Do not initialize GPU |
168+
| false | Initialize GPU |
122169

123-
:::
170+
### testResultsPath
124171

125-
**Required**: No
172+
Tells the task where to output test results. Path can be relative to repository root or absolute.
126173

127-
**Default Value**: -
174+
| YAML | Classic Editor | Required | Default |
175+
|----------------------------|-------------------------------|----------|---------|
176+
| `testResultsPath` | Test results output path | No | Test Results |
128177

129-
#### Options:
178+
### additionalCmdArgs
130179

131-
Check the official [Unity command line documentation](https://docs.unity3d.com/Manual/CommandLineArguments.html) for options.
180+
Specify any additional command line arguments to pass to the Unity process when running the task, should you need them.
132181

133-
---
182+
| YAML | Classic Editor | Required | Default |
183+
|----------------------------|-------------------------------|----------|---------|
184+
| `additionalCmdArgs` | Command line arguments | No | - |
134185

135-
## Outputs
186+
## Output variables
136187

137-
This task provides output variables.
188+
This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.
138189

139190
### testResultsOutputPathAndFileName
140191

141192
Path and File name of the test results in XML format.
142193

143-
### logsOutputPath
144-
145-
Path to the Unity editor log files generated while executing the task. Use this e.g. to upload logs in case of a failure.
146-
147-
---
148-
149-
## How to use
150-
151-
### YAML
152-
153-
In the simple YAML example below we are definiing the task a step in the pipeilne using `- task: UnityTestTask@1`. We are also giving the task a reference name using `name: unitytest`, so we can use it to refernce the output variables of the task in other tasks of the pipeline. E.g. we can output the value of the `testResultsOutputPathAndFileName` output variable to the console using `echo $(unitytest.testResultsOutputPathAndFileName)`. For `testMode` we specify that we want to run in `editMode`. Everything else we are leaving at the defaults.
154-
155-
```yaml
156-
trigger:
157-
- main
158-
159-
pool:
160-
name: Unity Windows
161-
162-
steps:
163-
- task: UnityTestTask@1
164-
name: unitytest
165-
inputs:
166-
testMode: editMode
167-
168-
- script: |
169-
echo $(unitytest.testResultsOutputPathAndFileName)
170-
```
171-
172-
### Classic Pipeline Editor
173-
174-
The classic (visual) editor for Azure Pipelines provides input fields for configuring the task. In the simple example below, we set `Test mode` to `Edit Mode`, that means we are running tests that will also include the Unity Editor assembly and APIs. This is e.g. useful when testing editor extensions. We are also assigning a `Reference name` to the task, so we can use it to refernce the output variables in the variables list in other tasks of the pipeline. E.g. to get the value of the `testResultsOutputPathAndFileName` output variable and insert it into any other input field of a task we can then use `$(unitytest.testResultsOutputPathAndFileName)`. Everything else we are leaving at the defaults.
175-
176-
![Classic Pipeline Designer Task Configuration](../../static/img/unity-test-task/unity-test-classic.png)
177-
178-
---
194+
### testsFailed
179195

180-
## Log
196+
`true`, if at least one test has failed. `false` otherwise.
181197

182-
When run and successful the task will provide log output similar to this:
198+
### editorLogFilePath
183199

184-
![Task Log](../../static/img/unity-test-task/unity-test-log.png)
200+
Path to the Unity editor log file generated while executing the task.

0 commit comments

Comments
 (0)