Add twister workflow and update Zephyr group documentation

workflow-templates/zephyr/.github/workflows/twister.yaml

@@ -0,0 +1,133 @@
+name: Twister
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  twister-build:
+    name: "Run Unit Tests"
+    # This version is a must, twister otherwise fails (some Python library
+    # depends on a specific version of libffi that is not present in the
+    # toolchain provided by nordic's toolchain manager).
+    runs-on: ubuntu-20.04
+    defaults:
+      run:
+        shell: bash
+        # Set work dir to "project" for all 'run' calls. Beware, everything else
+        # (actions, 'with' params, etc.) still needs to reference full path.
+        working-directory: project
+
+    steps:
+      - name: Checkout last PR commit
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: project
+
+      - name: Retrieve cache
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-modules
+        with:
+          path: |
+            bootloader
+            modules
+            nrf
+            nrfxlib
+            test
+            tools
+            zephyr
+            ~/.local/share/east/downloads/
+            ~/.local/share/east/nrfutil-toolchain-manager.exe
+          # Note above two lines, if we are caching entire ~/.local/share/east
+          # folder then cache action fails during download/extract step
+          key:
+            ${{ runner.os }}-build-${{ env.cache-name }}-${{
+            hashFiles('project/west.yml') }}
+          restore-keys: ${{ runner.os }}-build-${{ env.cache-name }}-
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+          cache: "pip"
+          cache-dependency-path: project/scripts/requirements.txt
+
+      - name: Install dependencies
+        run: make install-dep
+
+      - name: Install test dependencies
+        run: make install-test-dep
+
+      - name: Setup project
+        run: make project-setup
+
+      - name: Run tests
+        run: make test
+
+      - name: Create test report
+        if: always()
+        run: make test-report-ci
+
+      - name: Create coverage report
+        run: |
+          make coverage-report-ci
+          # sed command removes "project/" from the paths in coverage.info, 
+          # so that the GitHub action that makes the coverage report can create 
+          # proper links to the source files.
+          sed -i 's|project/||g' twister-out/coverage.info
+
+      - name: Upload Unit Test Results
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: test-report
+          path: |
+            project/twister-out/twister-report.html
+            project/twister-out/twister.xml
+            project/twister-out/twister.log
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v3
+        with:
+          name: coverage-report
+          path: |
+            project/twister-out/coverage.info
+
+  twister-test-results:
+    name: "Publish Unit Tests Results"
+    needs: twister-build
+    if: always()
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Download Artefacts
+        uses: actions/download-artifact@v3
+        with:
+          name: test-report
+          path: test-report
+
+      - name: Publish Unit Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v2.9.0
+        with:
+          check_name: Unit Test Results
+          files: test-report/twister.xml
+          comment_mode: off
+
+  coverage-report:
+    name: "Publish Coverage Report"
+    needs: twister-build
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Download Artefacts
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-report
+          path: coverage-report
+
+      - name: Publish Coverage Report
+        uses: romeovs/lcov-reporter-action@4cf015aa4afa87b78238301f1e3dc140ea0e1ec6
+        with:
+          lcov-file: ./coverage-report/coverage.info

workflow-templates/zephyr/README.md

@@ -11,8 +11,9 @@ Specifically, they provide:
 - Everything that [Basic](../basic/README.md) workflows already do: changelog
   preparation, tagging, publishing GitHub releases, etc.,
 - Running _builds_ on Pull Requests and during releases processes,
+- Running _tests_ on Pull Requests,
 - Caching of West modules and toolchains downloaded by East to speed up the
-  _build_ process,
+  project setup,
 - A way to change what _build_ means for each project,
 - A way to specify which artefacts are attached to the published GitHub releases
   for each project,
@@ -33,12 +34,13 @@ Needed files (relative to project's root dir):
 
 ### How to use
 
-This group contains four workflows:
+This group contains the following workflows:
 
 - `create-release.yaml`
 - `publish-release.yaml`
 - `build.yaml`
 - `label_pr.yaml`
+- `twister.yaml`
 
 They can be used in two different scenarios:
 
@@ -65,8 +67,8 @@ then the created release tag and Changelog update commit are deleted from the
 
 #### Pull requests
 
-`build.yaml` (and therefore _build_ process) is automatically triggered whenever
-a PR is opened, reopened or a new commit is pushed to the PR.
+`build.yaml` (aka. _build_ process) and `twister.yaml` are automatically
+triggered whenever a PR is opened, reopened or a new commit is pushed to the PR.
 
 ## How to configure _build_
 
@@ -138,8 +140,8 @@ artefacts or some dynamically generated report.
 To do that the `make pre-package` command can copy into the `artefacts` folder
 the `pre_changelog.md` and `post_changelog.md` markdown files.
 
-Contents of these files then becomes a part of the Release Notes in the
-following way:
+Contents of these files then become a part of the Release Notes in the following
+way:
 
 ```markdown
 # Release notes
@@ -155,7 +157,48 @@ If a section is not used, the corresponding file can be empty.
 `pre_changelog.md` and `post_changelog.md` files are not attached to the created
 release, even though they are present in the `artefacts` folder.
 
-### A short note about Make
+## Twister workflow
+
+Twister workflow performs the same project setup as `build.yaml` does before it
+starts executing the following `make` commands:
+
+```bash
+make install-dep
+make install-test-dep
+make project-setup
+make test
+make test-report-ci     # Runs always, even if "make test" failed
+make coverage-report-ci # Runs if make test succeded
+```
+
+Expected behaviour of `make` commands (those that weren't already described
+above):
+
+- `make install-test-dep` - Installs tooling needed by the testing.
+- `make test` - Runs tests with enabled coverage.
+- `make test-report-ci` - Creates test report. Runs always, even if `make test`
+  failed.
+- `make coverage-report-ci` - Creates coverage report.
+
+### Artefacts and reports
+
+Workflow will then:
+
+- Publish test report and
+- if the `make test` command is successful, it will also publish code coverage
+  summary as a comment on the PR.
+
+To see the test report you can click `Details` (next to any Twister check in the
+PR) -> `Summary`.
+
+Artefact `test-report` will also contain `test-report.html` which can be viewed
+in browser.
+
+![ci-checks](./ci-checks.png)
+
+![ci-summary](./ci-summary.png)
+
+## A short note about Make
 
 Make is a build automation tool, often used for managing source code
 dependencies and executing compiler commands.