ipytest - a IPython test runner

From time to time, I find myself wanting to run unit-tests in IPython notebooks. After writing the same code over and over again, I decided to publish it as a pip-installable package. This post aims to be a quick introduction how I came to create this package and how it can be used.

Nowadays, the first thing I do when starting a new project is firing up an IPython notebook to prototype an initial implementation. Since the notebook interface offers instant feedback, it allows for rapid experimentation. When dealing with large-ish datasets this feature becomes even more powerful. Parsing and transforming data in python can take some time. Using the notebook interface, one can perform this initial work once and then rapidly experiment with code using this data.

However, for all the advantages of IPython, testing code placed in notebooks can be hard. For this reason, I try move code into external python modules as soon as possible to make it easy to import and test. Having said this, sometimes, there is this twilight zone, where code it not yet quite stable, but still complex enough to warrant tests. In particular with pure algorithms test-driven development can save a lot of time in the long run.

For this reason, I wrote the ipytest, which allows to run tests in IPython notebooks. As a silly example, consider the Fibonacci sequence. With ipytest, one could have written the implementation and its tests as

# In[1]:
def fibonacci(i):
    """Compute the fibonacci sequence.

    >>> [fibonacci(n) for n in range(7)]
    [1, 1, 2, 3, 5, 8, 13]

    """
    if i == 0 or i == 1:
        return 1
    return fibonacci(i - 1) + fibonacci(i - 2)

# In[2]:
import ipytest
ipytest.clean_tests("test_fibonacci*")

class test_fibonacci_example(unittest.TestCase):
    def test_example():
        self.assertEqual(fibonacci(6), 13)

def test_fibonacci_0():
    assert fibonacci(0) == 1

def test_fibonacci_1():
    assert fibonacci(1) == 1

def test_fibonacci_2():
    assert fibonacci(2) == 2

def test_fibonacci_3():
    assert fibonacci(3) == 3

def test_fibonacci_4():
    assert fibonacci(4) == 5

def test_fibonacci_5():
    assert fibonacci(5) == 8

ipytest.run_tests(doctest=True)

Here, both the function computing the Fibonacci sequence and the tests are written in the same notebook. After executing it, the notebook looks like this. If you want to give it a try, just install it with pip install ipytest. A detailed reference is can be found on the project's github page.