Update docs

.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

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
+##### Personal License
-name: Test project
-on: [push]
-jobs:
-  testRunnerInAllModes:
-    name: Test all modes ✨
-    runs-on: ubuntu-latest
-    steps:
-```
 
-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
+- uses: webbertakken/unity-test-runner@v1.2
-- name: Run tests
   id: myTestStep
-  uses: webbertakken/unity-test-runner@v1.1
   env:
-    # Choose: "all", "playmode", "editmode"
+    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
-    TEST_MODE: all
+  with:
-
+    projectPath: path/to/your/project
-    # Optional: Path to your project, leave blank for "./"
+    unityVersion: 20XX.X.XXXX
-    PROJECT_PATH: relative/path/to/your/project
-
-    # Optional: Artifacts path, leave blank for "artifacts"
-    ARTIFACTS_PATH: store/artifacts/here
 ```
 
-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
+- uses: webbertakken/unity-test-runner@v1.2
-- name: Upload test results
+  id: myTestStep
-  uses: actions/upload-artifact@v1
+  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

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
 
 #