构建和测试 Python

本指南将介绍如何使用 TeamCity 构建 Python 项目，适合完全没有接触过 TeamCity 的开发者。

前提

We recommend that you have a basic understanding of Python and PyTest.

有关详情，请浏览 Python 文档。

第 1 步 - 创建 TeamCity 项目

  1. 点击 TeamCity 页面右上角的 Administration 齿轮。
  2. 点击 + Create Project，选择 From a repository URL 标签页。 In the Repository URL field, enter your repository, for example: https://github.com/marcobehlerjetbrains/teamcity-python.git. TeamCity 可以开箱即用地处理所有主流版本控制系统：Git、Subversion、Mercurial、Perforce 和 TFS（TeamCity Cloud + 本地部署）。 CVS、StarTeam 和 Visual SourceSafe 支持仅在 TeamCity 本地部署中可用。
  3. 如果您的仓库需要身份验证，请输入您的用户名和密码/访问令牌。
  4. 点击 Proceed。

如果 TeamCity 成功连接到您的仓库，您将看到以下对话框。

在 Create Project From URL 对话框中，您可以选择更改项目名称和初始构建配置名称。

注意：在较新版本的 TeamCity 中，您还将看到 Default branch 和 Branch specification 字段，用于指定 TeamCity 应构建的分支。 这可暂时忽略。

  • TeamCity 会建议一个默认的项目名称，但您可以根据需要为您的项目选择一个更合适的名称。
  • TeamCity 还将建议默认构建配置名称。 可以保留默认名称，如果需要，您稍后可以更改。 （每个 TeamCity 项目均应包含至少一个构建配置，其中包括构建项目所需的所有步骤。 TeamCity 的构建配置在其他 CI 系统中通常称为作业。）
  • 点击 Proceed。

点击 Proceed 后，TeamCity 会自动扫描您为支持的技术（在本例中为 Python）使用的版本控制仓库。

当 TeamCity 在您的仓库中检测到 .py 文件时，它会自动为您的项目建议一个或多个构建步骤。 对于本教程中使用的仓库，自动检测到的构建步骤将运行您的 main.py 或 setup.py 文件，这可能不符合您的预期。

不过，仍应将以下构建步骤默认添加到您的 Python 项目：

  1. Linting 构建步骤，执行 Flake8 或 PyLint
  2. Testing 构建步骤，执行 PyTest 或 UnitTest。

将这两个构建步骤都添加到您的项目，而非选择自动检测到的某个构建步骤。

首先向 TeamCity 项目添加 Flake8 linting 步骤。

  1. 点击 Build Steps，放弃自动检测到的构建步骤。
  2. 点击 Add Build Step，选择 Runner type: Python 添加能够构建 Python 代码的构建步骤。
  3. 选择 Command: Flake8，此 Python 项目具有用于 linting 的 Flake8 依赖项。 如果您的项目将 Pylint 用于 linting，应选择 Pylint。
  4. 您可以在 Script or module arguments 字段中指定要 lint 的目录。 如果您使用的是本教程中的 Python 仓库，则将其设置为“src/anewtodolist”。 或者，也可以将其留空，以 lint 整个项目。
  5. 可选：如果您的项目仍使用 2.x，则应选择不同的主要 Python 版本。
  6. 环境工具：该项目使用 Virtualenv 处理需要的所有依赖项，如 Flake8 和 PyTest。 确保选择 Virtualenv 作为环境工具以启用其支持。
  7. 点击 Save。

如果您成功创建了构建步骤，您将看到以下对话框。

接下来，我们来为您的项目添加 PyTest 步骤。

  1. （可选）如果您不在 Build Steps Overview 页面，请点击 Build Steps 放弃自动检测到的构建步骤。
  2. 点击 Add Build Step，选择 Runner type: Python 添加能够构建 Python 代码的构建步骤。
  3. 选择 Command: Pytest，此 Python 项目具有用于测试的 Pytest 依赖项。 如果您的项目将 UnitTest 用于测试，应选择 UnitTest。
  4. 可选：您可以在 Script or module arguments 字段中指定要测试的目录。 或者将其留空，如果您的测试位于 /tests 文件夹下，Python 运行程序将自动检测到该文件夹。
  5. 可选：如果您的项目仍使用 2.x，则应选择不同的主要 Python 版本。
  6. 环境工具：该项目使用 Virtualenv 处理需要的所有依赖项，如 Flake8 和 PyTest。 确保选择 Virtualenv 作为环境工具以启用其支持。
  7. 点击 Save。

第 2 步 - 运行您的第一个构建

现在，您可以运行您的第一个构建了。

  1. 点击窗口右上角的 Run 按钮，如下所示。
  2. 等待构建开始和完成。

注意：如果您使用的是 TeamCity Cloud，构建代理可能需要几分钟才能可用。 在此期间，您的构建将在队列中等待，直到被可用代理接收。

如果您将 TeamCity 本地部署与本地构建代理搭配使用，您的构建将立即开始。

构建开始后，您将被重定向到构建的概览页面，Build Log 标签页处于打开状态，显示与您的构建相关的实时数据。

构建运行后，您将被重定向到构建的概览页面。 现在，您可以查看测试结果和检查，或从构建的概览页面浏览完整的构建日志。

第 3 步 - 配置 Python TeamCity 项目

现在，您的 Python 仓库已连接到 TeamCity，您可以继续开发并将代码推送到您的仓库。

默认情况下，TeamCity 每隔 60 秒轮询一次 VCS 仓库的主分支以获取传入更改，并为所有检测到的提交触发一个（组合）构建。

构建分支

如果您想让仓库中任意分支的每次更改（而不仅仅是主分支）都触发构建，应将通配符分支规范添加到您的 VCS 根设置。 请注意，VCS 设置属于 TeamCity 项目，而不属于单个构建配置。 因此，您所做的任何更改都将应用于使用相同 VCS 根的所有构建配置。

  1. 在项目的概览页面上，点击 Edit Project。 或者，如果您已打开 Build 构建配置，请点击 Edit Configuration。
  2. 导航到 VCS 根（版本控制系统）并编辑您的 VCS 根。
  3. 填写 Branch Specification 输入字段，然后点击 Save。 如果您看不到 Branch Specification 输入字段，请先点击 Show Advanced。

示例分支规范：

  • +:refs/heads/* – TeamCity 将检查项目所有分支中的更改，但不会检查 GitHub 等平台上的 Pull Request，因为其与 refs/pull/* 匹配。
  • +:* – TeamCity 将检查任何分支上的任何传入更改。
  • 您自己的自定义分支规范。

TeamCity 现在将监控所有符合您的分支规范并推送到您的仓库的分支，检查传入的更改，并相应地运行构建。

构建 Pull Request

如果您希望 TeamCity 针对您的仓库自动构建 Pull Request，可以将 Pull Request 构建功能添加到您的构建配置。

  1. 打开您的构建配置，点击 Edit Configuration。
  2. 导航到 Build Features，点击 Add Build Feature。 如果您看不到 Build Features 链接，请点击 Show More。
  3. 从下拉列表选择 Pull Requests，选择您的仓库以及仓库提供商（GitHub、GitLab 等）。
  4. 或者，按作者或分支名称应用 Pull Request Filtering。

注意：Pull Request 构建功能会透明地扩展分支规范（更多信息见上一步）。 例如，对于 GitHub，Pull Request 功能将（不可见地）把 +:refs/pull/* 添加到您的分支规范。

我们建议在使用 Pull Request 功能时，确保 Pull Request 分支不在您的通用分支规范内，否则 Pull Request 相关功能在 TeamCity 中将不可用。

TeamCity 现在将检查外部平台的 Pull Request，并为符合您的配置规则的请求触发构建。

注意：如果在公共仓库上，您应谨慎使用此功能，因为任何人都可能将有害代码推送到仓库（您显然不想构建这样的代码）。

Commit Status Publisher

When using the pull requests feature in combination with Azure DevOps, Bitbucket Server, GitHub, or GitLab, it also makes sense to use the Commit Status Publisher build feature. 此功能将在相应平台上以构建结果更新 Pull Request 的状态。

要将 TeamCity 设置为向 GitHub 报告构建结果，您需要执行以下步骤：

  1. 打开您的构建配置，点击 Edit Configuration。
  2. 导航到 Build Features，点击 Add Build Feature。
  3. 从下拉列表中选择 Commit Status Publisher，然后选择您的仓库和发布者（GitHub、GitLab 等）。
  4. 提供具有足够权限的访问令牌以发布提交状态。
  5. 点击 Save。

TeamCity 运行构建后，您可以直接从 GitHub 的 Pull Request 标签页（绿色复选标记）轻松查看更改是否导致构建失败。