Py.test插件，用于验证Jupyter笔记本

此插件为py.test添加了识别和收集Jupyter笔记本的功能。测试的目的在于确定存储的输入执行是否与.ipynb文件中存储的输出匹配。同时确保笔记本运行无错误。

测试被设计来确保Jupyter笔记本（特别是那些用于参考和文档的笔记本）能够一致执行。

每个单元格被视为一个测试，如果一个单元格没有产生预期的输出，则会失败。

完整文档请参见docs/source/index.ipynb。

安装

可在PyPi上找到

pip install nbval

或从克隆仓库并运行最新版本

pip install .

从主目录。要卸载

pip uninstall nbval

工作原理

该扩展会检查IPython笔记本中每个包含代码的单元格，然后py.test系统会将笔记本中存储的输出与执行单元格时的输出进行比较。因此，笔记本本身被用作测试函数。执行笔记本时，可以通过传递额外的选项和文件来对输出行进行清理，当调用py.test命令时。这是一个ConfigParser库的常规配置文件。

关于执行，大致来说，脚本初始化一个带有shell和iopub套接字的IPython内核。需要shell来执行笔记本中的单元格（它向内核发送请求）和iopub提供从输出中获取消息的接口。从内核获得的消息内容被组织在不同的字典中，包含不同的信息，例如执行的时间戳、单元格数据类型、单元格类型、内核状态、用户名等。

一般来说，IPython笔记本系统的功能相当复杂，但关于消息的详细解释以及系统的工作原理，可以在此处找到

https://jupyter-client.readthedocs.io/en/latest/messaging.html#messaging

执行

要执行此插件，您需要使用nbval标志执行py.test以区分测试与常规python文件

py.test --nbval

您还可以指定--nbval-lax，它将运行笔记本并检查错误，但仅比较带有#NBVAL_CHECK_OUTPUT标记注释的单元格的输出。

py.test --nbval-lax

上述命令将执行当前文件夹中的所有.ipynb文件和'pytest'测试。如果只想执行笔记本，请指定-p no:python。或者，您也可以执行特定的笔记本

py.test --nbval my_notebook.ipynb

默认情况下，每个.ipynb文件将使用其元数据中指定的内核执行。您可以通过传递--nbval-kernel-name mykernel来覆盖此行为，以使用mykernel运行所有笔记本，或者使用--current-env来使用pytest自身启动的相同环境中的内核。

如果要对输出行进行清理，必须传递额外的标志--nbval-sanitize-with以及包含正则表达式配置文件的路径，例如

py.test --nbval my_notebook.ipynb --nbval-sanitize-with path/to/my_sanitize_file

其中my_sanitize_file具有以下结构。

[Section1]
regex: [a-z]*
replace: abcd

regex: [1-9]*
replace: 0000

[Section2]
regex: foo
replace: bar

regex选项包含将要匹配输出的表达式，而replace是替换regex匹配的字符串。目前，部分名称在测试系统中没有任何意义或影响，它将获取所有部分并替换相应的选项。

覆盖率

要使用笔记本为导入的代码生成覆盖率，请使用pytest-cov插件。nbval应自动检测相关选项并自行配置。

并行执行

nbval与pytest-xdist插件兼容，用于并行运行测试。但它确实需要使用--dist loadscope标志，以确保同一笔记本的所有单元格都在同一内核上运行。

文档

nbval的叙述性文档可在https://nbval.readthedocs.io找到。

帮助

使用 py.test -h 可以获取 py.test 系统的帮助信息，它将显示可以传递给命令的所有标志，例如详细的 -v 选项。Nbval 的选项可以在 Jupyter Notebook 验证 部分找到。

致谢

此插件灵感来源于 Andrea Zonca 的 py.test 插件，用于收集 IPython 笔记本中的单元测试（https://github.com/zonca/pytest-ipynb）。

原始原型基于 https://gist.github.com/timo/2621679 中的模板和笔记本测试系统的代码 https://gist.github.com/minrk/2620735，我们将它们整合并混合到 py.test 系统中。

感谢以下机构的财务支持：

• OpenDreamKit Horizon 2020 欧洲研究基础设施项目 (#676541)，http://opendreamkit.org

• EPSRC 的下一代计算建模博士培训中心，http://ngcm.soton.ac.uk (#EP/L015382/1) 和 EPSRC 的复杂系统模拟博士培训中心 ((EP/G03690X/1)，

• 通过 GBMF #4856 号资助由 Gordon 和 Betty Moore 基金会，Alfred P. Sloan 基金会以及 Helmsley 信托。

作者

2014 - 2017 David Cortes-Ortuno，Oliver Laslett，T. Kluyver，Vidar Fauske，Maximilian Albert，MinRK，Ondrej Hovorka，Hans Fangohr