Mercurial Test Helpers

这是一个帮助编写围绕Mercurial Python代码的集成测试的设施集合：核心开发和扩展或其他下游，如 forge 和图形用户界面。

它还提供了一个 coverage 插件，允许根据当前的 Mercurial 版本来检查语句。

有关更多详细信息，请参阅集成测试计划wiki页面。

该项目使用其自己的辅助工具进行测试，因此提供的许多测试也可以用作示例。

它有一个100%的覆盖率政策，由预提交的持续集成强制执行。

常见问题解答

项目目标

目标是将这些测试辅助工具包含在Mercurial核心中。

一旦发生这种情况，本项目将用于提供向后兼容性，特别是对于那些需要与核心包含之前的 Mercurial 版本兼容的扩展。

pytest 是否是强制性的？

这些辅助工具只是为了轻松创建设置和处理 Mercurial 仓库而提供的快捷方式。它们自身不依赖于测试框架。只有它们自己的测试才依赖于。

更紧密的 pytest 集成将作为一个独立的项目提供：pytest-mercurial

支持哪些 Python 和 Mercurial 版本？

支持 CPython 2.7、3.7 和 3.8。

如果 Mercurial 支持，PyPy 应该也能工作，除非是用于测试跳过的 Mercurial 扩展的发现。

Mercurial 版本是列在 tox.ini 中的。截至本文写作时，这些是 Python 2 上的 Mercurial 4.3 到 5.9，以及 Python 3 上的 5.3 到 5.9。

为什么不使用通用的 Mercurial 库？

做出的选择旨在提高效率（特别是在编写测试的任务中）。一些功能在通用库中可能是不合法的，例如随机的提交信息和文件内容。

另一方面，对于边界情况的额外关注并非总是必要的：如果辅助工具在用户的情况下表现不佳，用户始终可以选择降低级别。这在测试中比在主应用程序代码中更容易接受：立即添加缺失的测试并获得好处（非回归，为主代码重构提供基础）比推迟它以破坏规则要好得多（不用说测试中不存在技术债务）。

兼容性和稳定性

本项目过于年轻和简单，无法清晰地了解将会发生什么，但我们有理由保持乐观。

它最初是在 Mercurial 5.2 上启动的，并且很容易移植到 4.3。一旦它被集成到 Mercurial 核心中，向前兼容性就不会成为问题。原因在于它以高级别调用 Mercurial，实际上经常通过命令行界面后面的函数进行。

由于兼容性似乎很容易，一旦我们确定了基本名称，为下游用户提供稳定性不应太难。

此外，测试辅助工具的 API 中不需要强制使用 bytes，这是直接帮助处理在 Python 2 最终在 Mercurial 中被淘汰后可能发生的 bytes 与 str 的变化（例如，dict 键等）。虽然可以确定这些变化将对 Mercurial 开发者造成痛苦，无论是在核心还是在其他地方，但至少如果测试设置仍然工作，我们希望这会有所帮助。

使用覆盖率插件

必须在 .coveragerc 中激活插件。

[run]
plugins = coverage_mercurial

然后可以注释说明要运行的 Mercurial 版本。例如：

from mercurial import util

if util.versiontuple() < (5, 4):
   do_something()  # hg<5.4

上面的注释意味着当使用，例如，Mercurial 5.5 时，将排除对 do_something() 语句的覆盖率。

详细信息

• 仅支持使用 <、>、=、<= 和 >= 进行简单比较。
• 在注释本身中不允许任何空白。忽略注释的起始和结尾单词。
• 不能使用和/or 逻辑连接符创建更复杂的规则。使用多个标记时的当前行为在未来的某个版本中未指定，并将进行更改——不要依赖它。
• 支持的 Mercurial 版本是 x.y 类型。既不支持更广泛的规范（例如，hg<5），也不支持更精确的规范（例如，hg>4.8.2）。对它们的行为也未作说明，并且可以在任何未来的版本中更改。

运行这些测试辅助工具的测试

获取测试运行的最快方法是使用 tox，因为这个软件包附带了一个 tox 配置文件，它定义了一系列 Python 和 Mercurial 的组合。

0. 先决条件

   • 目标 Python 版本，在 $PATH 中作为 python2 或 python3 可用
   • 构建 Mercurial 源码所需的相关依赖项（Python 开发文件，通常在名为 python$VERSION-dev 或 python$VERSION-devel 的软件包中）

1. 安装 tox

   包管理器提供的版本通常没有问题。

   • Debian 和其衍生产品： apt install tox
   • Fedora： dnf install python3-tox
   • MacPorts/HomeBrew： ?
   • 通用： $somepython -m pip install tox。此 $somepython 可以与实际运行测试的 Python 完全不同。此外，tox 还是一个 virtualenv 管理器。

2. 针对特定 Python 和 Mercurial 版本运行： tox -e py3-hg-5.6。

   第一次运行将构建 Mercurial，后续的运行将会更快。

3. 运行所有组合的 tox： tox

   虽然第一次运行会很长，因为它将构建所有版本组合的 Mercurial，但后续的运行相当合理

   $ time tox
   (...)
   ____________ summary ____________
     py3-hg5.6: commands succeeded
     py3-hg5.5: commands succeeded
     py3-hg5.4: commands succeeded
     py3-hg5.3: commands succeeded
     py2-hg5.6: commands succeeded
     py2-hg5.5: commands succeeded
     py2-hg5.4: commands succeeded
     py2-hg5.3: commands succeeded
     py2-hg5.2: commands succeeded
     py2-hg5.1: commands succeeded
     py2-hg5.0: commands succeeded
     py2-hg4.9: commands succeeded
     py2-hg4.8: commands succeeded
     py2-hg4.7: commands succeeded
     py2-hg4.6: commands succeeded
     py2-hg4.5: commands succeeded
     py2-hg4.4: commands succeeded
     py2-hg4.3: commands succeeded
     congratulations :)
   tox  39.53s user 5.27s system 99% cpu 45.044 total
   

包含示例及其运行方法

examples/core

这些是 Mercurial 核心的实际测试，翻译（.t 测试的情况）或未翻译（Python 测试）。

它们作为主套件的一部分运行。如果您已经运行了 tox 测试运行，那么您已经尝试过它们。

tests/test_repo_wrapper.py 也是获取示例的来源，了解可以做什么。

examples/evolve

这些是用 evolve 和 topic 扩展进行测试的玩具示例，以及 hg-evolve 项目如何扩展这些辅助工具。

要运行它们，必须在 Mercurial 和 hg-evolve 可用的环境中使用 run-all-tests 脚本。示例

python3 -m venv venv_hg_evolve
venv_hg_evolve/bin/pip install Mercurial==5.5.2 hg-evolve
source venv_hg_evolve/bin/activate
pip install -r test-requirements.txt
./run-all-tests

备注

• 对于 Python 2，首先使用 virtualenv -p python2，然后就是一样的。

• 通常，在虚拟环境中安装 mercurial 后无法立即导入。这就是为什么上面的第一个 pip 在激活之前的原因。

• 还可以仅运行 hg-evolve 示例

  pytest examples/hg_evolve
  

examples/hg-git

另一个玩具示例，这次有额外的集成需求（Git 本身）。

先决条件： git 标准可执行文件，在 $PATH 中可用。

要运行测试，必须在 Mercurial 和 hg-git 可用的环境中使用 run-all-tests 脚本。示例

python3 -m venv venv_hg_git
venv_hg_git/bin/pip install Mercurial==5.6 hg-git
source venv_hg_git/bin/activate
pip install -r test-requirements.txt
./run-all-tests

备注

• 对于 Python 2，首先使用 virtualenv -p python2，然后就是一样的。

• 通常，在虚拟环境中安装 mercurial 后无法立即导入。这就是为什么上面的第一个 pip 在激活之前的原因。

• 还可以仅运行 hg-git 示例

  pytest examples/hg_git
  

致谢

维基百科用户：Townie 的 Test tube 标志，许可 Creative Commons by-sa 国际 4.0

变更日志

版本 0.6.0 (2021-10-21)

• !11: 新的 RepoWrapper.reload() 方法
• 覆盖率插件：支持 Mercurial 版本 6.x

版本 0.5.0 (2021-02-17)

• #2: 在创建提交的方法中为 datetime 和时区提供选项
• #3: 通用辅助程序，用于调用命令，即使没有存储库也可以
• #4: 创建合并提交的辅助方法

版本 0.4.0 (2020-12-20)

• #5: 在 RepoWrapper 上保留原始路径
• #6: 存储库配置（内存中）和 .hg/hgrc 编写器的辅助方法。