Comprehensive Guide to Python unittest Framework

1. Basic Concepts

1.1 TestCase class – each test case is a subclass of unittest.TestCase .

1.2 Test methods – every test method must start with test_ .

1.3 Assertion methods – examples include assertEqual(a, b) , assertTrue(expr) , assertFalse(expr) , and assertRaises(exception, callable, *args, **kwargs) .

1.4 TestSuite class – combines multiple test cases for batch execution.

2. Example Code

2.1 Simple test case:

import unittest
class SimpleTest(unittest.TestCase):
def test_addition(self):
self.assertEqual(1 + 1, 2)
def test_subtraction(self):
self.assertEqual(3 - 2, 1)
def test_string_length(self):
self.assertTrue(len("hello") > 0)
if __name__ == '__main__':
unittest.main()

2.2 Test suite example:

import unittest
class SimpleTest(unittest.TestCase):
def test_addition(self):
self.assertEqual(1 + 1, 2)
def test_subtraction(self):
self.assertEqual(3 - 2, 1)
def test_string_length(self):
self.assertTrue(len("hello") > 0)
if __name__ == '__main__':
suite = unittest.TestSuite()
suite.addTest(SimpleTest('test_addition'))
suite.addTest(SimpleTest('test_subtraction'))
runner = unittest.TextTestRunner()
runner.run(suite)

3. More Complex Test Cases

3.1 Sample module math_functions.py :

# math_functions.py
def add(a, b):
return a + b
def subtract(a, b):
return a - b

3.2 Corresponding test class:

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
if __name__ == '__main__':
unittest.main()

4. Setup and Teardown

4.1 setUp runs before each test to initialize the environment.

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def setUp(self):
self.numbers = [1, 2, 3, 4, 5]
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
if __name__ == '__main__':
unittest.main()

4.2 tearDown runs after each test to clean up.

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def setUp(self):
self.numbers = [1, 2, 3, 4, 5]
def tearDown(self):
del self.numbers
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
if __name__ == '__main__':
unittest.main()

5. Test Suites and Loaders

5.1 Creating a suite manually:

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
def suite():
suite = unittest.TestSuite()
suite.addTest(MathFunctionsTest('test_add'))
suite.addTest(MathFunctionsTest('test_subtract'))
return suite
if __name__ == '__main__':
runner = unittest.TextTestRunner()
runner.run(suite())

5.2 Using a TestLoader :

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
if __name__ == '__main__':
loader = unittest.TestLoader()
suite = loader.loadTestsFromTestCase(MathFunctionsTest)
runner = unittest.TextTestRunner()
runner.run(suite)

6. Parameterized Tests with subTest

import unittest
from math_functions import add
class MathFunctionsTest(unittest.TestCase):
def test_add(self):
test_data = [
(1, 2, 3),
(-1, 1, 0),
(10, 5, 15),
(0, 0, 0)
]
for a, b, expected in test_data:
with self.subTest(a=a, b=b):
self.assertEqual(add(a, b), expected)
if __name__ == '__main__':
unittest.main()

7. Test Reporting

Using unittest.TextTestRunner with higher verbosity produces detailed reports.

import unittest
from math_functions import add, subtract
class MathFunctionsTest(unittest.TestCase):
def test_add(self):
self.assertEqual(add(1, 2), 3)
self.assertEqual(add(-1, 1), 0)
def test_subtract(self):
self.assertEqual(subtract(3, 2), 1)
self.assertEqual(subtract(10, 5), 5)
if __name__ == '__main__':
loader = unittest.TestLoader()
suite = loader.loadTestsFromTestCase(MathFunctionsTest)
runner = unittest.TextTestRunner(verbosity=2)
runner.run(suite)

8. Advanced Assertion Methods

Examples: assertListEqual(list1, list2) , assertDictEqual(dict1, dict2) .

import unittest
from math_functions import add
class MathFunctionsTest(unittest.TestCase):
def test_add_lists(self):
self.assertListEqual(add([1,2,3], [4,5,6]), [5,7,9])
def test_add_dicts(self):
self.assertDictEqual(add({'a':1,'b':2}, {'a':3,'b':4}), {'a':4,'b':6})
if __name__ == '__main__':
unittest.main()

9. Organizing Test Cases

Tests can be structured into modules and packages. Example package layout:

tests/
│
├── __init__.py
├── test_math_functions.py
└── test_string_functions.py

Define a suite in tests/__init__.py :

# tests/__init__.py
import unittest
from .test_math_functions import MathFunctionsTest
from .test_string_functions import StringFunctionsTest
def suite():
suite = unittest.TestSuite()
suite.addTest(unittest.makeSuite(MathFunctionsTest))
suite.addTest(unittest.makeSuite(StringFunctionsTest))
return suite
if __name__ == '__main__':
runner = unittest.TextTestRunner()
runner.run(suite())

Run the entire test package with:

python -m unittest discover -s tests

Conclusion

The tutorial demonstrates that the unittest framework is a powerful, easy‑to‑use tool for writing high‑quality automated tests in Python, covering everything from basic assertions to advanced suite organization and reporting.