Visual Studio Code 中的 Python 测试

Python 扩展基于 VS Code 内置的测试功能构建，为 Python 内置的 unittest 框架和 pytest 提供测试发现、测试覆盖率以及运行和调试测试的功能。

配置测试

安装 Python 扩展并在编辑器中打开 Python 文件后，VS Code 活动栏上会显示一个烧杯图标，代表测试资源管理器 (Test Explorer) 视图。如果尚未启用测试框架，打开测试资源管理器会显示一个配置 Python 测试 (Configure Python Tests) 按钮。选择配置 Python 测试后，系统会提示您选择测试框架和包含测试的文件夹。如果您使用 unittest，还需选择用于标识测试文件的文件 glob 模式。

您可以随时通过命令面板中的 Python: 配置测试 (Python: Configure Tests) 命令，或者按照 VS Code 设置文档所述，在设置编辑器或 settings.json 文件中设置 python.testing.unittestEnabled 或 python.testing.pytestEnabled 来配置测试。每个框架还有特定的配置设置，详见下文的测试配置设置，包括文件夹和模式设置。

如果您启用了 pytest 但当前激活的环境中未安装它，Python 扩展会尝试在后台进行安装。此外，如果两个框架都已启用，Python 扩展将仅运行 pytest。

测试发现

默认情况下，一旦您启用了框架，Python 扩展就会尝试发现测试。您可以随时使用命令面板中的 测试: 刷新测试 (Test: Refresh Tests) 命令来触发测试发现。

测试发现将对当前框架应用发现模式（可通过测试配置设置进行自定义）。默认行为如下：

• python.testing.unittestArgs：在项目顶层文件夹中查找名称中带有 "test" 的任何 Python (.py) 文件。所有测试文件必须是可导入的模块或包。您可以使用 -p 配置设置自定义文件匹配模式，并使用 -t 设置自定义文件夹。

• python.testing.pytestArgs：在当前文件夹及其所有子文件夹中查找名称以 "test_" 开头或以 "_test" 结尾的任何 Python (.py) 文件。

如果测试发现成功，您将在测试资源管理器中看到列出的测试。

当直接从测试资源管理器触发测试发现时，您也可以取消正在进行的测试发现调用。使用取消 (Cancel) 按钮，该按钮会在发现过程中替换刷新 (Refresh) 按钮。

如果发现失败（例如，未安装测试框架或测试文件中存在语法错误），您将在测试资源管理器中看到一条错误消息，其中包含指向日志的链接。您可以查看 Python 输出面板以获取完整的错误消息（使用查看 (View) > 输出 (Output) 菜单命令显示输出面板，然后从右侧的下拉菜单中选择 Python）。

运行测试

您可以使用以下任何操作来运行测试：

• 在打开测试文件的情况下，选择显示在测试定义行旁边装订线（gutter）中的绿色运行图标（如前一节所示）。此命令仅运行该特定方法。

  

• 从命令面板中，通过运行以下任何命令：

  • 测试: 运行所有测试 (Test: Run All Tests) - 运行所有已发现的测试。
  • 测试: 运行当前文件中的测试 (Test: Run Tests in Current File) - 运行编辑器中打开的文件中的所有测试。
  • 测试: 运行光标处的测试 (Test: Run Test at Cursor) - 仅运行编辑器中光标所在的测试方法。

• 从测试资源管理器中：

  • 要运行所有已发现的测试，请选择测试资源管理器顶部的播放按钮。

    

  • 要运行特定组的测试或单个测试，请选择文件、类或测试，然后选择该项目右侧的播放按钮。

    

  • 您也可以通过测试资源管理器运行一组选定的测试。为此，请 Ctrl+单击（macOS 上为 Cmd+单击）选择您要运行的测试，右键单击其中一个，然后选择运行测试 (Run Test)。

测试运行后，VS Code 会直接在编辑器中以装订线装饰的形式显示结果。失败的测试也会在编辑器中高亮显示，并带有显示测试运行错误消息和所有测试运行历史记录的 Peek View（速览视图）。您可以按 Escape 关闭该视图；也可以通过打开用户设置（在命令面板中选择首选项: 打开设置 (UI) 命令），并将测试: 自动打开速览视图 (Testing: Automatically Open Peek View) 设置的值更改为 never 来禁用它。

在测试资源管理器中，结果会显示在各个测试以及包含这些测试的类和文件中。如果文件夹内的任何测试未通过，文件夹将显示失败图标。

VS Code 还会显示测试结果 (Test Results) 面板中的测试结果。

带覆盖率运行测试

要开启覆盖率运行测试，请在测试资源管理器中选择覆盖率运行图标，或者从您通常触发测试运行的任何菜单中选择带覆盖率运行 (Run with coverage) 选项。如果您使用的是 pytest，Python 扩展会使用 pytest-cov 插件运行覆盖率；如果您使用的是 unittest，则使用 coverage.py。

覆盖率运行完成后，编辑器中的行会高亮显示，以表示行级覆盖率。测试覆盖率结果将作为“测试覆盖率”子选项卡出现在测试资源管理器中，您也可以通过命令面板中的测试: 聚焦于测试覆盖率视图 (Testing: Focus on Test Coverage View) 导航到该选项卡（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。在此面板上，您可以查看工作区中每个文件和文件夹的行覆盖率指标，以及相关的分支覆盖率。

在使用 pytest 时，为了更精细地控制覆盖率运行，您可以编辑 python.testing.pytestArgs 设置以包含您的规范。当 python.testing.pytestArgs 中存在 pytest 参数 --cov 时，Python 扩展将不会对覆盖率参数进行任何额外编辑，以确保您的自定义设置生效。如果没有找到 --cov 参数，扩展会在运行前自动将 --cov=. 添加到 pytest 参数中，从而在工作区根目录下启用覆盖率。

有关测试覆盖率的更多信息，请访问 VS Code 的测试覆盖率文档。

调试测试

要调试测试，请右键单击函数定义旁边的装订线装饰并选择调试测试 (Debug Test)，或者选择测试资源管理器中该测试旁边的调试测试图标。

您可以在命令面板中使用以下命令来调试测试：

• 测试: 调试所有测试 (Test: Debug All Tests) - 为工作区中的所有测试启动调试器。
• 测试: 调试当前文件中的测试 (Test: Debug Tests in Current File) - 为编辑器中打开的文件中定义的测试启动调试器。
• 测试: 调试光标处的测试 (Test: Debug Test at Cursor) - 仅为编辑器中光标聚焦的方法启动调试器。您还可以使用测试资源管理器中的调试测试图标为所选范围内的所有测试和所有已发现的测试启动调试器。

您还可以更改默认行为：在 settings.json 文件中将 testing.defaultGutterClickAction 设置的值更改为 debug，即可将点击装订线装饰的操作改为调试测试而不是运行测试。

调试器对于测试的工作方式与其他 Python 代码相同，包括断点、变量检查等。要自定义调试测试的设置，您可以通过在工作区 .vscode 文件夹的 launch.json 或 settings.json 文件中添加 "purpose": ["debug-test"] 来指定测试调试配置。当您运行测试: 调试所有测试、测试: 调试当前文件中的测试和测试: 调试光标处的测试命令时，将使用此配置。

例如，下面 launch.json 文件中的配置禁用了调试测试时的 justMyCode 设置：

{
  "name": "Python: Debug Tests",
  "type": "debugpy",
  "request": "launch",
  "program": "${file}",
  "purpose": ["debug-test"],
  "console": "integratedTerminal",
  "justMyCode": false
}

如果您有多个带有 "purpose": ["debug-test"] 的配置条目，将使用第一个定义，因为我们目前不支持为此请求类型提供多个定义。

有关调试的更多信息或了解其在 VS Code 中的工作原理，请阅读Python 调试配置和通用的 VS Code 调试文章。

并行运行测试

通过 pytest-xdist 包支持使用 pytest 并行运行测试。请访问他们的文档，以获取有关如何使用 pytest-xdist 的更多信息。

当启用 xdist 且参数中未指定工作进程数时，Python 扩展会根据测试资源管理器中选定的测试数量自动优化工作进程数量。

Django 单元测试

Python 扩展还提供对发现和运行 Django 单元测试的支持！只需几个额外的设置步骤即可发现您的 Django 测试：

1. 在您的 settings.json 文件中设置 "python.testing.unittestEnabled": true,。
2. 将 MANAGE_PY_PATH 添加为环境变量。
   1. 在项目根目录创建一个 .env 文件。
   2. 将 MANAGE_PY_PATH='<path-to-manage.py>' 添加到 .env 文件中，并将 <path-to-manage.py> 替换为您应用程序 manage.py 文件的路径。

      提示：您可以通过在资源管理器视图中右键单击该文件并选择复制路径 (Copy Path) 来复制路径。

3. 根据需要将 Django 测试参数添加到 settings.json 文件中的 "python.testing.unittestArgs": []，并删除与 Django 不兼容的任何参数。

导航到测试视图，并选择刷新测试 (Refresh Tests) 按钮以显示您的 Django 测试！

故障排除

如果您的 Django 单元测试未在测试视图中显示，请尝试以下故障排除步骤：

• 在 Python 输出面板中搜索错误消息。它们可能会提供关于为何未发现测试的线索。
• 尝试在终端中运行 Django 测试。然后将相同的命令“转换”为 VS Code 设置。例如，如果您在终端中运行 python manage.py test --arg，则应在 .env 文件中添加 MANAGE_PY_PATH='./manage.py'，并在 VS Code 设置中设置 "python.testing.unittestArgs": [--arg]。或者，您也可以在 Python 输出面板中找到 Python 扩展运行的命令。
• 如果在开始时使用了相对路径，请在设置 MANAGE_PY_PATH 环境变量时使用 manage.py 文件的绝对路径。

测试命令

以下是 VS Code 中 Python 扩展测试所支持的所有命令。这些命令均可在命令面板中找到：

测试配置设置

Python 的测试行为受 VS Code 提供的通用 UI 设置以及特定于 Python 和您所启用的框架的设置驱动。

通用 UI 设置

影响测试功能 UI 的设置由 VS Code 本身提供，当您在 VS Code 设置编辑器中搜索“Testing”时可以找到它们。

Python 通用设置

设置 (python.testing.)	默认值	描述
autoTestDiscoverOnSaveEnabled	true	指定在保存测试文件时是否启用或禁用自动运行测试发现。在更改此设置后，您可能需要重新加载窗口以使其应用。
cwd	null	指定测试的可选工作目录。此设置的存在会动态调整 pytest 的 --rootdir 参数。
autoTestDiscoverOnSavePattern	**/*.py	指定一个 glob 模式，该模式确定当 autoTestDiscoverOnSaveEnabled 为 true 时，哪些文件更改会触发自动测试发现。
debugPort	3000	用于调试 unittest 测试的端口号。
promptToConfigure	true	指定如果发现潜在的测试，VS Code 是否提示配置测试框架。

unittest 配置设置

Unittest 设置(python.testing.)	默认值	描述
unittestEnabled	false	指定是否启用 unittest 作为测试框架。pytest 的相应设置应被禁用。
unittestArgs	["-v", "-s", ".", "-p", "*test*.py"]	传递给 unittest 的参数，其中每个由空格分隔的元素都是列表中的单独项目。有关默认值的描述，请参见下文。

unittest 的默认参数如下：

• -v 设置默认详细程度。删除此参数可获得更简洁的输出。
• -s . 指定发现测试的起始目录。如果您在“test”文件夹中有测试，请将该参数更改为 -s test（意味着在参数数组中为 "-s", "test"）。
• -p *test*.py 是用于查找测试的发现模式。在这种情况下，它是任何包含单词 "test" 的 .py 文件。如果您以不同方式命名测试文件，例如在每个文件名后追加 "_test"，则在数组的相应参数中使用类似 *_test.py 的模式。

要在第一次失败时停止测试运行，请将快速失败选项 "-f" 添加到参数数组中。

请参阅 unittest 命令行界面以获取可用选项的完整列表。

pytest 配置设置

pytest 设置(python.testing.)	默认值	描述
pytestEnabled	false	指定是否启用 pytest 作为测试框架。unittest 的相应设置应被禁用。
pytestPath	"pytest"	pytest 的路径。如果 pytest 位于当前环境之外，请使用完整路径。
pytestArgs	[]	传递给 pytest 的参数，其中每个由空格分隔的元素都是列表中的单独项目。请参阅 pytest 命令行选项。

pytest 的默认参数如下：

• rootdir 根据工作区中 python.testing.cwd 设置的存在而动态调整。

您还可以按照 pytest 配置中所述，使用 pytest.ini 文件配置 pytest。

注意

如果您安装了 pytest-cov 覆盖率模块，VS Code 在调试时不会在断点处停止，因为 pytest-cov 使用相同的技术来访问正在运行的源代码。为防止此行为，请在调试测试时在 pytestArgs 中包含 --no-cov，例如通过在调试配置中添加 "env": {"PYTEST_ADDOPTS": "--no-cov"}。（有关如何设置该启动配置，请参见上文的 调试测试。）（更多信息，请参阅 pytest-cov 文档中的 调试器和 PyCharm。）

IntelliSense 设置

IntelliSense 设置(python.analysis.)	默认值	描述
inlayHints.pytestParameters	false	是否显示 pytest fixture 参数类型的内联提示。接受的值为 true 或 false。

另请参阅

• Python 环境 - 控制用于编辑和调试的 Python 解释器。
• 设置参考 - 探索 VS Code 中所有与 Python 相关的设置。