在更新包时,如何自动执行 LaTeX 文档的“回归测试”?

在更新包时,如何自动执行 LaTeX 文档的“回归测试”?

我最近问了一个相关问题多久更新一次 LaTeX 软件包假设我一次性更新一堆软件包,或者定期更新但只更改几个软件包,我该如何测试我的 TeX 文档没有发生重大变化?

在编程中,这类似于单元测试或回归测试。也许我将太多编程错误的经验带到了 LaTeX 领域,但我担心的是,随着时间的推移,不同版本的软件包会导致不同的 PDF 输出。

我知道latexdiff,并经常使用它来手动检查 tex 文件中的差异,但这并不能解决两个问题:它无法轻松捕获归因于不同软件包版本的差异,而且我不清楚它是否可以轻松自动识别那些存在差异的文件。在我看来,前一个问题需要我做很多工作来手动隔离不同版本的软件包,而后一个问题似乎根本不容易实现自动化。

对于使用相同依赖项的不同版本编译的文件,是否有其他方法可以检查输出是否看起来相同?


更新 1:用例:假设您有很多已发布的文档或大量手稿,并且希望确保它们的编译版本不会因软件包更新而发生变化。您可能想要更改输出,因此需要进行软件包更新,但最重要的是您知道如果一切都发生了变化,并且你随后可以辨别出它们是如何变化的以及为什么变化。

答案1

LaTeX3 项目在这方面有一些经验,尽管我们目前的大多数自动化测试更侧重于代码输入/输出,而不是排版材料。这些脚本是为 LaTeX2e 开发的,但已进行了一些更新以用于 LaTeX3。

在使用框和输出例程的上下文中,我们确实有两种形式的回归测试,至少在一定程度上可以测试排版材料。这两种测试和更具程序性的测试都依赖于使用一个或多个测试文档,这些文档将详细信息写入日志文件。在进行一些基于脚本的清理以删除“动态”材料后,可以将它们与同一日志的参考版本进行比较,以检查输入和输出是否相同。

要构建合适的测试文件,可能需要一些想象力。例如,对于基于盒子的测试,我们使用类似于的东西\showthe\box...,它将在日志中显示盒子的内容。因此,如果您将要检查的材料装箱,然后将盒子写入日志,您就可以准确地看到那里有什么。

对于整页,您可以\tracingall在发货期间使用它来将页面上的所有内容记录到日志中。除此之外,我们还在输出例程代码等中设置了“跟踪”DocStrip 保护。此额外代码将非常详细的信息写入日志,例如计算的每个结果。布局的更改会改变这些数字,即使只是细微的,然后脚本就可以发现这些数字。

LaTeX3 项目用于测试的实现都可以从我们的 GitHub 网站. 关键机制包括特殊的 LaTeX 文件用于排版测试,以及小 Perl 脚本格式化日志(在某个阶段,最好用 Lua 重写后者,因为这样可以让事情更加独立)。支持这两个文件的是许多 Makefile/批处理脚本,它们都具有相同的通用格式,以及各种测试文件本身(测试输入为.lvt,测试输出为.tlg)。

2016 年 9 月更新

该团队在测试方面付出了巨大努力,并开发了l3build 作为 (La)TeX 的集成测试和构建系统。它还可以用于自动化测试,团队已使用特拉维斯-CI在每次提交时执行此操作。有一个拖船文章l3build以及我们的 Travis 设置。后者(目前)仅供 TUG 会员直接使用,但您可以获取源代码来自 LaTeX3 GitHub repo。

答案2

这实际上不是一个完整的答案,只是一些想法和提示。另一方面,对于评论来说它太长了。

鉴于我们已经更新了几个软件包:

  • 第一个回归可能是编译所有测试文档,然后通过比较日志文件来查看编译过程本身是否存在任何差异。新的编译错误显然表明存在回归问题,但新的警告也可能有帮助。当然,某些包的记录输出可能已更改,而包本身没有任何“实质性更改”。但是,搜索“魔法术语”,例如“depricated”,仍然可能触发潜在的回归问题。
  • 鉴于文档仍可编译,重点当然是视觉差异。一种显而易见的方法是逐页比较生成的 PDF。不幸的是,很少有“PDF 差异工具”真正计算出视觉的diff。据我所知,Adobe Acrobat Pro 可以做到这一点。更适合脚本编写(尽管据说 Acrobat 脚本编写得很好)的解决方案可能涉及 ImageMagick 或其他转换器,首先将每个 PDF 页面转换为 PNG 图形。PNG 页面(理论上)应该是二进制“可区分的”。至少应该能够找到具有一些视觉差异的页面。
  • 根据您的“测试文档”集,上一点可能涉及较高的计算开销。如果您有几本书,总共有几千页,那么盲目逐页比较所有内容的成本将很高。使用选项-recorderpdflatex每个文档计算实际使用的输入文件列表(包括包及其所有依赖项)并使用此信息仅对实际依赖于已更改包的文档进行回归分析可能是一个好主意。

相关内容