# treon
[](https://badge.fury.io/py/treon)
[](https://travis-ci.org/ReviewNB/treon)
Easy to use test framework for Jupyter Notebooks.
* Runs notebook top to bottom and flags execution errors if any
* Runs [unittest](https://docs.python.org/2/library/unittest.html) present in your notebook code cells
* Runs [doctest](https://docs.python.org/2/library/doctest.html) present in your notebook code cells
### Why should you use it?
* Start testing notebooks without writing a single line of test code
* Multithreaded execution for quickly testing a set of notebooks
* Executes every Notebook in a fresh kernel to avoid hidden state problems
* Primarily a command line tool that can be used easily in any Continuous Integration (CI) system
## Installation
```
pip install treon
```
## Usage
Treon will execute notebook from top to bottom and the test fails if any code cell returns an error. Additionally, one can write unittest & doctest to test specific behaviour (examples shown below).
```
$ treon
Executing treon version 0.1.4
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>] [-v] [--exclude=<string>]...
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]
-e=<string> --exclude=<string> Option for excluding files or entire directories from testing. All files whose
absolute path starts with the specified string are excluded from testing. This option can be
specified more than once to exclude multiple files or directories. If the exclude path is
a valid directory name, only this directory is excluded.
-v --verbose Print detailed output for debugging.
-h --help Show this screen.
--version Show version.
```
## unittest example
You just need to add tests as shown below & treon would execute them and report the result on the console. See [this](https://docs.python.org/2/library/unittest.html) 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](https://docs.python.org/2/library/doctest.html) 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 dependencies required for Notebooks under test
* treon only works with python3+ environments and uses python3 kernel for executing notebooks
## Development
For development, you may use below to create a Python interpreter that resides in `venv` in the current working directory, and to install all of treon's dependencies:
```
$ virtualenv venv
$ source venv/bin/activate
$ pip install -e .
$ pip install -r requirements-dev.txt
$ treon --help # should work
```
Because the script installs the package as editable, you can make changes in the source tree and use the `treon` command to immediately validate them. If this does not appear to work, check that you are using a the proper virtual environment, and that the package is indeed installed in editable mode:
```
$ which treon # should point into your virtualenv
/path/to/my/venv/bin/treon
$ pip list --local | grep treon # should point to the source tree
treon 0.1.4 /workspace/treon
```
Please refer to the `Makefile` for supplementary development tasks.
In particular, the following targets may be relevant when validating changes before committing:
```
$ make lint # check treon's source for code style errors
$ make test # run all tests
```
## Motivation
Our aim at [ReviewNB](https://www.reviewnb.com/) 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](https://github.com/ReviewNB/support/issues/19) & treon is the core tool in that effort. It is licensed liberally (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](https://medium.com/netflix-techblog/scheduling-notebooks-348e6c14cfd6) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/reviewNB/treon",
"name": "treon",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "test,jupyter,notebook,jupyter test,notebook test,unittest,doctest",
"author": "Amit Rathi",
"author_email": "amit@reviewnb.com",
"download_url": "https://files.pythonhosted.org/packages/14/ed/c9f9fa94fae6b232888d3afbb1bd45da0f5b169978e17746f3437a28a761/treon-0.1.4.tar.gz",
"platform": null,
"description": "# treon\n\n[](https://badge.fury.io/py/treon)\n[](https://travis-ci.org/ReviewNB/treon)\n\nEasy to use test framework for Jupyter Notebooks.\n* Runs notebook top to bottom and flags execution errors if any\n* Runs [unittest](https://docs.python.org/2/library/unittest.html) present in your notebook code cells\n* Runs [doctest](https://docs.python.org/2/library/doctest.html) present in your notebook code cells\n\n### Why should you use it?\n* Start testing notebooks without writing a single line of test code\n* Multithreaded execution for quickly testing a set of notebooks\n* Executes every Notebook in a fresh kernel to avoid hidden state problems\n* Primarily a command line tool that can be used easily in any Continuous Integration (CI) system\n\n\n## Installation\n```\npip install treon\n```\n\n## Usage\nTreon will execute notebook from top to bottom and the test fails if any code cell returns an error. Additionally, one can write unittest & doctest to test specific behaviour (examples shown below).\n\n```\n$ treon\nExecuting treon version 0.1.4\nRecursively scanning /workspace/treon/tmp/docs/site/ru/guide for Notebooks...\n\n-----------------------------------------------------------------------\nCollected following Notebooks for testing\n-----------------------------------------------------------------------\n/workspace/treon/tmp/docs/site/ru/guide/keras.ipynb\n/workspace/treon/tmp/docs/site/ru/guide/eager.ipynb\n-----------------------------------------------------------------------\n\nTriggered test for /workspace/treon/tmp/docs/site/ru/guide/keras.ipynb\nTriggered test for /workspace/treon/tmp/docs/site/ru/guide/eager.ipynb\n\ntest_sum (__main__.TestNotebook) ...\nok\ntest_sum (__main__.TestNotebook2) ...\nok\ntest_sum (__main__.TestNotebook3) ...\nok\n\n----------------------------------------------------------------------\nRan 3 tests in 0.004s\n\nOK\n\n-----------------------------------------------------------------------\nTEST RESULT\n-----------------------------------------------------------------------\n/workspace/treon/tmp/docs/site/ru/guide/keras.ipynb -- PASSED\n/workspace/treon/tmp/docs/site/ru/guide/eager.ipynb -- PASSED\n-----------------------------------------------------------------------\n2 succeeded, 0 failed, out of 2 notebooks tested.\n-----------------------------------------------------------------------\n```\n\n## Command line arguments\n```\nUsage:\n treon\n treon [PATH] [--threads=<number>] [-v] [--exclude=<string>]...\n\nArguments:\n PATH File or directory path to find notebooks to test. Searches recursively for directory paths. [default: current working directory]\n\nOptions:\n --threads=<number> Number of parallel threads. Each thread processes one notebook file at a time. [default: 10]\n -e=<string> --exclude=<string> Option for excluding files or entire directories from testing. All files whose\n absolute path starts with the specified string are excluded from testing. This option can be\n specified more than once to exclude multiple files or directories. If the exclude path is\n a valid directory name, only this directory is excluded.\n -v --verbose Print detailed output for debugging.\n -h --help Show this screen.\n --version Show version.\n```\n\n## unittest example\nYou just need to add tests as shown below & treon would execute them and report the result on the console. See [this](https://docs.python.org/2/library/unittest.html) for more details on how to write unittest.\n\n\n\n## doctest example\nYou just need to add tests as shown below & treon would execute them and report the result on the console. See [this](https://docs.python.org/2/library/doctest.html) for more details on how to write doctest.\n\n\n\n## Note about dependencies\n* You need to run treon from environment (virtualenv/pipenv etc.) that has all the dependencies required for Notebooks under test\n* treon only works with python3+ environments and uses python3 kernel for executing notebooks\n\n## Development\nFor development, you may use below to create a Python interpreter that resides in `venv` in the current working directory, and to install all of treon's dependencies:\n\n```\n$ virtualenv venv\n$ source venv/bin/activate\n$ pip install -e .\n$ pip install -r requirements-dev.txt\n$ treon --help # should work\n```\n\nBecause the script installs the package as editable, you can make changes in the source tree and use the `treon` command to immediately validate them. If this does not appear to work, check that you are using a the proper virtual environment, and that the package is indeed installed in editable mode:\n\n```\n$ which treon # should point into your virtualenv\n/path/to/my/venv/bin/treon\n$ pip list --local | grep treon # should point to the source tree\ntreon 0.1.4 /workspace/treon\n```\n\nPlease refer to the `Makefile` for supplementary development tasks.\nIn particular, the following targets may be relevant when validating changes before committing:\n\n```\n$ make lint # check treon's source for code style errors\n$ make test # run all tests\n```\n\n## Motivation\nOur aim at [ReviewNB](https://www.reviewnb.com/) 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](https://github.com/ReviewNB/support/issues/19) & treon is the core tool in that effort. It is licensed liberally (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.\n\nFor motivation, checkout [Netflix's blog](https://medium.com/netflix-techblog/scheduling-notebooks-348e6c14cfd6) to see how notebooks are graduating from scratchpad to a part of production workflow.\n\n## Contribute\nIf you see any problem, open an issue or send a pull request. You can write to team@reviewnb.com for any questions.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Testing framework for Jupyter Notebooks",
"version": "0.1.4",
"split_keywords": [
"test",
"jupyter",
"notebook",
"jupyter test",
"notebook test",
"unittest",
"doctest"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "f432fcac9e22606f732ca860a2f3d0c6",
"sha256": "ab7f54c7f45ee38ee27f9022e065a7fc261f09b36dc595f619393a0548d93a17"
},
"downloads": -1,
"filename": "treon-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f432fcac9e22606f732ca860a2f3d0c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 8141,
"upload_time": "2022-08-04T11:25:00",
"upload_time_iso_8601": "2022-08-04T11:25:00.536288Z",
"url": "https://files.pythonhosted.org/packages/e9/bd/ff217cc8e99fbfe617a5153c65dd6933182d53048f98c53a99755027b2bc/treon-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7e5184a703495f4705c9ec02853df42e",
"sha256": "6c31a1701036ee8a746adcc9ca59640269c01e887ea13ccc675680d39705d4f4"
},
"downloads": -1,
"filename": "treon-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "7e5184a703495f4705c9ec02853df42e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 7509,
"upload_time": "2022-08-04T11:25:03",
"upload_time_iso_8601": "2022-08-04T11:25:03.352885Z",
"url": "https://files.pythonhosted.org/packages/14/ed/c9f9fa94fae6b232888d3afbb1bd45da0f5b169978e17746f3437a28a761/treon-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-08-04 11:25:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "reviewNB",
"github_project": "treon",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "treon"
}
JSON
