From 2900c66647141d511917079e672004883d3b48a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B8rgen=20Schartum=20Dokken?= <dokken92@gmail.com>
Date: Thu, 13 Oct 2022 13:33:55 +0100
Subject: [PATCH] Add docs on coverage and testing (#39)

* Add docs on coverage and testing

* Fix coverage

* Apply suggestions from code review
---
 docs/_toc.yml          |  2 +-
 docs/part1/coverage.md | 25 +++++++++++++++++++++++++
 docs/part1/testing.md  | 34 ++++++++++++++++++++++++++++++++++
 pyproject.toml         |  8 +++++++-
 4 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/docs/_toc.yml b/docs/_toc.yml
index a1848cc..49c3579 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -5,10 +5,10 @@ parts:
   - caption: Python packaging
     chapters:
     - file: "part1/packaging"
+    - file: "part1/testing"
     - file: "part1/coverage"
     - file: "part1/linting"
     - file: "part1/typing"
-    - file: "part1/testing"
     - file: "part1/pre_commit.md"
 
   - caption: Github tools
diff --git a/docs/part1/coverage.md b/docs/part1/coverage.md
index 4695439..b2012c6 100644
--- a/docs/part1/coverage.md
+++ b/docs/part1/coverage.md
@@ -1 +1,26 @@
 # Coverage reports
+
+When creating a Python package, it can be very useful to know what part of your code is covered by the tests.
+
+We recommend using [pytest-cov](https://pytest-cov.readthedocs.io/en/latest/) which extends the [pytest](./testing.md) suite with a coverage report of your package.
+
+We add to the `addopts` section of the `[tool.pytest.ini_options]` table:
+```toml
+addopts = [
+    # Other options...
+    "--cov=mypackage --cov-report html --cov-report term-missing -v"
+]
+
+We use Github Actions to upload the coverage report as an artifact after executing the tests. We add the following step
+```yml
+      - name: Run tests
+        run: python -m pytest 
+
+      - name: Upload coverage report as artifact
+        if: matrix.os == 'ubuntu-22.04' && matrix.python-version == '3.10'
+        uses: actions/upload-artifact@v3
+        with:
+          name: code-coverage-report
+          path: htmlcov
+          if-no-files-found: error
+```
\ No newline at end of file
diff --git a/docs/part1/testing.md b/docs/part1/testing.md
index f00b526..2baf7a2 100644
--- a/docs/part1/testing.md
+++ b/docs/part1/testing.md
@@ -1 +1,35 @@
 # Testing
+
+It is very important to have tests for verification of your code.
+There are several types of tests, see for instanche [Atlassian](https://www.atlassian.com/continuous-delivery/software-testing/types-of-software-testing) for a summary.
+
+The most important types of tests are the _unit tests_, which tests the core functionality of your code.
+
+The most common testing suite for Python in [pytest](https://docs.pytest.org/en/latest/), which can be installed from the [Python Package Index](https://docs.pytest.org/en/latest/) (PYPI) using
+```bash
+python3 -m pip install pytest
+```
+
+You can run `pytest` as
+```bash
+python3 -m pytest
+Pytest will then find all files with names like `test_*.py` and `*_test.py`, see: [Conventions for test discovery](https://docs.pytest.org/en/latest/explanation/goodpractices.html#test-discovery) for more information.
+
+We add the following information to `pyproject.toml` under table header: `[project.optional-dependencies]`
+```toml
+[project.optional-dependencies]
+# Other entries
+# ....
+test = [
+   "pytest",
+]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--import-mode=importlib",
+    # Other entries ....
+]
+```
+The last option is due to pytest's recommendation for new projects, see [Choosing an import mode](https://docs.pytest.org/en/latest/explanation/goodpractices.html#choosing-an-import-mode) for more information.
+
+For other inputs to `[tool.pytest.ini_options]` see: [https://docs.pytest.org/en/latest/reference/customize.html#pyproject-toml](https://docs.pytest.org/en/latest/reference/customize.html#pyproject-toml)
diff --git a/pyproject.toml b/pyproject.toml
index c5a819d..eec7c4e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,7 +55,13 @@ files = [  # Folder to which files that should be checked by mypy
 ]
 
 [tool.pytest.ini_options]
-addopts = "--cov=mypackage --cov-report html --cov-report term-missing -v"
+addopts = [
+    "--import-mode=importlib",
+    "--cov=mypackage",
+    "--cov-report=html",
+    "--cov-report=term-missing",
+    "-v"]
+
 testpaths = [
     "test"
 ]