pytester是pytest内置的测试工具插件，用于安全、隔离地测试命令行工具，随pytest安装无需pip install，通过pytest_plugins=["pytester"]启用，支持临时环境、输出捕获与退出码验证。
直接用 pytest 跑命令行工具的测试是可行的，但手动构造 sys.argv、捕获 stdout、处理异常退出码、模拟用户输入……写多了容易出错且难以维护。真正靠谱的做法是用 pytester —— 它不是第三方包，而是 pytest 内置的测试工具插件（属于 pytest 自身的测试套件），但**可被普通项目安全复用**，专为“测试命令行入口”而生。
pytester 是什么，为什么不能 pip install？
pytester 是 pytest 源码中用于自测其 CLI 行为的 fixture，随 pytest 一起安装，无需额外安装。它本质是一个临时项目环境生成器：自动创建隔离的临时目录、写入测试用 Python 模块、调用 pytest.main() 或任意命令行入口，并捕获完整输出与退出码。
- 它不依赖真实文件系统污染（比如不会真的在你项目里写
test_cli.py） - 所有测试都在内存或临时路径完成，天然支持并发运行
- 返回对象含
.stdout.str()、.stderr.str()、.retcode，比手动subprocess.run(..., capture_output=True)更贴近真实 CLI 执行上下文
如何在普通项目中启用 pytester fixture
只需在测试文件顶部加一行声明即可激活：
pytest_plugins = ["pytester"]
然后在测试函数签名中声明 pytester 参数，它就会自动注入。注意：不能在 conftest.py 中全局启用，否则可能干扰其他 fixture 作用域；必须放在具体测试模块里。
立即学习“Python免费学习笔记（深入）”；
- 如果你看到
fixture 'pytester' not found，大概率是忘了这行pytest_plugins - 如果用了
pytest-xdist并行执行，pytester仍安全 —— 每个 worker 拥有独立临时环境 - 它默认使用当前 Python 解释器，不支持跨解释器测试（如强制用 py3.9 测试 py3.11 行为）
用 pytester 测试 click/tap/command-line 入口的典型模式
假设你的 CLI 工具主入口在 jformat.cli:main，且已打包为可执行命令 jformat。下面是最简可行测试：
def test_cli_help(pytester):
# 创建一个最小可用的 CLI 模块（会写入临时目录）
pytester.makepyfile("""
from jformat.cli import main
if __name__ == "__main__":
main()
""")
# 模拟执行 `python cli_module.py --help`
result = pytester.runpython("cli_module.py", "--help")
assert result.retcode == 0
assert "usage:" in result.stdout.str()
-
makepyfile()写的是真实 .py 文件，不是字符串 eval —— 所以能正确触发 import 和 entry point 初始化逻辑 -
runpython()等价于subprocess.run([sys.executable, ...])，但自动处理路径、编码、换行符归一化 - 若要测安装后的命令（如
jformat --version），改用result = pytester.run("jformat", "--version")，前提是该命令在当前 shell PATH 可见
常见陷阱和绕过方式
实际用时最容易卡在三类问题上：
-
模块导入失败：临时目录里没有你的包。解决方法是调用
pytester.syspathinsert()把项目根目录加进sys.path，或用pytester.makepyprojecttoml()构建一个带[build-system]的临时 pyproject.toml 并pip install -e .（较重，慎用） -
stdin 阻塞：CLI 等待用户输入时测试挂起。用
result = pytester.run(..., stdin="yes\n")注入输入流，注意换行符必须显式写出 -
颜色/进度条干扰断言：ANSI 控制字符让
stdout.str()难读。在 CLI 调用参数中加--no-color或环境变量NO_COLOR=1（如果工具支持），否则得用正则清洗输出
最复杂的 CLI 场景（如子命令嵌套、配置文件加载、多进程 spawn）往往需要组合 makeini()、makefile("config.toml", "...") 和 tmp_path fixture 手动构造上下文 —— 这些不是 pytester 的短板，而是命令行工具本身复杂性的自然映射。
