开发工具

相关源文件

• .github/actionlint.yaml
• .github/workflows/build.yml
• .github/workflows/jit.yml
• .github/workflows/reusable-context.yml
• .github/workflows/reusable-docs.yml
• .github/workflows/reusable-macos.yml
• .github/workflows/reusable-tsan.yml
• .github/workflows/reusable-ubuntu.yml
• .github/workflows/reusable-wasi.yml
• .github/workflows/reusable-windows-msi.yml
• .github/workflows/reusable-windows.yml
• Lib/test/libregrtest/cmdline.py
• Lib/test/libregrtest/findtests.py
• Lib/test/libregrtest/logger.py
• Lib/test/libregrtest/main.py
• Lib/test/libregrtest/mypy.ini
• Lib/test/libregrtest/refleak.py
• Lib/test/libregrtest/result.py
• Lib/test/libregrtest/results.py
• Lib/test/libregrtest/run_workers.py
• Lib/test/libregrtest/runtests.py
• Lib/test/libregrtest/setup.py
• Lib/test/libregrtest/single.py
• Lib/test/libregrtest/utils.py
• Lib/test/libregrtest/worker.py
• Lib/test/pythoninfo.py
• Lib/test/support/__init__.py
• Lib/test/support/bytecode_helper.py
• Lib/test/test_compiler_assemble.py
• Lib/test/test_regrtest.py
• Lib/test/test_yield_from.py
• Modules/clinic/_testinternalcapi.c.h
• Tools/build/.ruff.toml
• Tools/build/.warningignore_macos
• Tools/build/.warningignore_ubuntu
• Tools/build/check_warnings.py
• Tools/build/compute-changes.py

概述

本文档提供了用于测试和开发 CPython 的工具的全面概述。它涵盖了回归测试框架 (libregrtest)、持续集成管道以及各种用于调试和性能分析的实用工具。有关构建系统的信息，请参阅 构建系统，有关扩展开发细节，请参阅 扩展开发与 C API。

CPython 开发工具集包括：

1. 用于验证解释器行为的回归测试框架
2. 用于自动化测试的持续集成管道
3. 用于检测内存泄漏和引用计数问题的工具
4. 用于衡量性能和代码覆盖率的实用工具

回归测试框架 (libregrtest)

CPython 的测试基础设施的核心是名为 libregrtest 的回归测试框架。该框架负责测试发现、执行和结果报告。

来源：Lib/test/libregrtest/main.py Lib/test/libregrtest/utils.py Lib/test/libregrtest/runtests.py Lib/test/libregrtest/findtests.py

测试发现

测试发现过程由 findtests.py 模块处理。测试通过以下方式发现：

1. 在 Lib/test 目录中搜索匹配 test_*.py 模式的 Python 文件
2. 支持对特定测试目录的特殊处理以提高并行度

来源：Lib/test/libregrtest/findtests.py20-31

测试执行模式

测试可以以几种模式执行

1. 顺序模式：测试在单个进程中一个接一个地运行。
2. 并行模式：测试同时在多个工作进程中运行。
3. 泄漏检测模式：测试运行多次以检测引用泄漏。
4. 覆盖率模式：测试运行时启用代码覆盖率跟踪。

这是单个测试的运行方式

来源：Lib/test/libregrtest/single.py

引用泄漏检测

测试框架最强大的功能之一是能够检测 CPython C 代码中的引用泄漏。这在 refleak.py 中实现，其工作原理是：

1. 通过预热运行多次测试
2. 跟踪 Python 引用计数、内存分配和文件描述符
3. 分析模式以检测泄漏

核心函数是 runtest_refleak()，它会多次运行测试并跟踪引用计数

来源：Lib/test/libregrtest/refleak.py52-305

测试支持设施

test.support 包提供了许多实用工具来支持测试开发和执行。

主要支持功能包括：

• 资源使用跟踪
• 临时文件和目录管理
• 网络测试实用程序
• 子进程管理
• 基于平台或可用资源的测试跳过机制

来源：Lib/test/support/__init__.py

命令行界面

测试框架主要通过其命令行界面使用。

python -m test [options] [test_name1 [test_name2 ...]]

命令行界面提供了丰富的选项集，这些选项按类别进行组织：

类别	示例选项	目的
通用	--timeout、--wait、--header	控制测试执行环境
详细程度	-v/--verbose、-W/--verbose3	控制输出详细级别
测试选择	-m/--match、-i/--ignore、-r/--randomize	控制运行哪些测试
执行	-j/--multiprocess、-s/--single	控制如何执行测试
特殊运行	-R/--huntrleaks、-T/--coverage	特殊测试模式
资源使用	-u/--use、-M/--memlimit	控制资源使用

来源：Lib/test/libregrtest/cmdline.py9-128

关键命令行选项

一些最重要的命令行选项

来源：Lib/test/libregrtest/cmdline.py207-545

持续集成管道

CPython 使用 GitHub Actions 进行持续集成。工作流定义在 .github/workflows 目录中。

来源：.github/workflows/build.yml .github/workflows/jit.yml .github/workflows/reusable-tsan.yml

主工作流 (build.yml)

build.yml 中的主工作流协调整个 CI 管道。

1. 确定哪些内容已更改以及需要运行哪些测试（build-context 作业）
2. 在必要时运行文档检查（check-docs 作业）
3. 在不同平台上运行测试
   • Windows (x86, x64, ARM64)
   • macOS (Intel, Apple Silicon)
   • Linux (x86_64, ARM64)
   • WASI (WebAssembly)
4. 运行专用测试
   • 线程 Sanitizer
   • 地址 Sanitizer
   • Hypothesis 测试
   • SSL 测试

来源：.github/workflows/build.yml13-672

平台特定测试

每个平台都有自己的工作流文件，定义了如何构建和测试 CPython。

平台	工作流文件	主要功能
Windows	reusable-windows.yml	在 x86、x64 和 ARM64 架构上进行测试
macOS	reusable-macos.yml	在 Intel 和 Apple Silicon 上进行测试
Linux	reusable-ubuntu.yml	在 x86_64 和 ARM64 上进行测试，并可选 BOLT 优化
WASI	reusable-wasi.yml	WebAssembly 测试

来源：.github/workflows/reusable-windows.yml .github/workflows/reusable-macos.yml .github/workflows/reusable-ubuntu.yml .github/workflows/reusable-wasi.yml

特殊测试模式

提供几种特殊的测试模式：

1. 线程 Sanitizer：使用 LLVM 的线程 Sanitizer 检测线程问题。
2. 地址 Sanitizer：使用 LLVM 的地址 Sanitizer 检测内存损坏。
3. JIT 测试：测试实验性的 JIT 编译器。
4. Hypothesis 测试：使用基于属性的测试来查找边缘情况。

来源：.github/workflows/reusable-tsan.yml .github/workflows/jit.yml

构建配置

测试在各种构建配置下运行，以确保 CPython 在不同环境中正常工作。

配置	描述	控制方式
调试构建	包含断言和调试符号	--with-pydebug 配置标志
发布构建	针对性能进行了优化	默认构建
启用 JIT	使用实验性的 JIT 编译器	--enable-experimental-jit 配置标志
自由线程	在没有全局解释器锁 (GIL) 的情况下运行	--disable-gil 配置标志
Sanitizers	使用 LLVM Sanitizers	--with-address-sanitizer、--with-thread-sanitizer
BOLT 优化	使用 LLVM 的 BOLT 优化器	--enable-bolt 配置标志

来源： .github/workflows/build.yml150-172 .github/workflows/reusable-ubuntu.yml91-100

系统信息收集

CPython 包含一个用于收集系统信息的工具，以帮助调试测试失败。 pythoninfo.py 模块收集有关以下方面的详细信息：

• Python 版本和构建
• 平台信息
• 编译器版本
• 操作系统详细信息
• 内存统计信息
• 安全功能

这些信息对于在不同环境中重现和调试测试失败至关重要。

来源： Lib/test/pythoninfo.py

开发者工具

有多种命令和工具可供开发人员使用

测试结果分析

测试结果以结构化格式报告，便于识别问题

• 通过简短的摘要报告通过的测试
• 失败的测试显示详细的错误信息
• 跳过的测试包括跳过原因
• 报告了详细的资源泄漏信息
• 可以使用 -o/--slowest 获取性能统计信息

结果也可以导出为 JUnit XML 格式，以便与 CI 系统集成。

来源： Lib/test/libregrtest/results.py

使用回归测试框架

以下是运行测试的典型工作流程

1. 运行完整的测试套件以确保一切正常

2. 使用详细输出来运行特定测试

3. 如果测试失败，请提供更多信息重新运行它

4. 如果您怀疑存在内存泄漏，请运行并进行泄漏检测

来源： Lib/test/libregrtest/main.py55-184

CI 开发工作流程

在开发 CPython 的补丁时

1. 对代码库进行更改
2. 使用 python -m test 在本地运行相关测试
3. 提交拉取请求
4. GitHub Actions 将自动运行 CI 管道
5. 修复 CI 系统识别出的任何问题
6. 重复操作，直到所有测试通过

CI 系统将根据您的拉取请求中所更改的文件自动选择要运行的测试。

来源： .github/workflows/build.yml24-43

总结

CPython 的开发工具为测试、调试和维护 Python 解释器及标准库提供了一个全面的环境。回归测试框架、持续集成管道和调试工具协同工作，以确保代码库的质量和稳定性。