Test runner

Running your test suite in an automated workflow helps increase certainty when merging.

Use Unity - Test runner to run your Unity tests.

Basic setup

By default, the test runner will run both playmode and editmode tests.

Create or edit the file called .github/workflows/main.yml and add a job to it.

Personal license

Personal licenses require a one-time manual activation step (per unity version).

Make sure you acquire and activate your license file and add it as a secret.

Then, define the test step as follows:

- uses: webbertakken/unity-test-[email protected]
  env:
    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
  with:
    projectPath: path/to/your/project
    unityVersion: 20XX.X.XXXX

Professional license

Make sure you have set up these variables in the activation step.

• UNITY_EMAIL (should contain the email address for your Unity account)
• UNITY_PASSWORD (the password that you use to login to Unity)
• UNITY_SERIAL (the serial provided by Unity)

Define the test step as follows:

- uses: webbertakken/unity-test-[email protected]
  env:
    UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
    UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
    UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
  with:
    projectPath: path/to/your/project
    unityVersion: 20XX.X.XXXX

That is all you need to test your project.

Storing test results

To be able to access the test results, they need to be uploaded as artifacts.

To do this it is recommended to use Github Actions official upload artifact action after any test action.

By default, Test Runner outputs its results to a folder named artifacts.

- uses: actions/upload-artifact@v1
  with:
    name: Test results
    path: artifacts

Test results can now be downloaded as Artifacts in the Actions tab.

Specifying artifacts folder

You can specify a different artifactsPath in the test runner and reference this path using the id of the test step.

- uses: webbertakken/unity-test-[email protected]
  id: myTestStep

- uses: actions/upload-artifact@v1
  with:
    name: Test results
    path: ${{ steps.myTestStep.outputs.artifactsPath }}

Caching

In order to make test runs (and builds) faster, you can cache Library files from previous runs.

To do so, simply add Github Actions' official cache action before any unity steps.

- uses: actions/[email protected]
  with:
    path: path/to/your/project/Library
    key: Library-MyProjectName-TargetPlatform
    restore-keys: |
      Library-MyProjectName-
      Library-

This simple addition could speed up your test runs by more than 50%.

Configuration options

Below options can be specified under with: for the unity-test-runner action.

projectPath

Specify the path to your Unity project to be tested. The path should be relative to the root of your project.

required: false default: <your project root>

unityVersion

Version of Unity to use for testing the project. Use "auto" to get from your ProjectSettings/ProjectVersion.txt

required: false default: auto

testMode

The type of tests to be run by the test runner.

Options are: "all", "playmode", "editmode", "standalone"

Note: "all" only runs "playmode" and "editmode". You must explicitly specify "standalone" for it to run.

required: false default: all

artifactsPath

Path where the test results should be stored.

In this folder a folder will be created for every test mode.

required: false default: artifacts

useHostNetwork

Initializes Docker using the host network.

This is useful if Unity needs to access a local server that was started as part of your workflow.

Options are: "true", "false"

required: false default: false

customParameters

Custom parameters to configure the test runner.

Parameters must start with a hyphen (-) and may be followed by a value (without hyphen).

Parameters without a value will be considered booleans (with a value of true).

- uses: webbertakken/unity-test-[email protected]
  with:
    customParameters: -profile SomeProfile -someBoolean -someValue exampleValue

required: false default: ""

customImage

Specific docker image that should be used for testing the project.

- uses: webbertakken/unity-test-[email protected]
  with:
    customImage: 'unityci/editor:2020.1.14f1-base-0'

required: false default: ""

Complete example

A complete workflow that tests all modes separately could look like this:

name: Build project

on:
  pull_request: {}
  push: { branches: [main] }

env:
  UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

jobs:
  testAllModes:
    name: Test in ${{ matrix.testMode }} on version ${{ matrix.unityVersion }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        projectPath:
          - path/to/your/project
        unityVersion:
          - 2019.2.11f1
        testMode:
          - playmode
          - editmode
          - standalone
    steps:
      - uses: actions/checkout@v2
        with:
          lfs: true
      - uses: actions/[email protected]
        with:
          path: ${{ matrix.projectPath }}/Library
          key: Library-${{ matrix.projectPath }}
          restore-keys: |
            Library-
      - uses: webbertakken/unity-test-[email protected]
        id: tests
        with:
          projectPath: ${{ matrix.projectPath }}
          unityVersion: ${{ matrix.unityVersion }}
          testMode: ${{ matrix.testMode }}
          artifactsPath: ${{ matrix.testMode }}-artifacts
      - uses: actions/upload-artifact@v1
        with:
          name: Test results for ${{ matrix.testMode }}
          path: ${{ steps.tests.outputs.artifactsPath }}

Note: Environment variables are set for all jobs in the workflow like this.