Including doc tests into unit tests session

how to run doctests in your unit tests session

doctest could be very convenient. Mostly in cases if usage examples are the best tests for the code.

But if you add doc-tests in your project where you use unitests you’ve got a problem - how to get just one test result.

If you want one result to see and to use in CI you can include doc-tests into unit-tests session.

import doctest
from os.path import dirname, basename, isfile
from glob import glob
from importlib import import_module

import mypackage
PACKAGES = [mypackage]  # list of packages where to find doc-tests

PY_EXT = '.py'  # in what files we will look for doc-tests


def load_tests(loader, tests, ignore):
    for package in PACKAGES:
        for module_file in glob(dirname(package.__file__) + f'/*{PY_EXT}'):
            if isfile(module_file) and not module_file.endswith('__init__.py'):
                tests.addTest(doctest.DocTestSuite(
                    import_module(f'{package.__name__}.{basename(module_file)[:-len(PY_EXT)]}')
                ))
    return tests

I use load_tests protocol to create unit tests wrappers for doc tests and add them to the unit test session.

As a result we will have just one exit code, for unit tests and for doc tests.

Another bonus - more clear test report.