From 8ea84150f8d21bc91ab83b59c917bd160f1be8ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=B6z=C3=BCkan=20Hande?= <hande.gozukan@inria.fr>
Date: Wed, 17 Jan 2024 12:22:45 +0000
Subject: [PATCH] Enh coverage

---
 README.md                            | 28 ++++++++++++-
 practical/3.yml_for_unitary_tests.md | 62 +++++++++++++++++++++-------
 practical/4.yml_for_doc_build.md     |  5 +--
 practical/5.yml_for_docker.md        | 17 +++++---
 4 files changed, 86 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index e5fe2ec..74508f3 100644
--- a/README.md
+++ b/README.md
@@ -65,12 +65,38 @@ Then execute the following command from project root directory:
   pytest
 ```
 
-To run the tests and create coverage report:
+#### Test coverage
+To run the tests and view coverage report in terminal window:
+
+```bash
+  pytest --cov=projection --cov-report term-missing
+```
+
+To run the tests and generate coverage report in `html` format:
 
 ```bash
   pytest --cov=projection --cov-report=html
 ```
 
+This will generate coverage report in html format under the `htmlcov` directory
+in the project's root directory.
+
+To run the tests and generate coverage report in `xml` format:
+
+```bash
+  pytest --cov=projection --cov-report xml:coverage.xml 
+```
+
+This will generate coverage report in xml format under in the project's root directory.
+
+It is possible to combine the commands to generate all at once:
+
+```bash
+  pytest --cov=projection --cov-report term-missing \
+                          --cov-report=html \
+                          --cov-report xml:coverage.xml 
+```
+
 ## Build documentation
 
 To build documentation, install `projection` package with `doc` option which
diff --git a/practical/3.yml_for_unitary_tests.md b/practical/3.yml_for_unitary_tests.md
index 1625184..cb3b8cc 100644
--- a/practical/3.yml_for_unitary_tests.md
+++ b/practical/3.yml_for_unitary_tests.md
@@ -2,7 +2,7 @@
 
 ## 1st version - Projection installation
 
-Add the following `.gitlab-ci.yml` file at the git repository root in order to
+- Add the following `.gitlab-ci.yml` file at the git repository root in order to
 [install the projection module](../README.md#install-projection-with-pip):
 
 ```yml
@@ -18,7 +18,7 @@ tests:
     - echo "Projection is installed"
 ```
 
-Add the `.gitlab-ci.yml` file, commit and push your modifications:
+- Add the `.gitlab-ci.yml` file, commit and push your modifications:
 
 ```bash
 git add .gitlab-ci.yml
@@ -26,24 +26,26 @@ git commit -m "First version - Projection installation in CI"
 git push
 ```
 
-Verify the CI is launched and successful:
-- On the left sidebar in the Gitlab interface, go to **Build** → **Jobs**.
-- Check the job is passed.
-- Click on the **Passed** icon and verify the logs.
+- Verify the CI is launched and successful:
+    - On the left sidebar in the Gitlab interface, go to **Build** → **Jobs**.
+    - Check the job is running.
+    - Click on the **Running** icon and verify the logs.
+    - See the job is passed.
 
 ## 2nd version - Projection tests
 
-Add the required steps in the `script` section of the `.gitlab-ci.yml` file to [run the tests](../README.md#run-the-tests).
+- Add the required steps in the `script` section of the `.gitlab-ci.yml` file to [run the tests](../README.md#run-the-tests).
 
-Add the `.gitlab-ci.yml` file, commit and push your modifications.
+- Add the `.gitlab-ci.yml` file, commit and push your modifications.
 
-Verify the CI is launched and successful.
+- Verify the CI is launched and successful.
 
 ## 3rd version - Projection tests coverage report
 
-Modify how [the tests are run](../README.md#run-the-tests) to produce the coverage report.
+- Modify how [the tests are run](../README.md#run-the-tests) to produce the
+  coverage report in `html` format.
 
-Provide the coverage report as an artifact by adding in the `.gitlab-ci.yml` file:
+- Provide the coverage report as an artifact by adding in the `.gitlab-ci.yml` file:
 ```yml
   script:
     - pip install -e .
@@ -54,11 +56,11 @@ Provide the coverage report as an artifact by adding in the `.gitlab-ci.yml` fil
       - htmlcov
 ```
 
-Verify the CI is launched and successful:
-- On the left sidebar in the Gitlab interface, go to **Build** → **Jobs**.
-- Check the job is passed.
-- Click on the **Passed** icon and verify the logs.
-- On the right sidebar in the Gitlab interface, browse the job artifact.
+- Verify the CI is launched and successful:
+    - On the left sidebar in the Gitlab interface, go to **Build** → **Jobs**.
+    - Check the job is passed.
+    - Click on the **Passed** icon and verify the logs.
+    - On the right sidebar in the Gitlab interface, browse the job artifact.
 
 ## 4th version (OPTIONAL)
 
@@ -83,6 +85,34 @@ To do so on this project:
     - Badge Image URL: `https://gitlab.inria.fr/%{project_path}/badges/%{default_branch}/coverage.svg`
 - Click on the **Add badge** button.
 
+- Modify `script` section to generate coverage report both in `html` and `xml` formats.
+
+- Add [coverage](https://docs.gitlab.com/16.7/ee/ci/yaml/index.html#coverage)
+section to project’s `.gitlab-ci.yml` file to provide test coverage results to
+a merge request. Provided regex is used to find the coverage in the tool’s
+output.
+
+- Add [reports](https://docs.gitlab.com/ee/ci/yaml/index.html#artifactsreports)
+  section to `artifacts` and specify `coverage.xml` for coverage analysis to
+  work.
+
+> Here we still keep `artifacts:paths` part as `reports` artifacts are not
+  downloadable from the job details page.
+
+```yml
+  script:
+    - (...)
+  coverage: '/^TOTAL.+?(\d+\%)$/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+    paths:
+      - htmlcov
+      - coverage.xml
+```
+
 ## 5th version
 
 Let's introduce another useful feature of GitLab-CI: [the pipelines](https://docs.gitlab.com/ee/ci/pipelines/).
diff --git a/practical/4.yml_for_doc_build.md b/practical/4.yml_for_doc_build.md
index bdc9f19..a73ad00 100644
--- a/practical/4.yml_for_doc_build.md
+++ b/practical/4.yml_for_doc_build.md
@@ -59,9 +59,8 @@ directory as artifact, `pages:deploy` job has failed.
 - Verify the CI is launched and successful.
 
 - Verify that the html pages are published.
-
-  o On the left sidebar in the GitLab interface, go to **Deploy** → **Pages**.
-  o Click on link provided in the **Access Pages** section.
+    - On the left sidebar in the GitLab interface, go to **Deploy** → **Pages**.
+    - Click on link provided in the **Access Pages** section.
 
 ## 3rd version - Build documentation only for default branch (OPTIONAL)
 
diff --git a/practical/5.yml_for_docker.md b/practical/5.yml_for_docker.md
index 3266849..c3fccc3 100644
--- a/practical/5.yml_for_docker.md
+++ b/practical/5.yml_for_docker.md
@@ -87,8 +87,7 @@ variable. Instead of tagging the image with `v1`, we can use
 - Verify the CI is launched and successful.
 
 - Verify that the Docker image is saved in the GitLab container registry.
-
-  o On the left sidebar in the GitLab interface, go to **Deploy** → **Container Registry**.
+    - On the left sidebar in the GitLab interface, go to **Deploy** → **Container Registry**.
 
 ## 3rd version - Use Docker Image for CI Jobs
 
@@ -124,7 +123,16 @@ test python 3.12:
     - small
   script:
     - pip install -e .
-    - pytest --cov=projection --cov-report=html
+    - pytest --cov=projection --cov-report term-missing --cov-report xml:coverage.xml --cov-report html
+  coverage: '/^TOTAL.+?(\d+\%)$/'
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage.xml
+    paths:
+      - htmlcov
+      - coverage.xml  
 
 test python 3.11:    
   image: python:3.11 
@@ -135,9 +143,6 @@ test python 3.11:
   script:
     - pip install -e .[test]
     - pytest
-  artifacts:
-    paths:
-      - htmlcov
 
 pages:
   image: $IMAGE_TAG
-- 
GitLab