nbapproval 0.4.0

Notebook-friendly approval testing for Python and Jupyter

nbapproval

Notebook-friendly approval testing for Python and Jupyter.

nbapproval lets you compare actual notebook outputs to approved values, store approvals in a separate approvals notebook, and fail CI runs when approvals are missing or mismatched.

Install

pip install nbapproval

Quick Start

from nbapproval import approval_test

approval_test(
    "Simple approval check",
    {"value": 42},
)

approval_test.assert_all_approved()

API (Terse-First)

Primary call supports concise notebook usage:

approval_test(description, actual, sort_by=None)

Also supported:

• id alias for test_id
• desc alias for description
• keyword form: actual=...
• automatic test_id derivation from description when omitted
• pandas DataFrame values as actual (auto-converted to stable records)

Examples:

# Explicit id + keyword style
approval_test(
    id="known_holiday_checkpoints_match_expected_names_for_specific_dates",
    desc="Known holiday checkpoints match expected names for specific dates.",
    actual=approval_test.to_iso_records(actual_df),
    sort_by=["Date", "Expected"],
)

# Terse positional style (id auto-derived from description)
approval_test(
    "Known holiday checkpoints match expected names for specific dates.",
    actual_df,
    sort_by=["Date", "Expected"],
)

approval_test.from_dataframe(...) remains available, but is optional now because the main call handles DataFrames directly.

Runtime Status

You can inspect the current approval run state directly:

approval_test.status_report()
approval_test.approvals_notebook_path

• status_report() returns totals and per-test statuses for the current session.
• approvals_notebook_path returns the resolved approvals notebook path.

approval_test.assert_all_approved() prints a summary and approvals notebook path, then raises if any test is not Approved.

Notebook Magics

The package registers two IPython magics for concise notebook tests:

• %approve for line-style checks
• %%approve for cell-style checks

Examples:

# line magic with expression only
%approve bool(df["Date"].is_monotonic_increasing)

# line magic with options + expression (use :: separator)
%approve --id dates_are_sorted --desc "Dates are sorted" :: bool(df["Date"].is_monotonic_increasing)

# cell magic with a code block; last expression becomes approved value
%%approve --desc "Federal holidays for 2026" --sort-by "['Date', 'Holiday']"
df.loc[df["Year"] == 2026, ["Date", "Holiday"]]

Notes:

• In %approve, when options are present, put :: before the expression.
• In %%approve, full code blocks are supported; setup statements are allowed, and the last expression is used as actual.

Testing

Run tests with:

pip install -e .[dev]
pytest -q

Notes

• Stable and unique test_id values are required.
• For deterministic CI runs, configure an explicit approvals notebook path.
• Works well with Papermill-driven notebook execution.

License

Apache License 2.0. See LICENSE.