← Reference notes

Unit tests with Python unittest

Summary

unittest is Python's built-in test framework. Subclass unittest.TestCase, write methods whose names start with test, and use assertions such as assertEqual and assertRaises. Put shared setup in setUp and tearDown. Run the tests with python -m unittest (it discovers them automatically) or unittest.main().

Draft. License: CC BY 4.0 (this summary). Sources: [S1] Python Software Foundation, "unittest: Unit testing framework (Python 3 docs)" (PSF License 2.0 docs; restated in our own words, no copied text).

Example

import unittest

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

class AddTests(unittest.TestCase):
    def test_ints(self):
        self.assertEqual(add(2, 3), 5)
    def test_type_error(self):
        with self.assertRaises(TypeError):
            add(1, None)

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

Facts

• id: F1 claim: Tests are methods of a unittest.TestCase subclass whose names start with 'test'. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F2 claim: Assertion methods include assertEqual, assertTrue, assertIn, assertIsNone and assertAlmostEqual; on failure they report both values. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F3 claim: assertRaises can be used as a context manager: with self.assertRaises(ValueError): ... confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F4 claim: setUp() runs before each test method and tearDown() after it; setUpClass/tearDownClass are class methods run once per class. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F5 claim: python -m unittest discover (or plain python -m unittest) finds test*.py files by default; -v gives verbose output. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F6 claim: unittest.main() runs the tests in a module when it is executed as a script. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F7 claim: Decorators @unittest.skip, @unittest.skipIf and @unittest.expectedFailure mark tests to skip or expect to fail. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F8 claim: self.subTest() reports each case of a loop separately instead of stopping at the first failure. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02
• id: F9 claim: unittest.mock (standard library since 3.3) replaces objects with mocks, e.g. via mock.patch. confidence: medium date: 2026-11-02 sources: [S1] license: CC BY 4.0 checked_on: 2026-11-02

Caveats

• pytest can run unittest-style tests too; pick one style per project.
• Tests should not depend on execution order.

Pointers

• id: P1 answers: Full details and updates where: https://docs.python.org/3/library/unittest.html access: free, public web page

@misc{iil_note_yzrt49jf,
  author = {{iinventedlight Library}},
  title = {{Unit tests with Python unittest}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-02},
  url = {https://iinventedlight.com/library/reference/python-docs/python-unittest/},
  note = {Permanent ID iil:note:yzrt49jf. License: CC-BY-4.0. Summary of https://docs.python.org/3/library/unittest.html.},
}

For language models and agents: start at /llms.txt. This page in Markdown: /library/reference/python-docs/python-unittest.md.