Skip to content
Easy to use test framework for Jupyter Notebooks
Branch: master
Clone or download
Latest commit 81e1048 Apr 4, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
images Images for readme Apr 4, 2019
treon messaging update Apr 3, 2019
LICENSE Added MIT License Mar 30, 2019
MANIFEST.in Initial scaffolding Mar 30, 2019
README.md Update README.md Apr 4, 2019
setup.py update setup.py to enforce python version Apr 4, 2019
treon-runner.py Initial scaffolding Mar 30, 2019

README.md

PyPI version

treon

Easy to use test framework for Jupyter Notebooks.

  • Runs notebook top to bottom and flags execution errors if any
  • Runs unittest present in your notebook code cells
  • Runs doctest present in your notebook code cells

Why should you use it?

  • Start testing notebooks without writing a single line of code
  • Multithreaded execution for quickly testing a set of notebooks
  • Executes every Notebook in a fresh kernel to avoid kernel state interference
  • Primarily a command line tool that can be used easily in any Continuous Integration (CI) system
  • Soon to be part of ReviewNB's CI system that automatically runs treon everytime you push notebook changes to GitHub

Installation

pip install treon

Usage

$ treon
Executing treon version 0.1.0
Recursively scanning /workspace/treon/tmp/docs/site/ru/guide for Notebooks...

-----------------------------------------------------------------------
Collected following Notebooks for testing
-----------------------------------------------------------------------
/workspace/treon/tmp/docs/site/ru/guide/keras.ipynb
/workspace/treon/tmp/docs/site/ru/guide/eager.ipynb
-----------------------------------------------------------------------

Triggered test for /workspace/treon/tmp/docs/site/ru/guide/keras.ipynb
Triggered test for /workspace/treon/tmp/docs/site/ru/guide/eager.ipynb

test_sum (__main__.TestNotebook) ... 
ok
test_sum (__main__.TestNotebook2) ... 
ok
test_sum (__main__.TestNotebook3) ... 
ok

----------------------------------------------------------------------
Ran 3 tests in 0.004s

OK

-----------------------------------------------------------------------
TEST RESULT
-----------------------------------------------------------------------
/workspace/treon/tmp/docs/site/ru/guide/keras.ipynb       -- PASSED 
/workspace/treon/tmp/docs/site/ru/guide/eager.ipynb       -- PASSED 
-----------------------------------------------------------------------
2 succeeded, 0 failed, out of 2 notebooks tested.
-----------------------------------------------------------------------

Command line arguments

Usage:
  treon
  treon [PATH] [--threads=<number>]

Arguments:
  PATH                File or directory path to find notebooks to test. Searches recursively for directory paths. [default: current working directory]

Options:
  --threads=<number>  Number of parallel threads. Each thread processes one notebook file at a time. [default: 10]
  -h --help           Show this screen.
  --version           Show version.

unitttest example

You just need to add tests as shown below & treon would execute them and report the result on the console. See this for more details on how to write unittest.

doctest example

You just need to add tests as shown below & treon would execute them and report the result on the console. See this for more details on how to write doctest.

Note about dependencies

  • You need to run treon from environment (virtualenv/pipenv etc.) that has all the dependcies required for Notebooks under test
  • treon only works with python3+ environments and uses python3 kernel for executing notebooks

Motivation

Our aim at ReviewNB is to make notebooks a first class entity in the production workflow. We've built a code review system for Notebooks. The next step is to build a CI pipeline & treon is the core tool in that effort. It is licensed librerally (MIT) & I foresee it being used as an independent tool as well. You can use it locally and/or integrate with CI system of your choice.

For motivation, checkout Netflix's blog to see how notebooks are graduating from scratchpad to a part of production workflow.

Contribute

If you see any problem, open an issue or send a pull request. You can write to team@reviewnb.com for any questions.

You can’t perform that action at this time.