📖 DOC: Coverage plugin

06_testing/coverage.md

@@ -0,0 +1,43 @@
+# Test Coverage
+
+Test coverage is a software development metric that measures the how much of your code is covered by tests. It's typically expressed as a percentage, where higher percentages indicate more extensive testing.
+
+Test coverage is important for several reasons:
+
+* It helps identify untested parts of the code, which could contain potential bugs or vulnerabilities.
+* It serves as a quality indicator, as higher coverage usually leads to more robust and reliable software.
+* It facilitates decision-making regarding further testing, as developers can focus their efforts on areas with lower coverage.
+
+`pytest` is a very popular testing framework for Python, and it's what we will be using in our assignments. We will also be using the `pytest-cov` plugin to measure test coverage. For your assignments, everything is already defined in the `pyproject.toml` file, so you don't need to install anything extra after installing the local package.
+
+If you want to install `pytest` and `pytest-cov` manually, follow these steps:
+
+```shell
+pip install pytest pytest-cov
+```
+
+Then run `pytest` with the `--cov` flag:
+
+```shell
+pytest tests/ --cov
+```
+
+> **Note**: Remember that a high coverage doesn't guarantee bug-free code, as it only shows which parts of the code are executed during testing, not if the tests are effective or meaningful. Don't writ unnecessary tests just to increase coverage.
+
+## HTML Reports
+
+Sometime you want to see exactly what lines are not being covered by tests. To answer that question, you can generate an HTML report.
+
+### Using `pytest-cov` plugin
+
+Run `pytest` with the `--cov` flag, specifying the source directory and the desired output format (in this case, 'html'):
+
+```shell
+pytest --cov=my_project --cov-report html tests/
+```
+
+Note that now we must specify the coverage source directory, which is the directory containing the Python files that we want to measure coverage for. In this case, it's the `my_project/` directory.
+
+This command will generate an HTML report in the `htmlcov/` directory by default.
+
+Open the `index.html` file in the `htmlcov/` directory using a web browser. This will display the test coverage report, including the percentage of coverage for each file, and the lines that are covered or missed by the tests.

assignments/assignment_1/README.md

@@ -32,7 +32,7 @@ These are the code requirements for part one:
     4. Ensures `value` is a `float` (with the appropriate data cleaning if required, and do remove the `NaN`s).
     5. Filters only the data where `region` equal to `PT` (Portugal).
     6. Save the resulting data frame to the `data` folder as `pt_life_expectancy.csv`. Ensure that no numerical index is saved.
-3. Verify that your code runs by running `pytest life_expectancy --cov`.
+3. Verify that your code runs by running `pytest life_expectancy --cov`[^1].
 
 If everything runs, congrats! Move on to the next part.
 
@@ -60,3 +60,5 @@ Now, let's create a CI pipeline for this project. We will use GitHub Actions for
 3. Create a pull request from `ci` to `main`. Don't merge it yet! If the workflow triggers were correct, GitHub should try to run the workflow. If it doesn't or if it fails, try to fix it with additional commits to the `ci` branch.
 4. Add a badge to the `README.md` file that shows the status of the pipeline. You can find the badge in the `Actions` tab of the repo. Select the workflow run and then click the "..." button: a "Create status badge" option should appear. Open the `ci` branch on your local machine (a quick way to do this, if you haven't created a local `ci` branch yet, is to use the `git switch ci` command), paste the provided markdown to the project's `README.md` and push this commit.
 5. Merge the pull request when the pipeline succeeds.
+
+[^1]: Do you want to know what the `--cov` flag does? It's a flag for the `pytest` command that tells it to run the code coverage tool. You can read more about it [here](06_testing/coverage.md).