[论文解读] Testing with Jupyter notebooks: NoteBook VALidation (nbval) plug-in for pytest

Hans Fangohr, Vidar Tonaas Fauske+6 more|arXiv (Cornell University)|Jan 13, 2020

Software Engineering Research参考文献 7被引用 6

一句话总结

本文介绍了 nbval，一个 pytest 插件，通过重新执行单元格并将结果与保存的输出进行比较，验证 Jupyter 笔记本的输出，从而确保可重现性和测试覆盖率。它使笔记本能够作为可执行文档、单元测试、集成测试和系统测试使用，支持输出净化、错误处理以及通过 nbdime 实现的丰富差异对比。

ABSTRACT

The Notebook validation tool nbval allows to load and execute Python code from a Jupyter notebook file. While computing outputs from the cells in the notebook, these outputs are compared with the outputs saved in the notebook file, treating each cell as a test. Deviations are reported as test failures, with various configuration options available to control the behaviour. Application use cases include the validation of notebook-based documentation, tutorials and textbooks, as well as the use of notebooks as additional unit, integration and system tests for the libraries that are used in the notebook. Nbval is implemented as a plugin for the pytest testing software.

研究动机与目标

• 为解决随着底层库的演进，笔记本可重现性随时间下降的挑战。
• 使 Jupyter 笔记本能作为代码、文档和教程的可执行测试使用。
• 通过在 CI/CD 流水线中自动化输出对比，减少手动验证的工作量。
• 通过检测意外的输出变化，支持代码的安全重构。
• 提供轻量级、基于插件的解决方案，与 pytest 集成，实现无缝的测试工作流。

提出的方法

• nbval 使用 IPython 内核加载并执行 Jupyter 笔记本中的每个单元格。
• 它将每个单元格重新计算的输出与笔记本文件中先前保存的输出进行对比。
• 该工具以严格或宽松模式运行，通过单元格元数据标签（如 nbval-check-output 和 nbval-ignore-output）进行行为配置。
• 它支持使用正则表达式进行输出净化，以忽略时间戳或内存地址等变量内容。
• 它与 nbdime 集成，可可视化丰富差异，包括图像和多媒体输出的对比。
• 它允许跳过单元格（nbval-skip）或在验证期间忽略异常（nbval-raises-exception）。

实验结果

研究问题

• RQ1 Jupyter 笔记本能否有效用作科学和数据科学代码的自动化测试形式？
• RQ2 当依赖项发生变化时，如何随时间自动验证笔记本中的输出可重现性？
• RQ3 哪些机制能够实现对笔记本输出中可变输出（如时间戳、内存地址）的可靠对比？
• RQ4 如何将笔记本验证集成到 CI/CD 流水线中以支持生产环境使用？
• RQ5 笔记本在不增加维护负担的前提下，能在多大程度上同时作为文档和测试套件？

主要发现

• 当代码更改导致输出偏离先前保存的结果时，nbval 能够成功检测到输出不匹配。
• 基于正则表达式的净化方法可实现对包含时间或环境特定值的输出的可靠对比。
• 与 nbdime 的集成支持图像和多媒体输出的可视化对比，提升了差异调试效率。
• 经 nbval 验证的笔记本可作为系统测试使用，无需额外编写测试代码即可提升测试覆盖率。
• 该插件支持增量式测试和文档维护，减少了科研软件项目中的技术债务。
• nbval 实现了笔记本的早期和持续验证，有助于防止回归问题并确保长期可重现性。