Test Discovery and Running Tests

Test discovery rules (common pattern)

Unittest can discover tests when:

• files match test*.py
• tests are under a folder like tests/
• test methods start with test_

Typical project layout

text

project/
  src/
    app.py
  tests/
    test_app.py

Running discovery

From the project root:

bash

python -m unittest discover

To specify a tests folder:

bash

python -m unittest discover -s tests

Run a specific test module

bash

python -m unittest tests.test_app

Tip

If discovery finds 0 tests, check:

• filenames
• class inherits from unittest.TestCase
• methods start with test_

🧪 Try It Yourself

Exercise 1 – Write a unittest TestCase

pch.exerciseTag pch.exerciseTitle

Exercise 2 – assertRaises

pch.exerciseTag pch.exerciseTitle

Exercise 3 – setUp and tearDown

pch.exerciseTag pch.exerciseTitle

What discovery looks for

commands

python -m unittest discover                 # from the current directory
python -m unittest discover -s tests -t .   # start in tests/, resolve imports from .
python -m unittest discover -p "check_*.py" # a different file pattern
python -m unittest discover -v              # name each test as it runs

diagram Diagram mermaid

  flowchart TD
  D["discover -s tests -t ."] --> W["walk tests/ recursively"]
  W --> P{"filename matches test*.py?"}
  P -->|"no"| SK["ignored"]
  P -->|"yes"| I["import it"]
  I --> C{"TestCase subclasses?"}
  C -->|"yes"| M{"methods starting with test?"}
  M -->|"yes"| R["run them, alphabetically"]
  M -->|"no"| SK

Four things must all be true for a test to run, and each is a silent failure on its own:

1. the file matches test*.py
2. the class subclasses unittest.TestCase
3. the method name starts with test
4. the package is importable from the top-level directory

-s and -t are different, and that is the usual problem

• -s is where to start looking for test files.
• -t is the top-level directory, which is what gets put on sys.path.

Running discover -s tests alone makes tests/ the top level, so from calc import add fails — calc.py lives one level up. Measured working invocation:

what actually works

python -m unittest discover -s tests -t .

with an __init__.py inside tests/ so it is a package.

A suite that finds nothing exits successfully

Ran 0 tests is not an error. A green CI run can mean every test passed, or that discovery matched nothing at all. Assert the count if that distinction matters:

guard

python -m unittest discover -v 2>&1 | tee out.txt
grep -q "Ran 0 tests" out.txt && exit 1

Reading the result line

Measured on a suite with eight tests:

output

Ran 8 tests in 0.004s
 
FAILED (skipped=2, expected failures=1, unexpected successes=1)

Every counter there matters, and the run failed without a single ordinary failure — because of the unexpected success, which the next page covers.

See it move

sketch Why a test did not run p5.js Pause Restart

Four conditions must all hold before unittest runs a method. Any one of them failing is silent.

Check yourself

pch.quizTag pch.quizDefaultTitle

1. What is the difference between -s and -t in unittest discover?

   A -s is silent mode and -t is timing B -s is where to start looking for test files; -t is the top-level directory placed on sys.path C they are aliases D -t selects a single test
   pch.quizShowAnswer

   B — -s is where to start looking for test files; -t is the top-level directory placed on sys.path — Running discover -s tests alone makes tests/ the top level, so importing a module one directory up fails. The working form measured here was -s tests -t .

2. Discovery matches no files and the suite prints Ran 0 tests. What is the exit status?

   A non-zero, because nothing ran B zero — success, indistinguishable from all tests passing C it raises a collection error D it depends on the -v flag
   pch.quizShowAnswer

   B — zero — success, indistinguishable from all tests passing — A green CI run can mean every test passed or that discovery matched nothing. Assert the count if the distinction matters.

3. A test method is defined but never runs. Which of these would cause that silently?

   A the method name does not start with test B the class does not subclass TestCase C the file does not match test*.py D any of the above
   pch.quizShowAnswer

   D — any of the above — All four discovery conditions fail silently. That is why a suite can grow while its effective coverage quietly shrinks.