用 CliRunner 检查 Click 命令的输入输出与退出行为

命令行程序的接口不仅是函数返回值，还包括参数解析、提示文字、标准输出、标准错误和退出码。Click 提供的 click.testing.CliRunner 能在测试中调用命令对象，将这些行为收集为 Result，让它们成为可以断言的接口约定。

本文依据 Pallets 与 Click 文档贡献者的 Testing Click Applications 翻译整理，覆盖该页全部技术章节。2026 年 10 月 5 日读取时，stable 文档标识为 8.5.x。代码为静态核对后的教学示例，未执行 pytest；涉及版本变化的 API 应与项目实际依赖核对。

先建立最小的输入输出约定

invoke() 接收 Click 命令对象和参数列表，不需要在测试中启动 shell。下面的命令接收一个名字并打印问候语；测试同时检查退出状态和完整文本，包含末尾换行。

# hello.py
import click

@click.command()
@click.argument("name")
def hello(name):
    click.echo(f"Hello {name}!")

# test_hello.py
from click.testing import CliRunner
from hello import hello

def test_hello_world():
    result = CliRunner().invoke(hello, ["Peter"])
    assert result.exit_code == 0
    assert result.output == "Hello Peter!\n"

Result 保存捕获的文本和字节输出、退出码，以及可能出现的异常。不要只用“包含某段文字”代替成功判断：程序先打印成功字样、随后抛出异常，也可能满足文本断言。反过来，只断言退出码为零也无法发现输出格式退化。

测试失败时，应结合 result.exception 和输出定位原因。这里的捕获机制是测试工具，不会替命令隔离网络、权限、数据库或外部副作用；被调用的命令仍然运行真实 Python 代码。

子命令和组级参数按命令行顺序传入

调用命令组时，把子命令名字放进参数列表；属于组的选项放在子命令前。原例的 --debug 由组处理，sync 由子命令处理。

# sync.py
import click

@click.group()
@click.option("--debug/--no-debug", default=False)
def cli(debug):
    click.echo(f"Debug mode is {'on' if debug else 'off'}")

@cli.command()
def sync():
    click.echo("Syncing")

# test_sync.py
from click.testing import CliRunner
from sync import cli

def test_sync():
    result = CliRunner().invoke(cli, ["--debug", "sync"])
    assert result.exit_code == 0
    assert "Debug mode is on" in result.output
    assert "Syncing" in result.output

这种测试同时覆盖组回调和子命令入口。若只直接调用底层业务函数，就无法验证 Click 的参数解析顺序、选项默认值或命令路由。

固定 Context，避免终端差异干扰测试

传给 invoke() 的额外关键字参数会参与初始 Context 的构造。例如 terminal_width=60 可固定帮助文本排版使用的终端宽度，减少不同运行环境造成的换行差异。

import click
from click.testing import CliRunner

@click.group()
def cli():
    pass

@cli.command()
def sync():
    click.echo("Syncing")

def test_context_settings():
    result = CliRunner().invoke(cli, ["sync"], terminal_width=60)
    assert result.exit_code == 0
    assert result.output == "Syncing\n"

与原文的差异：原页这一节的组回调只有 pass，测试却断言输出包含 Debug mode is on。该文字属于上一节的命令，当前命令不会打印它。上面的整理版删除了错误断言，改为核对当前命令的完整输出；这属于静态修正，并非声称测试已通过。

文件测试使用专属目录和绝对路径

测试读写文件的命令时，让每个测试只使用自己的临时目录，并向命令传递绝对路径。pytest 的 tmp_path 会提供独立目录；不使用 pytest 时可采用 tempfile.TemporaryDirectory。这样无需更改整个进程的当前工作目录。

# cat.py
import click

@click.command()
@click.argument("f", type=click.File())
def cat(f):
    click.echo(f.read())

# test_cat.py
from click.testing import CliRunner
from cat import cat

def test_cat(tmp_path):
    hello = tmp_path / "hello.txt"
    hello.write_text("Hello World!", encoding="utf-8")
    result = CliRunner().invoke(cat, [str(hello.resolve())])
    assert result.exit_code == 0
    assert result.output == "Hello World!\n"

与原例相比，这里显式指定写入编码，并用 resolve() 表达绝对路径意图。例子的内容仅含 ASCII，目的是让路径与环境假设更清楚；如果实际命令要处理多语言文本，还需要明确 click.File 的读取编码及错误处理策略。

不要用项目目录、用户主目录或生产数据做这种文件测试，也不要将 tmp_path 理解为安全沙箱：命令仍可能访问临时目录之外的路径。Click 8.5.0 已弃用 CliRunner.isolated_filesystem()，文档计划在 9.0 移除；迁移现有测试时应按实际安装版本确认。

模拟 stdin 与交互提示

input 参数可提供模拟的标准输入。对于 prompt=True 的选项，Click 会模拟用户输入并将可见输入回显到捕获输出中；隐藏输入不会这样回显。

import click
from click.testing import CliRunner

@click.command()
@click.option("--foo", prompt=True)
def prompt(foo):
    click.echo(f"foo={foo}")

def test_prompts():
    result = CliRunner().invoke(prompt, input="wau wau\n")
    assert result.exit_code == 0
    assert result.exception is None
    assert result.output == "Foo: wau wau\nfoo=wau wau\n"

与原文的差异：原页期望字符串在第二行 foo= 前多写了一个空格，但命令的 click.echo 没有打印该空格。此处按代码所表达的输出意图去除空格，并补充退出码断言；仍须在目标 Click 版本上运行后确认实际输出。密码等隐藏输入测试应使用专门的假值，即使提示本身不回显，应用日志或异常也可能泄露输入。

选择 sys 还是 fd 捕获

如果被测程序依赖 faulthandler 等需要真实文件描述符的组件，可在支持的平台上选择 CliRunner(capture="fd")。文档说明该模式的 fileno() 返回保存的描述符，写入描述符 1 和 2 的内容进入捕获临时文件。capture 参数从 8.4.0 才加入；8.3.3 曾改变 fileno() 行为，后来因与 pytest 的文件描述符捕获清理冲突而调整。因此不要将本页构造参数原样用于更早版本。

原文的文件描述符捕获示例如下；这里的 myapp 和预期输出需对应被测应用，未在本文执行：

from click.testing import CliRunner
from myapp import cli

def test_captures_everything():
    runner = CliRunner(capture="fd")
    result = runner.invoke(cli)
    # result.stdout 同时包含 Python 级与文件描述符级输出。
    assert "expected output" in result.stdout

并发隔离以进程为单位

CliRunner.invoke() 会临时替换 sys.stdin、sys.stdout、sys.stderr 等解释器级全局状态。同一个解释器内并发调用会相互覆盖，所以它不具备线程安全性。独立临时目录只能隔离文件，不能使标准流替换变成线程安全。

需要并行执行时，原文推荐 pytest-xdist 的独立进程工作者，例如 pytest --numprocesses=auto；项目必须先具备对应测试依赖，并根据资源情况限制工作者数量。Click 自身也结合 pytest-randomly 和 pytest-xdist 检查顺序相关问题。测试环境仍应使用假的凭据、隔离的外部服务以及受控的文件路径。

本文未执行命令或测试，静态审查未发现所列示例包含 shell 拼接、真实硬编码密钥或网络请求；这不能证明被测应用无漏洞。对自己的 CLI，应另外验证失败退出、非法参数、空输入、权限错误和外部调用的边界。

来源与许可

原作者及维护者：Pallets 与 Click 文档贡献者。原文：Testing Click Applications；许可：BSD-3-Clause。中文翻译整理、静态勘误和技术示意图：未完纪。以下保留相关许可声明：

Copyright 2014 Pallets

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.