pytest_notebook.nb_regression module#

Jupyter Notebook Regression Test Class.

exception pytest_notebook.nb_regression.NBRegressionError[source]#

Bases: Exception

Exception to signal a regression test fail.

class pytest_notebook.nb_regression.NBRegressionFixture(exec_notebook: bool = True, exec_cwd: str | None = None, exec_allow_errors: bool = False, exec_timeout: int = 120, coverage: bool = False, cov_config: str | None = None, cov_source: str | Tuple[str] | None = None, cov_merge: Coverage | None = None, post_processors: tuple = ('coalesce_streams',), process_resources: dict = _Nothing.NOTHING, diff_replace: tuple = (), diff_ignore: tuple = ('/cells/*/outputs/*/traceback',), diff_use_color: bool = True, diff_color_words: bool = False, force_regen: bool = False)[source]#

Bases: object

Class to perform Jupyter Notebook Regression tests.

Parameters:

  • exec_notebook (bool) – Create a new notebook, by executing all cells in the original notebook This value is accessible, after initialization, via the exec_notebook attribute. Default: True

  • exec_cwd (Optional[str]) – Path to the directory which the notebook will run in (defaults to directory of notebook). This value is accessible, after initialization, via the exec_cwd attribute. Default: None

  • exec_allow_errors (bool) – Do not stop execution after the first unexpected exception (where cell is not tagged raises-exception). This value is accessible, after initialization, via the exec_allow_errors attribute. Default: False

  • exec_timeout (int) – The maximum time to wait (in seconds) for execution of each cell. This value is accessible, after initialization, via the exec_timeout attribute. Default: 120

  • coverage (bool) – Record coverage data, with coverage.py. This value is accessible, after initialization, via the coverage attribute. Default: False

  • cov_config (Optional[str]) – Determines what coverage configuration file to read. This value is accessible, after initialization, via the cov_config attribute. Default: None

  • cov_source (str, Tuple[str]) – A list of file paths or package names to measure coverage for. This value is accessible, after initialization, via the cov_source attribute. Default: None

  • cov_merge (Optional[coverage.control.Coverage]) – A coverage.Coverage instance, to merge coverage results with. This value is accessible, after initialization, via the cov_merge attribute. Default: None

  • post_processors (tuple) – post-processors to apply to the new workbook, relating to entry points in the ‘nbreg.post_proc’ group This value is accessible, after initialization, via the post_processors attribute. Default: (‘coalesce_streams’,)

  • process_resources (dict) – Resources to parse to processor functions. This value is accessible, after initialization, via the process_resources attribute. Default: Factory(factory=<class ‘dict’>, takes_self=False)

  • diff_replace (tuple) – A list of regex replacements to apply before diffing, e.g. [('/cells/*/outputs', '\d{2,4}-\d{1,2}-\d{1,2}', 'DATE-STAMP')]. This value is accessible, after initialization, via the diff_replace attribute. Default: ()

  • diff_ignore (tuple) – List of diff paths to ignore, e.g. ‘/cells/1/outputs’ or ‘/cells/*/metadata’. This value is accessible, after initialization, via the diff_ignore attribute. Default: (‘/cells//outputs//traceback’,)

  • diff_use_color (bool) – Use ANSI color code escapes for text output. This value is accessible, after initialization, via the diff_use_color attribute. Default: True

  • diff_color_words (bool) – Highlight changed words using only colors. This value is accessible, after initialization, via the diff_color_words attribute. Default: False

  • force_regen (bool) – Re-generate notebook files, if no unexpected execution errors, and an output path has been supplied. This value is accessible, after initialization, via the force_regen attribute. Default: False

_validate_cov_merge(attribute, value)[source]#
_validate_coverage(attribute, value)[source]#
_validate_diff_ignore(attribute, values)[source]#
_validate_diff_replace(attribute, values)[source]#
_validate_exec_cwd(attribute, value)[source]#
_validate_exec_timeout(attribute, value)[source]#
_validate_post_processors(attribute, values)[source]#
check(path: TextIO | str, raise_errors: bool = True) → NBRegressionResult[source]#

Execute the Notebook and compare its initial vs. final contents.

if force_regen is True, the new notebook will be written to path

if raise_errors is True:

Raises:
Return type:

NBRegressionResult

cov_config: str | None#
cov_merge: Coverage | None#
cov_source: str | Tuple[str]#
coverage: bool#
diff_color_words: bool#
diff_ignore: tuple#
diff_replace: tuple#
diff_use_color: bool#
exec_allow_errors: bool#
exec_cwd: str | None#
exec_notebook: bool#
exec_timeout: int#
force_regen: bool#
post_processors: tuple#
process_resources: dict#
class pytest_notebook.nb_regression.NBRegressionResult(nb_initial: NotebookNode, nb_final: NotebookNode, diff_full: List[DiffEntry], diff_filtered: List[DiffEntry], diff_string: str, process_resources: dict = _Nothing.NOTHING)[source]#

Bases: object

A class to store the result of NBRegressionFixture.check.

Parameters:

  • nb_initial (nbformat.notebooknode.NotebookNode) – Initial notebook. This value is accessible, after initialization, via the nb_initial attribute.

  • nb_final (nbformat.notebooknode.NotebookNode) – Notebook after execution and post-processing. This value is accessible, after initialization, via the nb_final attribute.

  • diff_full (List[nbdime.diff_format.DiffEntry]) – Full diff of initial/final notebooks. This value is accessible, after initialization, via the diff_full attribute.

  • diff_filtered (List[nbdime.diff_format.DiffEntry]) – Diff of initial/final notebooks, filtered according to the parsed configuration. This value is accessible, after initialization, via the diff_filtered attribute.

  • diff_string (str) – The formatte string of diff_filtered. This value is accessible, after initialization, via the diff_string attribute.

  • process_resources (dict) – Resources returned from notebook processors. This value is accessible, after initialization, via the process_resources attribute. Default: Factory(factory=<class ‘dict’>, takes_self=False)

diff_filtered: List[DiffEntry]#
diff_full: List[DiffEntry]#
diff_string: str#
nb_final: NotebookNode#
nb_initial: NotebookNode#
process_resources: dict#
pytest_notebook.nb_regression._get_coverage_aliases(cov)[source]#

Retrieve path aliases from coverage.Coverage object.