JupyterLab中生产型Jupyter笔记本的单元格测试

概述

nbcelltests旨在为线性执行的笔记本编写测试。其主要用途是进行单元测试报告。

安装

Python包安装：pip install nbcelltests

要在 JupyterLab 中使用，您还需要实验室和服务器扩展。通常，这些扩展与 nbcelltests 一起自动安装，所以您不需要做任何特殊操作。实验室扩展需要重新构建 JupyterLab，您在安装 celltests 后第一次启动 JupyterLab 时会被提示进行此操作（或者您可以使用 jupyter lab build 手动进行）。请注意，您必须已安装 node.js（如任何实验室扩展所需）。

要查看您拥有的扩展，请检查 jupyter labextension list 的输出（查找 nbcelltests），以及 jupyter serverextension list 的输出（查找 nbcelltests）。如果出于某种原因您需要手动安装扩展，您可以按照以下步骤操作

jupyter labextension install nbcelltests
jupyter serverextension enable --py nbcelltests

（注意：如果在环境中使用，您可能希望将 --sys-prefix 添加到 serverextension 命令。）

“线性执行笔记本？”

当将笔记本转换为 html/pdf/电子邮件报告时，它们将自上而下执行一次，并期望包含尽可能少的代码，主要关注绘图和 markdown 部分。此类库包括 Papermill、JupyterLab Emails 等。

这不是已经存在了吗？

Nbval 是一款出色的产品（我们在本项目中利用了它），我建议您用于笔记本回归测试。但它仅允许测试意外的失败或简单的输出相等性测试。

那我为什么还要这样做呢？

如果数据源崩溃，这可能不会帮助您，但您很可能还是会注意到这一点。这很有用的情况是

• 当系统（例如包版本）的环境发生变化时
• 当您在笔记本中玩耍（例如非线性执行）但不确定报告是否还会生成时
• 当您的软件生命周期系统难以处理笔记本（无法像代码一样对其进行 lint/audit，除非集成 nbdime/nbconvert 到脚本中，难以测试，难以确保今天工作的是什么明天仍然工作）

那么这能做什么呢？

给定一个笔记本，您可以为单个单元格编写模拟和断言。然后，您可以为此笔记本生成测试脚本，让您将其集成到测试系统中，从而提供报告的单元测试。

编写测试

当您为单元格编写测试时，我们会在 unittest 类上创建一个新方法，对应于您的单元格索引，并包括之前所有单元格的累积测试（以模拟笔记本线性执行中已经发生的事情）。您可以编写您喜欢的任何模拟和断言，并且可以调用 %cell 来将单元格内容注入到测试中。 测试本身存储在单元格元数据中，类似于 celltags、幻灯片信息等。

运行测试

您可以从 .ipynb 文件离线运行测试，或者从浏览器执行它们并查看 pytest-html 的 html 插件的输出。

额外测试

• 每个单元格的最大行数
• 每个笔记本的最大单元格数
• 每个笔记本的最大函数定义数
• 每个笔记本的最大类定义数
• 测试单元格的百分比

示例

在提交的 examples/Example.ipynb 笔记本中，但进行了修改，使得单元格 0 的导入语句复制了 10 次（以触发测试和 lint 失败）

测试

以下输出是通过运行 nbcelltests test examples/Example.ipynb 生成的

examples/_Example_test.py::TestNotebook::test_cell_coverage PASSED                                                                               [ 20%]
examples/_Example_test.py::TestNotebook::test_code_cell_1 PASSED                                                                                 [ 40%]
examples/_Example_test.py::TestNotebook::test_code_cell_2 PASSED                                                                                 [ 60%]
examples/_Example_test.py::TestNotebook::test_code_cell_3 PASSED                                                                                 [ 80%]
examples/_Example_test.py::TestNotebook::test_code_cell_4 PASSED                                                                                 [100%]

代码检查

以下输出是通过运行 nbcelltests lint examples/Example.ipynb 生成的

PASSED: Checking lines in cell (max=10; actual=2) (Cell 1)
PASSED: Checking lines in cell (max=10; actual=1) (Cell 2)
PASSED: Checking lines in cell (max=10; actual=1) (Cell 3)
PASSED: Checking lines in cell (max=10; actual=1) (Cell 4)
PASSED: Checking cells per notebook (max=10; actual=4)
PASSED: Checking functions per notebook (max=10; actual=0)
PASSED: Checking classes per notebook (max=10; actual=0)
FAILED: Checking lint:
	examples/Example.ipynb (in /var/folders/s3/1mjw0y192zg3450tkkn1yfnm0000gn/T/tmpp91li59p.py):32:1: F821 undefined name 'test3'
	examples/Example.ipynb (in /var/folders/s3/1mjw0y192zg3450tkkn1yfnm0000gn/T/tmpp91li59p.py):32:6: W291 trailing whitespace

注意：在jupyterlab中，笔记本将使用运行jupyter lab本身的Python版本进行过程中的代码风格检查。因此，打算与Python 2内核一起运行的笔记本在代码风格检查过程中可能会产生语法错误。

开发

有关指南，请参阅CONTRIBUTING.md。

许可证

本软件遵循Apache 2.0许可证。有关详细信息，请参阅LICENSE和AUTHORS文件。