Running Doctests in Jupyter Notebooks

You can run doctests within a Jupyter notebook in two ways:

Method 1 - Inside the notebook

Either insert this cell into your notebook:

if __name__ == '__main__':
    import xdoctest
    xdoctest.doctest_module()

This will execute any doctests for callables that are in the top-level namespace of the notebook. While you don’t have to include the if __name__ block, it is better practice because it will prevent issues if you also wish to use “Method 2”.

Method 2 - Outside the notebook

An alternative way to run would be using the xdoctest command line tool and pointing to the notebook file.

xdoctest path/to/notebook.ipynb

This will execute every cell in the notebook and then execute the doctest of any defined callable with a doctest.

Caveats

WARNING: in both of the above methods, when you execute doctests it will include any function / class that was defined in the notebook, but also any external library callable with a doctest that you import directly! Therefore it is best to (1) never use from <module> import * statements (in general using import * is bad practice) and (2) prefer using functions via their module name rather than importing directory. For example instead of from numpy import array; x = array([1]) use import numpy as np; x = np.array([1]).

Lastly, it is important to note that Jupyter notebooks are great for prototyping and exploration, but in practice storing algorithm and utilities in Jupyter notebooks is not sustainable (for some of these reasons). Reusable code should eventually be refactored into a proper pip-installable Python package where the top level directory contains a setup.py and a folder with a name corresponding to the module name and containing an __init__.py file and any other package python files. However, if you write you original Jupyter code with doctests, then when you port your code to a proper package the automated tests come with it! (And the above warning does not apply to statically parsed python packages)