Running Unittests in Python: A Step-by-Step Guide


Why Unit Testing is Important for Python Developers

Unit testing is an essential part of the software development process that involves testing individual units or components of code to ensure they function correctly. This helps to identify and isolate defects early on in the development cycle, improving code quality and reducing the likelihood of bugs making it into production.

Without unit tests, developers may not be aware of issues or errors in their code until they are discovered by users. This can lead to more significant problems down the line, such as system crashes and data loss, which can ultimately harm a company’s reputation and revenue streams.

An Overview of Python’s Unittest Module

Python’s unittest module provides a framework for writing and running unit tests in Python. It comes bundled with Python and provides a comprehensive set of tools for developers to create robust test suites and validate their code.

Some benefits of using unittest include:

  • Straightforward syntax: unittest follows the Arrange-Act-Assert pattern, making it easy for developers to write clear, concise test cases.
  • Test discovery: unittest automatically discovers all tests within a given directory.
  • Seamless integration with popular IDEs: PyCharm and Visual Studio Code both have built-in support for running unittest tests.
  • In-built fixtures: The setUp() and tearDown() methods allow developers to create fixtures that will be run before each test case.

Overall, Python’s unittest module provides a simple yet powerful framework for ensuring code quality via unit testing. The next section will cover setting up the environment required to begin writing unit tests in Python.

Setting up the Environment

Python’s unittest module is built-in to the Python standard library and can therefore be immediately used without any installation required. However, it is always a good idea to use a virtual environment when running tests to ensure that dependencies and packages are isolated from other projects on your machine.

Installing Python and the unittest module

The first step in setting up your testing environment is to ensure you have the correct versions of Python and the unittest module installed on your machine. Check which version of Python you have installed by typing python --version into your terminal or command prompt. If you don’t have Python installed, visit to download the latest version for your system.

To check if you have the unittest module already installed, open a terminal or command prompt and type python -m unittest. If an error message appears stating that ‘No module named unittest’ could be found, then it means that the module has not been installed on your system.

To install unittest, navigate back to your terminal or command prompt window and run pip install unittest. This will install the latest version of unittest in your current environment.

Creating a virtual environment for testing

Now that we have Python and our testing framework set up correctly, it’s time to create an isolated virtual environment specifically for our unit tests. To do this, we will make use of venv which comes pre-installed with versions 3.3 onwards of Python.

Firstly create a new directory where you want to house all of your project files by typing mkdir my_project into your terminal or command prompt window. Once inside this directory run python -m venv my_env, this will create a new folder called ‘my_env’ which contains everything necessary for our virtual environment.

Now activate this new virtual environment by running source my_env/bin/activate on Mac/Linux or my_env\Scripts\activate on Windows. When you are finished working in this environment, simply type deactivate to exit out of the virtual environment.

Writing Test Cases

Test cases are the heart of unit testing. They allow you to systematically verify that your code is working correctly. In this section, we’ll discuss what a test case is, and how to write basic test cases for simple functions.

Understanding the Anatomy of a Test Case

A test case consists of three parts: setup, exercise, and verify. The setup part is where you initialize any objects or data structures needed for the test. The exercise part is where you actually call the function being tested with some input parameters.

In the verify part, you compare the output of the function to an expected result. For example, let’s say we have a simple function that adds two numbers together:

def add_numbers(a, b): return a + b

To create a test case for this function using unittest module in Python 3.x:


import unittest class TestAddNumbers(unittest.TestCase):

def setUp(self): # Initialize any objects or data structures needed for testing

pass def test_add_numbers(self):

# Call the function being tested with some input parameters result = add_numbers(2, 3)

# Compare output to expected result self.assertEqual(result, 5)

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

Writing Basic Test Cases for Simple Functions

Now that we understand what a test case is all about let’s write some basic test cases for our add_numbers function.

python import unittest

class TestAddNumbers(unittest.TestCase): def setUp(self):

pass def test_add_numbers_with_positive_integers(self):

result = add_numbers(2, 3) self.assertEqual(result, 5)

def test_add_numbers_with_negative_integers(self): result = add_numbers(-2, -3)

self.assertEqual(result, -5) def test_add_numbers_with_floats(self):

result = add_numbers(2.0, 3.5) self.assertEqual(result, 5.5)

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

We’ve written three test cases for the add_numbers function: one with two positive integers as input parameters, one with two negative integers and one with two floats as input parameters. The assertEqual() method is used to compare the result of the function call to an expected output.

Using Assertions to Check Expected Results

Assertions are an important component of any test case. They are used to check that a condition is true at a certain point in the code.

In Python’s unittest module we have several types of assertions available such as assertEqual(), assertTrue(), assertFalse(), and many others. In our previous example we used assertEqual() method which checks whether two values are equal or not.

There are several other assertions that can be used depending on the type of your function and what you’re trying to achieve in your tests. For example:

python self.assertTrue(expression) # Checks if expression evaluates to True

self.assertFalse(expression) # Checks if expression evaluates to False 
self.assertIs(a, b) # Checks if a and b refer to the same object

Writing effective test cases is crucial for ensuring your code works correctly in all scenarios. By following a systematic approach outlined in this section and using powerful assertions like those provided by Python’s unittest module you can create robust testing suites that will help you catch bugs early on in development cycle saving time and money in long run.

Running Tests with Unittest

Command Line Testing

Once you have written your tests using the unittest module, you can run them from the command line using the unittest discover command. This command will search for and execute all tests that are located in files ending in * To run this command, navigate to the directory containing your test files and enter python -m unittest discover in your terminal window.

You can also specify a specific folder or file to test by adding that path after the discover argument. For example, if my tests were only located in a folder called “tests”, I could run python -m unittest discover tests/.

When running tests from the command line, it is important to note that any print statements within test methods will show up during testing. This can be helpful for debugging purposes, but it is best practice to remove these statements before committing code.

IDLE / IDE Testing

Most Integrated Development Environments (IDEs) come with built-in support for running unit tests. For example, PyCharm has a built-in test runner that allows you to easily execute your tests and view their results within the IDE itself. To run your tests from within PyCharm:

1. Click on “Run” at the top of the screen

2. Click on “Edit Configurations”

3. Click on “+” to add a new configuration

4. Select “Python Tests” -> “Unittests”

5. Name your configuration and select which specific test or directory of tests you want to run.

6. Click on “OK” and then click on “Run” again.

Running unit tests within an IDE is often more convenient than running them from the command line because the IDE will often provide more detailed feedback on failed tests, including information on which lines in the test code caused the failure. Additionally, IDEs often come with built-in debugging tools that can be helpful for diagnosing difficult-to-find bugs.


Running unit tests is critical for ensuring the stability of your codebase. By using Python’s built-in unittest module, you can easily create and run tests to ensure your code is working as expected.

Whether you choose to run your tests from the command line or within your favorite IDE, it is important to understand how to interpret test results and effectively debug any issues that arise. Remember, unit testing should be an ongoing process throughout your development cycle.

As new features are added or changes are made to existing code, it is important to update and maintain your test suite accordingly. By following best practices for unit testing in Python, you can ensure that your codebase remains robust and reliable over time.

Advanced Testing Techniques

Using setUp() and tearDown() methods to prepare test data

One of the key aspects of unit testing is ensuring that each test case is independent of any other cases. One way to achieve this is by using the setUp() and tearDown() methods provided by the unittest module. The setUp() method is called before each test case, and can be used to set up any necessary data or objects that will be used in the test.

The tearDown() method, on the other hand, is called after each test case, and can be used to clean up any resources (such as temporary files) created during the test. For example, imagine we have a function that reads data from a file and returns it as a list.

Before we can run any tests on this function, we need to create a temporary file with some sample data. We could use setUp() to create this file before each test case, and tearDown() to delete it afterwards:

import unittest import tempfile

def get_data(filename): # Read data from filename

pass class TestData(unittest.TestCase):

def setUp(self): self.temp_file = tempfile.NamedTemporaryFile(delete=False)

self.temp_file.write(b"1\n2\n3\n") self.temp_file.close()

def tearDown(self): # Delete temporary file

pass def test_get_data(self):

data = get_data( self.assertEqual(data, [1, 2, 3])

In this example, we’ve created a temporary file in setUp(), which contains some sample data. We then use this file in our test_get_data() method to make sure our get_data function returns the correct output.

Mocking objects and functions for more complex testing scenarios

Sometimes our code depends on external services or libraries, which can make testing more difficult. For example, if we have a function that makes an API call to a third-party service, we don’t want to have to rely on that service being available every time we run our tests.

One solution to this problem is to use “mock” objects and functions, which allow us to simulate the behavior of external dependencies. The unittest module provides a built-in library for creating mock objects, called unittest.mock.

We can use this library to create fake objects with the same interface as our real dependencies. For example, if we have a function that uses the requests library to make an HTTP request:

import requests def get_data(url):

response = requests.get(url) return response.json()

We could create a mock object for the requests.get() method using unittest.mock:

from unittest.mock import patch

class TestGetData(unittest.TestCase): @patch('requests.get')

def test_get_data(self, mock_get): mock_get.return_value.json.return_value = {'data': [1, 2, 3]}

data = get_data('') self.assertEqual(data['data'], [1, 2, 3])

In this example, we’ve used patch() from the unittest.mock library to replace requests.get() with a fake function. We then set up some dummy data using return_value and json.return_value attributes of our fake response object.

Using parameterized tests to run multiple variations of a test case

In some cases, it may be useful to run the same test case with multiple input values. The unittest module provides built-in support for parameterized tests through the use of decorators.

To create a parameterized test case in Python’s unittest module requires using one or several decorators in your unit testing code as shown below:

import pytest

import math @pytest.mark.parametrize("param1, param2, expected_output", [(4, 5, 9), (0, 5, 5), (-4,-5,-9),(0,0,0)])

def test_add_numbers(param1,param2,expected_output): assert math.add_numbers(param1,param2) == expected_output

Here we created the test_add_numbers() test case which tests our add_numbers() function by passing in different input values using the decorator @pytest.mark.parametrize. The decorator specifies a list of tuples each representing a unique set of input arguments and reference output.

The arguments in each tuple are local variables that will be passed to the test function as parameters. Using parameterized tests can significantly reduce the amount of code you need to write for testing multiple variations of your functions or classes.

The Art of Analyzing Test Results

The primary purpose of unit testing is to detect and fix bugs early in the software development cycle. In order to achieve this goal, it’s essential to analyze test results with precision and accuracy.

Python’s unittest module provides various tools for analyzing test results, including output messages that offer clues about where the tests failed and what went wrong. When running unittests, you’ll observe different types of output messages that provide useful information about the tests.

For instance, when a test case passes successfully, unittest displays an “OK” message. However, when one or more test cases fail, the output message becomes more informative by displaying details about which particular test case failed and how it failed.

It’s important to note that running unit tests alone doesn’t guarantee bug-free code; rather, it helps to identify potential issues early on so that they can be fixed promptly. Therefore, once you run your tests analyze the results thoroughly; pinpointing where the code failed is just as important as understanding why it failed in the first place.

Understanding Output Messages from Unittest

One of unittest’s key strengths is its ability to provide detailed output messages that help you understand what went wrong during testing. These messages are displayed in plain text on your console or integrated development environment (IDE), depending on which environment you are using. When analyzing these output messages from unittests, it is essential first to understand their structure and meaning.

Typically, errors will be accompanied by stack traces or error reports indicating where errors occurred within your code. Moreover, some failures may have raised AssertionError exceptions giving precise information about what went wrong during execution – such as an expected value not being equal to its actual value.

Interpreting Test Results and Identifying Failures

To get accurate results when interpreting test runs in Python’s unittest module requires careful analysis of the output messages. By checking each message, you can determine precisely where the problem is and how to fix it.

Unittest’s output messages usually start with a summary of the test suite’s results, indicating the number of test cases that passed, failed, or raised an error. Along with this summary, unittest also provides detailed information on each test case so you can identify which ones passed and which ones failed.

By analyzing each failure or error message from unittests, you can determine the root cause and take appropriate action to fix it. This process requires careful attention to detail.

In some cases, it may be necessary to run additional tests or debug your code further to get a better understanding of what went wrong. But by using Python’s unittest module and following these best practices for analyzing test results, you’ll be well on your way to building more robust and reliable software applications.

Best Practices for Unit Testing in Python

Unit testing is a critical part of software development, and as such, it’s important to follow best practices when writing unit tests. Here are some tips for writing effective unit tests in Python:

Tips for Writing Effective Unit Tests

1. Write small, focused test cases. Each individual test case should focus on one specific aspect or behavior of the code being tested. This not only makes it easier to identify the cause of any failures but also makes it easier to maintain and update the test suite.

2. Use descriptive and meaningful function names. Test functions should have descriptive names that clearly communicate what is being tested.

This not only helps developers understand what the test is doing but also makes it easier to identify which tests are related, so they can be grouped together or reordered if necessary.

3. Test both positive and negative scenarios. It’s important to not only test scenarios where the code behaves as expected (positive scenarios) but also scenarios where it doesn’t (negative scenarios). This helps ensure that all potential edge cases have been considered and handled appropriately.

Maintaining A Robust Test Suite

In order for a test suite to be effective, it needs to be maintained properly over time. Here are some strategies for maintaining a robust test suite:

The Importance Of Code Coverage

Monitor code coverage regularly. Code coverage measures how much of your code is covered by your tests, so it’s important to monitor this metric regularly in order to identify any areas that may need more testing. Aiming for 100% code coverage may not always be feasible or necessary, but having a high level of coverage can help catch any potential issues early on.

The Role Of Continuous Integration

Integrate testing into your development workflow. Continuous integration (CI) is a process where code changes are automatically built and tested as they are committed to the repository.

This helps ensure that any potential issues are caught early on, before they make it to production. Many CI tools also provide metrics and insights into test results, which can help identify areas for improvement in the test suite.

The Importance Of Test Refactoring

Refactor tests regularly. As code changes over time, so should the associated tests. This may involve updating existing tests to reflect changes in functionality or adding new tests to cover new features or edge cases.

Regularly refactoring your tests helps ensure that they remain relevant and effective over time. By following these best practices for writing unit tests and maintaining a robust test suite, you can help ensure that your code is reliable, maintainable, and of high quality.


This guide has provided a comprehensive overview of how to run unittests in Python using the built-in unittest module. We started by discussing the importance of unit testing and why it’s crucial for developing robust and reliable code.

We then delved into the details of setting up a testing environment, writing test cases, running tests with unittest, and analyzing test results. One key takeaway from this guide is that a well-designed unit test suite can save time and effort in the long run by catching bugs early on in development.

By writing effective test cases and using advanced testing techniques such as mocking and parameterization, developers can ensure that their code is working as expected across different scenarios. Another important point to remember is that unit testing is an iterative process.

As code evolves over time, so too must the corresponding test suite be updated to reflect these changes. By adopting best practices for unit testing in Python, developers can maintain a robust and reliable test suite that helps them catch issues before they become major problems.

Overall, by following the step-by-step guide outlined here, developers can feel confident in their ability to create effective unit tests for their Python projects. By taking the time to write thorough tests at each stage of development, they can ensure that their code is high-quality and reliable for users.

Related Articles