unittest — Test Suites & Discovery

• Run all tests with python -m unittest discover.
• Understand the naming rules discovery relies on.
• Run a single file, class, or method while debugging.
• Organise tests in a tests/ folder.

$ python -m unittest          # finds & runs every test_*.py
$ python -m unittest discover # same, explicit

........F...
----------------------------------------------------------------------
Ran 12 tests in 0.04s
FAILED (failures=1)

The naming rules discovery uses

files    must match  test*.py     (default pattern)
classes  must inherit unittest.TestCase
methods  must start   test_

Break any of these and the test silently won't be discovered — a
classic "why isn't my test running?" trap.

Discover from a folder

project/
├─ mycode/
│   └─ bank.py
└─ tests/
    ├─ __init__.py
    ├─ test_bank.py
    └─ test_inventory.py

$ python -m unittest discover -s tests       # search the tests/ folder
$ python -m unittest discover -s tests -p "test_*.py"   # custom pattern

Run a subset while debugging

# one file
$ python -m unittest tests.test_bank
# one class
$ python -m unittest tests.test_bank.TestBankAccount
# one method (laser focus on the failing test)
$ python -m unittest tests.test_bank.TestBankAccount.test_overdraw_raises

Useful flags

-v       verbose: print each test name + ok/FAIL
-f       failfast: stop at the first failure
-b       buffer: hide print() output unless the test fails
-k word  run only tests whose name contains "word"

Building a suite in code (rarely needed)

import unittest
from tests import test_bank

suite = unittest.TestLoader().loadTestsFromModule(test_bank)
unittest.TextTestRunner(verbosity=2).run(suite)

You almost never write this by hand — discovery does it. But it shows what discovery is doing under the hood.

shop/
├─ shop/
│   ├─ __init__.py
│   ├─ cart.py
│   └─ pricing.py
├─ tests/
│   ├─ __init__.py
│   ├─ test_cart.py
│   └─ test_pricing.py
└─ README.md

# tests/test_pricing.py
import unittest
from shop.pricing import apply_discount

class TestPricing(unittest.TestCase):
    def test_no_discount_under_100(self):
        self.assertEqual(apply_discount(50), 50)
    def test_discount_over_100(self):
        self.assertEqual(apply_discount(200), 180)

# from the project root:
$ python -m unittest discover -v
test_no_discount_under_100 (tests.test_pricing.TestPricing) ... ok
test_discount_over_100 (tests.test_pricing.TestPricing) ... ok
test_add_item (tests.test_cart.TestCart) ... ok
...
Ran 9 tests in 0.01s
OK

# debugging just one failing area:
$ python -m unittest tests.test_pricing -v

Read the diff

The tests/ folder mirrors the package, each module has its test_* counterpart, and one command runs everything. While debugging the pricing module you narrow to just tests.test_pricing for instant feedback. This layout + discovery is the standard for every Python project — and pytest (next lesson) uses the same conventions.

Discovery finds tests by convention (test*.py files, TestCase classes, test_* methods) — break a name and it silently won't run. python -m unittest discover runs everything; the dotted path or -k runs a subset for debugging. Keep tests in a tests/ folder mirroring your package. That wraps up unittest; next, pytest does the same with far less boilerplate.