Skip to main content
Version: v4 (current)

Test

The Unity Orb provides the test job to facilitate the process of testing your Unity project.

At the end of the run, the test results are parsed to JUnit and stored in CircleCI so that test insights can be used. You can access test insights from the CircleCI web app.

Parameters​

Below you will find information on each parameter that can be passed to the test job.

Each example only shows the parameter it describes. A working job also needs the required executor parameter, as shown in the examples.

custom-parameters​

Additional parameters for the Unity CLI, for example to filter which tests run with the Unity Test Framework's command line arguments.

The parameters must be separated by space and must be in the format -key value or -key for booleans. Environment variables are supported and will be expanded in runtime. Values can't contain spaces: quotes are removed and the parameters are split on whitespace.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
custom-parameters: '-testFilter MyNamespace.MyTests -testCategory Unit'
  • Default: N/A
  • Required: false
  • Type: string

executor​

The executor on which you want to run your test job on. Each executor has its set of parameters. See the Executors section for more details.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
executor:
name: 'unity/ubuntu'
target_platform: 'linux-il2cpp'
editor_version: '2021.3.2f1'
resource_class: 'medium'
  • Default: N/A
  • Required: True
  • Type: Executor

no_output_timeout​

Elapsed time without output before the job is canceled and stopped. The value can be in hours, minutes or seconds - a digit followed by h, m or s respectively. Consider increasing it if you see this error:

Too long with no output (exceeded 20m0s): context deadline exceeded

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
no_output_timeout: 30m
  • Default: 20m
  • Required: false
  • Type: string

project-path​

If your project sits at the root of your repository, leave it to the default value. Otherwise, enter the path of your Unity project. This should be the directory that has an "Assets" folder inside it.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
project-path: 'Unity2D-Demo-Game-CI-CD/src'
  • Default: .
  • Required: False
  • Type: String

return-license​

Whether to return the Unity license at the end of the job, even when the job fails. Don't enable it for jobs running in parallel with the same license: GameCI's Linux images share a machine ID, so returning the license in one job deactivates Unity in the others.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
return-license: true
  • Default: false
  • Required: false
  • Type: boolean

step-name​

Specify a custom step name to be shown in the CircleCI web app.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
step-name: 'Test my Unity project'
  • Default: Run tests
  • Required: False
  • Type: String

test-platform​

Choose the platform to run your tests on. The available options can be found on the Unity test framework documentation.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
test-platform: 'playmode'
  • Default: editmode
  • Required: False
  • Type: String

unity-license-var-name​

The name of the environment variable holding the content of your Unity license file (.ulf), raw or base64-encoded. Only used with a Personal License, when no serial is set: the serial is extracted from the license file. See activation for more details.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
unity-license-var-name: 'UNITY_LICENSE'
  • Default: UNITY_LICENSE
  • Required: False
  • Type: env_var_name

unity-password-var-name​

The name of the environment variable holding the password set in your Context. See Activation for more details.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
unity-password-var-name: 'UNITY_PASSWORD'
  • Default: UNITY_PASSWORD
  • Required: False
  • Type: env_var_name

unity-serial-var-name​

The name of the environment variable holding the serial set in your Context. If you are testing your project using the Unity Personal license, this is not required. See Activation for more details.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
unity-serial-var-name: 'UNITY_SERIAL'
  • Default: UNITY_SERIAL
  • Required: False
  • Type: env_var_name

unity-email-var-name​

The name of the environment variable holding your Unity account email. See activation for more details.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
test-unity-project:
jobs:
- unity/test:
unity-email-var-name: 'UNITY_EMAIL'
  • Default: UNITY_EMAIL
  • Required: False
  • Type: env_var_name

Examples​

In this section, you will find examples of workflows using this job. However, notice that the separation used in the examples is only for the sake of visualisation. You can test all target platforms in the same workflow. All examples are based on CircleCI's Demo Project.

Personal License​

This example shows how to build your project for several platforms using a Personal License.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
build-unity-project:
jobs:
# Linux
- unity/test:
name: 'test-linux'
step-name: 'Check if the tests run and results are uploaded'
unity-license-var-name: 'UNITY_LICENSE'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/ubuntu'
target_platform: 'linux-il2cpp'
editor_version: '2021.3.1f1'
resource_class: 'medium'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity

# Windows
- unity/test:
name: 'test-windows'
step-name: 'Check if the tests run and results are uploaded'
unity-license-var-name: 'UNITY_LICENSE'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/windows-2022'
size: 'large'
editor_version: '2021.3.2f1'
target_platform: 'windows-il2cpp'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity

# macOS
- unity/test:
name: 'test-osx'
step-name: 'Check if the tests run and results are uploaded'
unity-license-var-name: 'UNITY_LICENSE'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/macos'
editor_version: '2021.3.1f1'
resource_class: 'm4pro.large'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity

Professional License​

This example shows how to build your project for several platforms using a Pro License.

version: 2.1

orbs:
unity: game-ci/unity@2

workflows:
build-unity-project:
jobs:
# Linux
- unity/test:
name: 'test-linux'
step-name: 'Check if the tests run and results are uploaded'
unity-serial-var-name: 'UNITY_SERIAL'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/ubuntu'
target_platform: 'linux-il2cpp'
editor_version: '2021.3.1f1'
resource_class: 'medium'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity

# Windows
- unity/test:
name: 'test-windows'
step-name: 'Check if the tests run and results are uploaded'
unity-serial-var-name: 'UNITY_SERIAL'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/windows-2022'
size: 'large'
editor_version: '2021.3.2f1'
target_platform: 'windows-il2cpp'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity

# macOS
- unity/test:
name: 'test-osx'
step-name: 'Check if the tests run and results are uploaded'
unity-serial-var-name: 'UNITY_SERIAL'
unity-email-var-name: 'UNITY_EMAIL'
unity-password-var-name: 'UNITY_PASSWORD'
executor:
name: 'unity/macos'
editor_version: '2021.3.1f1'
resource_class: 'm4pro.large'
project-path: 'Unity2D-Demo-Game-CI-CD/src'
test-platform: 'playmode'
context: unity