Skip to content

Commit 482fc70

Browse files
Added a coverage.py entry in the Testing section (#29)
* Added a coverage.py entry in the Testing section * Fixed small typo --------- Co-authored-by: Carlos Martinez <c.martinez@runtime-revolution.com>
1 parent 08b88e8 commit 482fc70

File tree

1 file changed

+72
-0
lines changed

1 file changed

+72
-0
lines changed

docs/testing/8_coverage.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Coverage
2+
3+
<https://coverage.readthedocs.io/>
4+
5+
Coverage.py is a tool for measuring code coverage of Python programs. It monitors your program, noting which parts of the code have been executed, then analyzes the source to identify code that could have been executed but was not. Coverage.py won't fix anything in your code but will show you parts of your code that aren't being tested.
6+
7+
This guide will show you how to run coverage.py and generate a final report in html.
8+
9+
## Running coverage
10+
11+
After installing, running coverage on your test suite is as simple as calling the following command:
12+
13+
```bash
14+
coverage run manage.py test
15+
```
16+
17+
This will seemingly run your tests and do nothing else, but it will create a .coverage file in the current working directory. You can open that file but it will be complicated to read anything, run the command `coverage report` to see the results.
18+
19+
## Better output
20+
21+
You can just do a `coverage run` and then a `coverage report` or you can have something better like storing the results in an html file and then open it in the browser. To do this, instead of running `coverage report`, you can run:
22+
23+
```bash
24+
coverage html --skip-empty
25+
```
26+
27+
This will generate a folder called htmlcov. Inside that folder, you will see a lot of files, mainly the index.html file; if you open this file, you will see a much better result.
28+
29+
The flag `--skip-empty` will skip empty files. For example, empty "__init__.py" files won't be included in the html report because you don't need that kind of noise in your report.
30+
31+
## Ignoring folders, files or code
32+
33+
To ignore code that you don't want to be tested, you can create a file called ".coveragerc" in the same directory you will be running coverage. Here's an example:
34+
35+
```text
36+
[run]
37+
omit =
38+
*/tests/*
39+
folder1/*
40+
folder2/*
41+
folder3/*
42+
path/to/file/the_file.py
43+
if self.debug:
44+
if settings.DEBUG
45+
```
46+
47+
This example will do the following:
48+
49+
- "\*/tests/\*": Ignore any directory called "tests" in the project structure and its contents;
50+
- "folder1/\*", "folder2/\*", "folder3/\*": These 3 folders and their contents will be ignored;
51+
- "path/to/file/the_file.py": Ignore any directory called "tests" in the project structure and its contents;
52+
- `if self.debug:` and `if settings.DEBUG`: The line itself and everything inside its scope will be ignored;
53+
54+
## Complete example for Django project using Make
55+
56+
With coverage installed and the .coveragerc file defined, you can use this make command to run your tests, generate and open an html report:
57+
58+
```make
59+
test_with_report:
60+
cd tutorial && coverage run manage.py test && coverage html --skip-empty --skip-covered
61+
open tutorial/htmlcov/index.html
62+
```
63+
64+
This will get your basics covered. It will run your tests through coverage, then it will generate an html report where it skips empty files and files where you have 100% coverage, and finally it will open the generated html report in your browser.
65+
66+
## Final note
67+
68+
This doesn't work with pytest. For pytest, you need something called [pytest-cov](https://pytest-cov.readthedocs.io/).
69+
70+
## Documentation
71+
72+
You can and should check the documentation [here](https://coverage.readthedocs.io) so you can see all that is possible with the coverage.py tool.

0 commit comments

Comments
 (0)