testbook

What it is and what it does

testbook is a unit testing framework that lets you write conventional Python unit tests for Jupyter Notebooks without embedding tests inside the notebooks themselves. Instead of mixing test code with notebook cells, you write separate test files that load and execute a notebook, then extract and assert on its outputs and variables. It depends on nbformat to parse notebooks and nbclient to execute them, bridging the gap between notebook-based development and traditional test-driven development practices.

The package treats .ipynb files as importable modules within your test suite. You decorate a test function with @testbook, pointing it to a notebook path, and the decorator handles notebook execution and provides a testbook object (tb) that lets you retrieve variables and functions defined in the notebook. This approach is useful for data science and analytics workflows where notebooks are primary development artifacts but you still want automated test coverage.

Use it for:

• Test data processing pipelines defined in Jupyter notebooks without rewriting them as Python modules
• Validate notebook outputs and intermediate variables in a CI/CD pipeline
• Ensure notebook functions produce expected results when dependencies or data change
• Build regression tests for analytical or scientific notebooks shared across a team
• Verify notebook cells execute without errors before publishing or sharing them

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

testbook lets you write unit tests for Jupyter Notebooks in separate Python test files, treating .ipynb files like .py modules and executing notebook code within test functions.

Yes, with caution. testbook fills a real gap for testing notebook-based code, and the low install friction and permissive license make it accessible. However, the package is dormant—no releases since 2021-06-02—which raises questions about compatibility with modern Python and Jupyter versions. If your notebooks target Python 3.6–3.8 and stable Jupyter dependencies, it should work; for newer environments, verify compatibility before committing to production use.

Install

testbook on PyPI

pip install testbook

uv add testbook

poetry add testbook

Installing testbook

Before you install

Low friction install with just two runtime dependencies (nbformat, nbclient). However, the package is dormant—last release was 2021-06-02, though the repository remains active with a recent commit on 2024-08-25. No active maintenance signal.

License in practice

BSD license is permissive, allowing commercial and private use with minimal restrictions. No licensing friction for most use cases.

Quickstart

pip install testbook

from testbook import testbook

@testbook('/path/to/notebook.ipynb', execute=True)
def test_func(tb):
    func = tb.get("func")
    assert func(1, 2) == 3

Requires a Jupyter kernel installed separately (e.g., ipykernel via pip install ipykernel) to execute notebooks during tests.

Verify before relying

• Whether testbook works with modern Python versions beyond 3.8, given classifiers list only through 3.8
• Current compatibility with recent nbformat and nbclient versions, given no releases since 2021-06-02
• Whether dormant status affects bug fixes or compatibility with newer Jupyter ecosystem changes

Package facts

Evidence: testbook-0.4.2-py3-none-any.whl

Keywords: jupyter, mapreduce, nteract, pipeline, notebook

Tags

More Testing packages