From 7aa832e3d10122f788394e4792453094ce4814d5 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Sun, 2 Oct 2022 12:31:11 +0100 Subject: [PATCH] Contributing.md: test coverage notes --- Contributing.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Contributing.md b/Contributing.md index 4d7fc9fc..6d60065a 100644 --- a/Contributing.md +++ b/Contributing.md @@ -244,6 +244,42 @@ handy if you want to step through the testing code to be sure of anything. Otherwise, see the [pytest documentation](https://docs.pytest.org/en/stable/contents.html). +### Test Coverage +As we work towards actually having tests for as much of the code as possible +it is useful to monitor the current test coverage. + +Running `pytest` will also produce the overall coverage report, see the +configured options in `pyproject.toml`. + +One issue you might run into is where there is code that only runs on one +platform. By default `pytest-cov`/`coverage` will count this code as not +tested when run on a different platform. We utilise the +`coverage-conditional-plugin` module so that `#pragma` comments can be used +to give hints to coverage about this. + +The pragmas are defined in the +`tool.coverage.coverage_conditional_plugin.rules` section of `pyproject.toml`, +e.g. + +```toml +[tool.coverage.coverage_conditional_plugin.rules] +# Yes, the sense of all of these is inverted, because else it ends up +# inverted at *every* use. +sys-platform-win32 = "sys_platform != 'win32'" +... +``` +And are used as in: +```python +import sys + +if sys.platform == 'win32': # pragma: sys-platform-win32 + ... +else: # pragma: sys-platform-not-win32 + ... +``` +Note the inverted sense of the pragma definitions, as the comments cause +`coverage` to *not* consider that code block on this platform. + --- ## Imports used only in core plugins