Generating Test Coverage Reports in Python: A Comprehensive Tutorial


Testing is an integral part of software development. It ensures that the code being written is functional and meets the requirements specified. However, testing alone is not sufficient to guarantee a high-quality product.

Test coverage reports are an essential tool for assessing the effectiveness of your test suite by identifying areas of code that have not been exercised during testing. In simple terms, a test coverage report provides information about which lines of code were executed during testing and which were skipped.

By analyzing this data, developers can identify gaps in their test suite and refine it accordingly to achieve better coverage. This way, they can ensure that they have tested every line of code and catch any potential bugs or issues before they make their way into production.

This tutorial will take you through everything you need to know about generating test coverage reports using Python. We will start by setting up our environment with the necessary packages such as pytest and coverage, then move on to writing effective test cases using best practices.

Afterward, we will demonstrate how to use coverage to generate reports and analyze them for insights into how well your code has been tested. There will also be sections covering customizing your reports output format, filtering unwanted files or directories from the report, integrating with continuous integration tools like Jenkins or Travis CI and more advanced topics like branch coverage and cyclomatic complexity metrics.

We believe this tutorial will provide a comprehensive guide for developers looking to improve their understanding of generating test coverage reports in Python while helping them write better tests for their applications. So without further ado let’s get started!

Setting Up the Environment

Before we can start generating test coverage reports in Python, we need to ensure that our environment is set up correctly. This involves installing necessary packages, such as coverage and pytest, and creating a virtual environment for testing.

Installing Necessary Packages

The first step in setting up our environment is to install the necessary packages. We’ll need coverage, which is a Python package that measures code coverage during testing. We’ll also need pytest, which is a popular testing framework for Python.

To install these packages (and any other necessary packages), we can use pip:

pip install coverage pytest

If you’re working on a larger project with multiple dependencies, you may want to consider using a tool like pipenv or conda to manage your project’s dependencies.

Creating a Virtual Environment for Testing

A virtual environment allows us to create an isolated environment with its own set of dependencies. This ensures that our tests run consistently across different machines and environments.

To create a virtual environment, we’ll use the venv module that comes with Python 3:

python -m venv env

This will create a new directory called “env” in our current working directory. To activate the virtual environment, we’ll run:

source env/bin/activate (Linux/Mac) .\env\Scripts\activate.bat (Windows)

We’re now ready to start writing test cases and generating test coverage reports!

Writing Test Cases

Test cases are a critical component of software development, as they help ensure that code behaves as expected and doesn’t introduce regressions. Writing effective test cases is essential to get the most out of automated testing tools like coverage. Here are some best practices to consider when writing test cases:

Best Practices for Writing Effective Test Cases

1. Be Specific: The more specific your test case is, the easier it will be for developers to reproduce and fix issues. Name the behavior you’re testing, describe the inputs used in the test case, and document what the expected output should be.

2. Test One Thing at a Time: Focus on a single behavior or feature in each test case so that you can pinpoint which part of your code is causing an issue if something goes wrong.

3. Cover All Possible Scenarios: Think about all possible inputs and situations that could occur with your codebase and create appropriate tests.

Examples of Test Cases in Python

Let’s consider a hypothetical example where we want to write tests for a simple calculator class:


class Calculator: def add(self, a, b):

return a + b def subtract(self, a, b):

return a - b

Here’s an example of how we might write some test cases using Python’s built-in unittest library:

python import unittest

from calculator import Calculator class TestCalculator(unittest.TestCase):

def setUp(self): self.calculator = Calculator()

def test_addition(self): self.assertEqual(self.calculator.add(2, 2), 4)

def test_subtraction(self): self.assertEqual(self.calculator.subtract(4, 1), 3)

if __name__ == '__main__': unittest.main()

In this example, we’ve created two test cases for our calculator class: one to test addition and one to test subtraction. We also used the setUp method to create an instance of our Calculator class before each test case runs, so that we have a clean slate for each test.

Running Tests with Coverage

When you have written your test cases, you will need to run them through coverage and generate a report. This is done by using the coverage run command followed by the name of the test file. For example, if you have a test file named, you can run it with coverage by typing coverage run

Coverage will then execute all of the tests in that file and record which lines of your code were executed during each test. Once all tests are completed, coverage will generate a report that shows how much of your code was covered by the tests.

Coverage Report Analysis

Analyzing the results of your coverage report is essential to understanding how well your unit tests are covering your code. When analyzing the report, look for sections that show low coverage percentages or areas where there are many missed lines.

One way to analyze the report is to examine each file individually and see which lines were not covered by any tests. If there are many uncovered lines in a particular section of code, it may indicate a problem with your unit testing or that section of code may need more thorough testing.

Another useful tool for analysis is viewing the report in HTML format. This allows for easy navigation through different files and highlights uncovered lines in red so they can be quickly identified.

Coveralls Integration

Coveralls is a popular online service used to track code coverage over time and across multiple builds. It integrates easily with Python projects using Travis CI or other continuous integration tools.

To use Coveralls, first create an account on their website and link it to your GitHub repository. Next, add Coveralls as a service in Travis CI so that it can automatically submit results after each build runs.

If everything is set up correctly, you should see your coverage results on the Coveralls website. You can also configure Coveralls to send notifications when coverage drops below a certain threshold or if there are any other issues with your unit tests.

Customizing Coverage Reports

Test coverage reports can be customized to fit different needs and preferences. This section introduces some of the ways that coverage reports can be tailored to display information in a more understandable or visually appealing manner, as well as how to filter out unwanted information from the report.

Changing Output Formats

By default, coverage generates a report in text format that shows the percentage of lines executed in each file. However, it is possible to generate reports in other formats such as HTML, XML, or JSON. The HTML output format creates a web page that displays annotated source code with colors representing different levels of test coverage.

This format can make it easier for developers to identify which lines of code need more testing and which are already well covered. To generate an HTML report for your Python project using coverage, you can run the following command: “`

coverage html 

This will create an `htmlcov` directory containing all the needed files for viewing an HTML report of your test coverage.

Filtering Out Unwanted Files or Directories from the Report

In some projects, there may be directories or files that do not require testing and should therefore be excluded from the test coverage report. This is particularly useful when dealing with third-party libraries or other external dependencies.

To exclude files or directories from being considered during code coverage evaluation, create a `.coveragerc` file at your project’s root directory with this content:


omit = /*,/*,,

This will exclude both directories (directory1 and directory2) and specific files (file1 and file2) from being included in code-coverage calculations.

In addition to these basic customizations shown above, there are many other ways you can customize your test-coverage reports such as creating a custom template or using different colors to represent coverage levels. Taking some time to customize your reports can make them more engaging and effective in helping you identify areas of your code that need further testing and improvement.

Integrating Coverage with Continuous Integration Tools

Setting up coverage to work with Jenkins

Jenkins is a popular open-source automation server that can be used for continuous integration. With a few simple steps, it can also be configured to work with coverage reports generated by our tests. To set up Jenkins to work with coverage, we need to install the “Cobertura plugin” and “Python plugin.” Once installed and configured, we can use the Cobertura plugin to generate HTML reports based on our test results.

We can also configure Jenkins to break builds if the test coverage score falls below a certain threshold. We first need to install the Cobertura and Python plugins in Jenkins from its “Plugin Manager.” Then we create a new job in Jenkins which will run our Python tests.

In the configuration page of this job, we must set up two build steps – one for running our Python tests using pytest/cov and another for creating an XML report using Cobertura. We need to configure publishing of Cobertura reports using the “Post-Build Actions” section of Jenkins.

Setting up coverage to work with Travis CI

Travis CI is another popular continuous integration tool used by many developers today. It supports multiple programming languages including Python and integrates well with GitHub repositories where most open-source projects are hosted these days. Setting up Travis CI is relatively easy as it has built-in support for running tests using pytest/cov.

To integrate Travis CI with test coverage, we first need to add a “.travis.yml” file in our project’s root directory specifying the configuration options such as language (set as python), versions of python (if more than one), installation commands needed (such as pip installs) etc. In addition, we also add code snippets in this file which will enable us to run pytest command along with coverage option (pytest –cov) and generate coverage reports in a specific format.

We need to specify the location of our coverage reports and configure Travis to parse them for us. With these configurations in place, we can automatically run our tests on Travis CI and get notified of any failures or coverage issues in real-time.

Integrating test coverage with continuous integration tools is essential for ensuring that code is well-tested before it is released. In this article, we discussed how to set up coverage with two popular continuous integration tools – Jenkins and Travis CI. By following the steps outlined here, you should be able to generate comprehensive test coverage reports that will help you identify areas of your code that are not properly tested.

With the help of these tools, you can also avoid releasing code that has low test coverage or contains bugs that could have been caught by testing early on in the development cycle. So take advantage of these powerful tools to improve your testing process and deliver high-quality software products.

Advanced Topics

Using branch coverage to analyze code paths

Test coverage reports are an invaluable tool to ensure that your Python code is thoroughly tested. However, traditional test coverage only indicates which lines of code were executed during the tests.

What about if there are multiple execution paths within a function or method? This is where branch coverage comes into play.

Branch coverage measures which branches within the code have been executed during testing. With branch coverage, you can analyze how many conditional statements were actually evaluated as true or false, offering a more thorough understanding of the test suite’s effectiveness.

Python’s “coverage” package can be configured to execute multiple branches in your code and report back on their results. Keep in mind that achieving 100% branch coverage does not necessarily mean that all possible combinations have been executed.

It simply means that every possible branch within each function has been executed at least once. Therefore, it is important to use other testing techniques such as boundary value analysis and equivalence partitioning along with branch coverage.

Measuring code complexity with cyclomatic complexity metrics

Cyclomatic complexity metrics provide insight into how complex a particular piece of Python code is by analyzing its structure and control flow. Cyclomatic complexity is based on the number of independent paths through a program’s source-code graph, which can be calculated using various formulas based on control structures like loops and conditionals.

The higher the cyclomatic complexity score for a particular piece of Python code, the more difficult it will be to maintain, debug and refactor it because there are simply too many potential branches in the source-code graph. Therefore, reducing cyclomatic complexity should always be a goal when writing high-quality Python programs.

One way to reduce cyclomatic complexity is by breaking up large functions or methods into smaller ones with clear responsibilities – this also makes it easier to unit-test individual components of your overall program. Additionally, using control structures like “for” loops instead of “while” loops can help to reduce the number of branches in a program’s source-code graph.

While cyclomatic complexity metrics can be a helpful tool to measure code quality, they should not be used as the only metric to determine the effectiveness of your testing suite. Instead, it should be used together with other testing techniques and analysis tools to give a complete picture of your code’s overall quality.


Throughout this tutorial, we have explored the importance of generating test coverage reports in Python. We began by discussing what test coverage reports are and why they are important. Then, we walked through setting up the environment necessary to generate these reports, including installing packages like coverage and pytest and creating a virtual environment for testing.

Next, we talked about best practices for writing effective test cases in Python and provided various examples. We then showed how to use coverage to run tests and generate coverage reports, as well as how to customize these reports by changing output formats or filtering out unwanted files or directories.

Moreover, we discussed how to integrate coverage with continuous integration tools such as Jenkins or Travis CI. We delved into advanced topics like measuring code complexity with cyclomatic complexity metrics.

Encouragement to Use Test Coverage Reports in Future Projects

Generating test coverage reports is an essential part of developing high-quality software applications. Not only do they help identify areas where code is not being tested thoroughly enough but also provide valuable insights into the overall health of an application’s codebase. By following the steps outlined in this tutorial and implementing a robust testing process that includes generating comprehensive test coverage reports regularly, you’ll be able to catch bugs before they reach production environments while also ensuring that your application is running at its highest possible level of efficiency.

So why not start integrating test coverage reports into your development workflow today? With a little bit of effort upfront, you’ll be able to reap significant rewards down the road by delivering better software faster while reducing risk for your users.

Related Articles