Repolode
Submit
jpmorganchase

jpmorganchase/nbcelltests

A JupyterLab extension and Python package for writing unit tests against individual cells of linearly executed notebooks, such as report notebooks.

View on GitHub
Stars
97
Forks
26
Open issues
42
Last commit
6 days ago

What is it?

nbcelltests lets you write tests for production Jupyter notebooks, mainly those that run top to bottom to generate reports. For each cell you can add mocks and assertions, and the tool generates a unittest class with one method per cell that includes the cumulative tests of all earlier cells, mirroring the notebook's linear execution.

Tests are stored in cell metadata, and can be run offline from an .ipynb file with the nbcelltests CLI, or executed from the JupyterLab browser interface with pytest-html results. The project also includes lint-style checks such as maximum lines per cell, cells per notebook, function and class counts, and the percentage of cells covered by tests.

The tool is aimed at catching breakage when package versions change or when exploratory, non-linear edits leave a notebook unable to generate its report. It builds on nbval, which handles regression-style output comparison.

Key features

  • 01Writes per-cell unittest methods with cumulative tests for earlier cells
  • 02Stores test definitions in cell metadata inside the notebook
  • 03Runs tests from the command line on .ipynb files
  • 04Runs and displays results in JupyterLab via pytest-html
  • 05Checks notebook structure limits such as lines per cell and cells per notebook

Use cases

  • Unit testing report notebooks that run top to bottom with Papermill or similar tools
  • Detecting breakage after package upgrades in a notebook-based reporting pipeline
  • Enforcing simple code-size limits on notebooks in a software lifecycle process

Quick start

  1. 1

    Install the Python package from PyPI

    pip install nbcelltests
  2. 2

    Generate and run the tests for an example notebook

    nbcelltests test examples/Example.ipynb

Things to know

  • JupyterLab integration requires Node.js and a JupyterLab rebuild after installing.
  • In JupyterLab, lint checks run with the Python version that runs Jupyter, so Python 2 notebooks may show false syntax errors.

In collections

Testing frameworks & test automation tools

Topics

#jupyter#testing#unit-testing#jupyterlab#notebooks#pytest#jpmorganchase#jupyter-notebook#jupyter-notebooks#jupyterlab-extension

FAQ

What is nbcelltests?
A JupyterLab extension and Python package for writing unit tests against individual cells of linearly executed notebooks, such as report notebooks. nbcelltests lets you write tests for production Jupyter notebooks, mainly those that run top to bottom to generate reports. For each cell you can add mocks and assertions, and the tool generates a unittest class with one method per cell that includes the cumulative tests of all earlier cells, mirroring the notebook's linear execution.
Is nbcelltests free to use? What license does it have?
nbcelltests is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is nbcelltests still maintained?
Actively maintained. The last commit to nbcelltests was on Nov 1, 2026.
What can I use nbcelltests for?
Unit testing report notebooks that run top to bottom with Papermill or similar tools Detecting breakage after package upgrades in a notebook-based reporting pipeline Enforcing simple code-size limits on notebooks in a software lifecycle process
How do I install nbcelltests?
Install the Python package from PyPI: pip install nbcelltests Generate and run the tests for an example notebook: nbcelltests test examples/Example.ipynb
Where can I get nbcelltests?
The source code and installation instructions are on GitHub: https://github.com/jpmorganchase/nbcelltests

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects