Update docs

pull/11/head
Webber 2020-01-31 00:35:41 +01:00 committed by Webber Takken
parent 56b8c04f36
commit c937b9ed6c
3 changed files with 230 additions and 42 deletions

View File

@ -21,17 +21,50 @@ jobs:
- run: yarn build || { echo "build command should always succeed" ; exit 61; }
- run: yarn build --quiet && git diff --quiet action || { echo "action should be auto generated" ; exit 62; }
testAllModesLikeInTheReadme:
name: Test in ${{ matrix.testMode }} on version ${{ matrix.unityVersion }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
projectPath:
- unity-project-with-correct-tests
unityVersion:
- 2019.2.11f1
testMode:
- playmode
- editmode
steps:
- uses: actions/checkout@v2
with:
lfs: true
- uses: actions/cache@v1.1.0
with:
path: ${{ matrix.projectPath }}/Library
key: Library-${{ matrix.projectPath }}
restore-keys: |
Library-
- uses: ./
id: tests
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
artifactsPath: ${{ matrix.testMode }}-artifacts
- uses: actions/upload-artifact@v1
with:
name: Test results for ${{ matrix.testMode }}
path: ${{ steps.tests.outputs.artifactsPath }}
testRunnerInAllModes:
name: Test all modes ✨
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
unityVersion:
# - 2018.4.15f1 # need a way to use multiple licenses, using matrix.include referencing env
- 2019.2.11f1
projectPath:
- unity-project-with-correct-tests
unityVersion:
- 2019.2.11f1
steps:
# Checkout repository (required to test local actions)
- name: Checkout repository
@ -53,9 +86,9 @@ jobs:
id: allTests
uses: ./
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
testMode: all
projectPath: ${{ matrix.projectPath }}
# Test implicit artifactsPath, by not setting it
# Upload artifacts
@ -96,9 +129,9 @@ jobs:
id: editMode
uses: ./
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
testMode: editmode
projectPath: ${{ matrix.projectPath }}
artifactsPath: artifacts/editmode
# Upload artifacts
@ -114,10 +147,10 @@ jobs:
strategy:
fail-fast: false
matrix:
unityVersion:
- 2019.2.11f1
projectPath:
- unity-project-with-correct-tests
unityVersion:
- 2019.2.11f1
steps:
# Checkout repository (required to test local actions)
- name: Checkout repository
@ -139,9 +172,9 @@ jobs:
id: playMode
uses: ./
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
testMode: playmode
projectPath: ${{ matrix.projectPath }}
artifactsPath: artifacts/playmode
# Upload artifacts
@ -151,7 +184,7 @@ jobs:
name: Test results (play mode)
path: ${{ steps.playMode.outputs.artifactsPath }}
testRunnerInEachModeSeparately:
testEachModeSequentially:
name: Test each mode sequentially 👩‍👩‍👧‍👦 # don't try this at home (it's much slower)
runs-on: ubuntu-latest
strategy:
@ -181,18 +214,18 @@ jobs:
- name: Tests in editmode 📝
uses: ./
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
testMode: editmode
projectPath: ${{ matrix.projectPath }}
artifactsPath: artifacts/editmode
# Configure second test runner
- name: Tests in playmode 📺
uses: ./
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
testMode: playmode
projectPath: ${{ matrix.projectPath }}
artifactsPath: artifacts/playmode
# Upload combined artifacts

215
README.md
View File

@ -26,50 +26,209 @@ collection repository for workflow documentation and reference implementation.
## Usage
#### Setup test runner
By default the test runner will run all your playmode and editmode tests.
Create or edit the file called `.github/workflows/main.yml` and add a job to it.
```yaml
name: Test project
on: [push]
jobs:
testRunnerInAllModes:
name: Test all modes ✨
runs-on: ubuntu-latest
steps:
```
##### Personal License
Configure the test runner as follows:
Personal licenses require a one-time manual activation step (per unity version).
Make sure you
[acquire and activate](https://github.com/marketplace/actions/unity-request-activation-file)
your license file and add it as a secret.
Then, define the test step as follows:
```yaml
# Configure test runner
- name: Run tests
- uses: webbertakken/unity-test-runner@v1.2
id: myTestStep
uses: webbertakken/unity-test-runner@v1.1
env:
# Choose: "all", "playmode", "editmode"
TEST_MODE: all
# Optional: Path to your project, leave blank for "./"
PROJECT_PATH: relative/path/to/your/project
# Optional: Artifacts path, leave blank for "artifacts"
ARTIFACTS_PATH: store/artifacts/here
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
with:
projectPath: path/to/your/project
unityVersion: 20XX.X.XXXX
```
You use the id to **upload the artifacts** like so:
##### Professional license
Professional licenses do not need any manual steps.
Instead, three variables will need to be set.
- `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:
```yaml
# Upload artifacts
- name: Upload test results
uses: actions/upload-artifact@v1
- uses: webbertakken/unity-test-runner@v1.2
id: myTestStep
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](https://github.com/marketplace/actions/upload-artifact)
after any test action.
###### Using defaults
By default, Test Runner outputs it's results to a folder named `artifacts`.
Example:
```yaml
- 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
If a different `artifactsPath` was specified in the test runner,
you can reference this path using the `id` of the test step.
Example:
```yaml
- 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](https://github.com/marketplace/actions/cache)
before any unity steps.
Example:
```yaml
- uses: actions/cache@v1.1.0
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%.
#### Complete example
A complete workflow that tests all modes separately could look like this:
```yaml
name: Build project
on:
pull_request: {}
push: { branches: [master] }
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
steps:
- uses: actions/checkout@v2
with:
lfs: true
- uses: actions/cache@v1.1.0
with:
path: ${{ matrix.projectPath }}/Library
key: Library-${{ matrix.projectPath }}
restore-keys: |
Library-
- uses: webbertakken/unity-test-runner@v1.2
id: tests
with:
projectPath: ${{ matrix.projectPath }}
unityVersion: ${{ matrix.unityVersion }}
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._
## 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.
_**required:** `false`_
_**default:** `2019.2.1f11`_
#### testMode
The type of tests to be run by the test runner.
Options are: "all", "playmode", "editmode"
_**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`_
#### customParameters
Custom parameters to configure the test run.
Custom parameters to configure the test runner.
Parameters must start with a hyphen (`-`) and may be followed by a value (without hyphen).
@ -86,10 +245,6 @@ _**example:**_
_**required:** `false`_
_**default:** ""_
#### Save your workflow
Commit and push your workflow definition.
## More actions
Visit

View File

@ -11,7 +11,7 @@ echo "Using project path \"$UNITY_PROJECT_PATH\"."
# Set and display the artifacts path
#
echo "Using build path \"$ARTIFACTS_PATH\" to save test results."
echo "Using artifacts path \"$ARTIFACTS_PATH\" to save test results."
FULL_ARTIFACTS_PATH=$GITHUB_WORKSPACE/$ARTIFACTS_PATH
#