跳转到主要内容

一个用于验证Jupyter笔记本的py.test插件

项目描述

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

Tests PyPI Version Documentation Status

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

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

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

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

安装

可在PyPi上找到

pip install nbval

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

pip install .

从主目录。要卸载

pip uninstall nbval

工作原理

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

关于执行,大致来说,脚本初始化一个带有shelliopub套接字的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

由以下支持

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页面