From c937b9ed6cdcf54dab9a71f06b5315ed82a115cf Mon Sep 17 00:00:00 2001 From: Webber Date: Fri, 31 Jan 2020 00:35:41 +0100 Subject: [PATCH] Update docs --- .github/workflows/main.yml | 55 ++++++++-- README.md | 215 +++++++++++++++++++++++++++++++------ action/steps/run_tests.sh | 2 +- 3 files changed, 230 insertions(+), 42 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 90447ca..1e2ab13 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -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 diff --git a/README.md b/README.md index 7f3a541..a8f94c5 100644 --- a/README.md +++ b/README.md @@ -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:** ``_ + +#### 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 diff --git a/action/steps/run_tests.sh b/action/steps/run_tests.sh index 8e7b9c9..484bcfc 100644 --- a/action/steps/run_tests.sh +++ b/action/steps/run_tests.sh @@ -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 #