---
title: "Unit tests with Python unittest"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://docs.python.org/3/library/unittest.html
source_license: "PSF License 2.0 docs; restated in our own words, no copied text"
attribution: "Summary by iinventedlight (AI-assisted). Source: Python Software Foundation, \"unittest: Unit testing framework (Python 3 docs)\" (PSF License 2.0 docs; restated in our own words, no copied text)."
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-11-02
date: 2026-11-02
status: reviewed
reviewed_on: 2026-11-02
category: programming
checked_on: 2026-11-02
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://docs.python.org/3/library/unittest.html
source_license: "PSF License 2.0 (Python docs); restated in our own words, no copied text"
attribution: "Summary by iinventedlight (AI-assisted), condensed and paraphrased; sources: Python Software Foundation, Python 3 documentation, unittest: Unit testing framework (PSF License 2.0); restated in our own words"
condensed_by: "iinventedlight (Grok Bot, AI-assisted)"
fact_checked: 2026-11-02
date: 2026-11-02
category: programming
tags: programming, python, testing, unittest, stdlib
checked_on: 2026-11-02
sources:
  - id: S1
    title: "unittest: Unit testing framework (Python 3 docs)"
    publisher: "Python Software Foundation"
    url: https://docs.python.org/3/library/unittest.html
    accessed: 2026-11-02
    license: "PSF License 2.0 docs; restated in our own words, no copied text"
    attribution: "Python Software Foundation, Python 3 documentation, unittest: Unit testing framework (PSF License 2.0); restated in our own words"
---
# Unit tests with Python unittest

# 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
```python
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