将TOX与Jenkins Integration Server配合使用

使用Jenkins多配置作业

这个 Jenkins 持续集成服务器允许您使用“构建步骤”定义“作业”，这些步骤可以是测试调用。如果你 install tox 在每个Jenkins代理上的默认Python安装上，您可以使用以下步骤轻松创建一个Jenkins多配置作业，该作业将从CI服务器端驱动您的tox运行：

  • 在“管理Jenkins”下安装Jenkins的Python插件

  • 创建一个“多配置”作业，给它一个您选择的名称

  • 配置您的存储库，以便Jenkins可以提取它

  • (可选)配置多个节点，以便在多个主机上执行tox运行

  • 配置 axes 通过使用 TOXENV 作为轴名称和AS值提供您希望Jenkins/tox执行的以空格分隔的测试环境名称。

  • 添加一个 Python-build step 包含此内容(另请参阅下一个示例)：

    import tox

os.chdir(os.getenv("WORKSPACE"))
tox.cmdline()  # environment is selected by ``TOXENV`` env variable

  • 检查 Publish JUnit test result report 然后进入 **/junit-*.xml 作为模式，以便Jenkins收集JUnit XML格式的测试结果。

最后一点要求您的测试命令创建JunitXML文件，例如使用 pytest 它是这样做的：

[testenv]
commands = pytest --junitxml=junit-{envname}.xml

zero-installation 对于座席

注解

由于“toxbootstrap.py”已被移除，此功能当前已被破坏。如果你想看回来，请提交一期。

如果您管理多个Jenkins代理，并且希望使用最新正式发布的tox(或最新开发版本)，并且希望跳过手动安装 tox 那么上面的替身 Python构建步骤 使用以下代码进行编码：

import urllib, os

url = "https://bitbucket.org/hpk42/tox/raw/default/toxbootstrap.py"
# os.environ['USETOXDEV']="1"  # use tox dev version
d = dict(__file__="toxbootstrap.py")
exec urllib.urlopen(url).read() in d
d["cmdline"](["--recreate"])

已下载的 toxbootstrap.py 文件下载要安装的所有必要文件 tox 在虚拟子环境中。注：

  • 取消对包含以下内容的行的注释 USETOXDEV 使用TOX的最新开发发布版本，而不是最新发布的版本。

  • 根据需要调整最后一行中的选项(示例代码将导致tox始终重新安装所有虚拟环境，这通常是CI服务器上下文中需要的)

在Jenkins作业中集成“Shinx”文档检查

如果您正在使用一个收集JUnit测试结果的多配置Jenkins作业，那么使用前面运行sphinx-build命令的方法将会遇到问题，因为它不会生成JUnit结果。要解决这个问题，一种解决方案是 pytest 包装sphinx-check并创建一个JUnit结果文件，该文件包装调用sphinx-build的结果。下面是一个示例：

  1. 创建一个 docs 您的 tox.ini 像这样的文件：

[testenv:docs]
basepython = python
# change to ``doc`` dir if that is where your sphinx-docs live
changedir = doc
deps = sphinx
       pytest
commands = pytest --tb=line -v --junitxml=junit-{envname}.xml check_sphinx.py

  1. 创建一个 doc/check_sphinx.py 像这样的文件：

import subprocess


def test_linkcheck(tmpdir):
    doctrees = tmpdir.join("doctrees")
    htmldir = tmpdir.join("html")
    subprocess.check_call(
        ["sphinx-build", "-W", "-blinkcheck", "-d", str(doctrees), ".", str(htmldir)]
    )


def test_build_docs(tmpdir):
    doctrees = tmpdir.join("doctrees")
    htmldir = tmpdir.join("html")
    subprocess.check_call(
        ["sphinx-build", "-W", "-bhtml", "-d", str(doctrees), ".", str(htmldir)]
    )

  1. 运行 tox -e docs 然后，您可以将此环境与其他环境一起集成到Jenkins中。

注意 pytest 仅安装到文档环境中，不需要与任何其他环境一起使用或安装。

在Jenkins作业之间访问包工件

在对的扩展中 在多个tox运行之间访问包工件 您还可以配置Jenkins作业来访问彼此的工件。 tox 使用 distshare 目录以访问Jenkins上下文中的构件(通过环境变量的存在检测到 HUDSON_URL )；默认为 {{toxworkdir}}/distshare .

这意味着每个工作空间都将有自己的工作空间 distshare 目录，我们需要配置Jenkins来执行工件复制。建议执行此操作的方法是安装 Jenkins Copy Artifact plugin 对于每个“接收”工件的作业，您都会添加一个 从另一个项目复制工件 大致使用以下配置的构建步骤：

Project-name: name of the other (tox-managed) job you want the artifact from
Artifacts to copy: .tox/dist/*.zip   # where tox jobs create artifacts
Target directory: .tox/distshare     # where we want it to appear for us
Flatten Directories: CHECK           # create no subdir-structure

您还需要配置“Other”作业来归档工件；这是通过选中 Archive the artifacts 并输入：

Files to archive: .tox/dist/*.zip

因此，我们的“其他”作业将创建一个sdist-package工件，而“copy-artitures”插件将把它复制到我们的 distshare 区域。现在一切都进行得很顺利 在多个tox运行之间访问包工件 显示出来了。

因此，如果您使用的是缺省设置，则可以完全相同地重用和调试 tox.ini 文件，并利用在运行或Jenkins作业之间自动共享工件。

用较长的横切线避免“路径过长”错误

使用时 tox 在Jenkins实例上，可能存在以下情况 tox 无法调用 pip 因为谢邦(Unix)的队伍太长了。某些系统仅支持解释器指令的有限字符数(e.x。Linux作为128个的限制)。有两种方法可以解决此问题：

  1. 援引 tox 与 --workdir 选项，该选项告诉您 tox 为其虚拟环境使用特定目录。使用唯一的短路径可以防止此问题。

  2. 使用环境变量 TOX_LIMITED_SHEBANG 处理具有解释器指令限制的环境(请参阅 处理长度较长的解释器指令 更多信息）。

并行运行TOX环境

Jenkins有并行的阶段，允许您并行运行命令，但是构建tox包并不是并行安全的。使用 --parallel--safe-build 启用并行安全生成的标志(这将为生成唯一的文件夹名称 distdir ， distshare 和 log 。下面是一个通用的舞台定义，演示了如何在Jenkins中使用它：

stage('run tox envs') {
  steps {
    script {
      def envs = sh(returnStdout: true, script: "tox -l").trim().split('\n')
      def cmds = envs.collectEntries({ tox_env ->
        [tox_env, {
          sh "tox --parallel--safe-build -vve $tox_env"
        }]
      })
      parallel(cmds)
    }
  }
}