nbval is a pytest plugin designed to validate Jupyter notebooks. It allows users to execute notebooks as part of their test suite and compare cell outputs against previously saved outputs, ensuring reproducibility and correctness. The current version is 0.11.0, and it has a sporadic but active release cadence, typically with minor releases every 6-12 months.
pip install nbval pytestVerified import paths — ran on the pinned version, not inferred.
This quickstart script demonstrates how to programmatically create a simple Jupyter notebook and then run `pytest` with the `nbval` plugin to validate its output. It shows the minimal setup required to get started with notebook testing using `nbval`.
Remove `--nbval-sanitize` from your pytest command-line arguments or `pytest.ini` configuration. If sanitation is still required, consider pre-processing notebooks or using `nbval`'s cell metadata options for more granular control over output comparison (e.g., `nbval-ignore_data_priority`).
Upgrade your Python environment to Python 3.7 or newer. The current minimum requirement is Python 3.7.
To get a simpler pass/fail indication without detailed diffs, you can set `nbval_diff=False` in your `pytest.ini` or use `--no-nbval-diff` on the command line. For more controlled output validation, explore options like `--nbval-lax` or specific cell metadata for ignoring certain outputs.
Ensure you understand how `nbval` handles outputs. For cells that are expected to fail, add `"raises-exception": true` to their cell metadata. For cells with no relevant output or to skip execution, use `"skip-execution": true` or `"skip-compare": true`. Use `--nbval-lax` for more permissive output comparison, or `--nbval-errors` to fail on any executed code error regardless of output comparison.