"python -m doctest" ignores files with same names in different directories

Question

Suppose we have two files:

fail/stuff.py

"""
>>> True
False
"""

pass/stuff.py

"""
>>> True
True
"""

Then we run them both under doctest:

python -m doctest fail/stuff.py pass/stuff.py

As expected, we see an error from fail/stuff.py. But if we run them in the opposite order:

python -m doctest pass/stuff.py fail/stuff.py

Then it passes!

Is there some fundamental reason why Python's import system is unable to cope with loading tests from both files, or is doctest simply broken?

Answer 1

Is there some fundamental reason why Python's import system is unable to cope with loading tests from both files, or is doctest simply broken?

Doctests is basically just broken. There's no fundamental reason why Python import system can't handle this scenario. Ergo, there's no fundamental reason the test runner can't also handle this scenario. I doubt they gave it too much thought when writing the command-line interface, because most people wouldn't use doctest as a runner directly (rather, integrating the library code in with a more full-featured runner and using a doctest plugin would be much more usual).

You can just use a better test runner. For example, pytest (among others) won't have this problem:

$ pytest --doctest-modules --import-mode importlib
============================= test session starts =============================
platform darwin -- Python 3.13.1, pytest-8.3.4, pluggy-1.5.0
rootdir: /tmp
collected 2 items                                                             

fail/stuff.py F                                                         [ 50%]
pass/stuff.py .                                                         [100%]

================================== FAILURES ===================================
____________________________ [doctest] fail.stuff _____________________________
001 
002 >>> True
Expected:
    False
Got:
    True

/tmp/fail/stuff.py:2: DocTestFailure
=========================== short test summary info ===========================
FAILED fail/stuff.py::fail.stuff
========================= 1 failed, 1 passed in 0.01s =========================