# 流水线变绿，不等于客户环境里真的跑起来了

> 三个 pytest 测试加一个退出码，就能决定是否回滚，前提是退出码 5 不能漏过关口。

原文: https://fdetimes.net/zh/guides/post-deployment-smoke-tests-pytest/

在 ArgoCD 中，可以把冒烟测试挂到 PostSync hook 上，部署一完成就自动运行。有一个细节常被忽略：测试失败时，同步会被标记为失败，但新资源仍然留在集群里。工具只负责通知你，是否回滚仍要你自己决定。

对前线部署工程师（FDE）来说，这是日常工作。你把产品安装到客户的基础设施中，用的是客户自己的网络、数据库和登录系统，流水线显示绿色。Google SRE Workbook 明确指出，有些发布故障只有在真实流量开始进入服务后才会暴露。客户环境恰恰就是这些故障出现的地方。

本文介绍如何用 pytest 编写一套冒烟测试。这套测试只需一个命令行选项就能在任意客户环境中运行，并返回一个退出码，部署脚本据此决定保留版本还是回滚。

## 要做什么，需要准备什么

举一个假设的例子：你刚把一个文档搜索服务部署到客户的基础设施中。该服务有三个端点，同样是为说明而虚构的：`/health` 表示进程已启动，`/ready` 只在能连上数据库时返回 200，`/api/search` 需要令牌。实际工作中，请换成你的产品对外提供的端点。

你需要 Python 3、pytest、待检查环境的 URL，以及一个保存在环境变量中的测试令牌。下面的代码使用标准库 `urllib`，无需额外安装任何东西。这是一个精简版本，足以掌握方法，但不是可以直接上生产环境的成品。

```text
smoke/
  pytest.ini
  conftest.py
  test_smoke.py
```

## 第 1 步：只检查会让整个系统瘫痪的部分

冒烟测试是对核心功能是否可用的快速检查，它能尽早告诉你部署的基础部分是否在正常运行。范围只限于关键路径，例如启动、数据库连接和认证。边界情况和单个小功能不属于这里。

整套测试的时间预算应控制在 2 分钟以内。上面的例子有三个测试，每个请求的超时时间为 5 秒。最坏情况是四个请求都挂起直到超时，大约 20 秒，仍远在限制之内。如果测试集开始膨胀到好几分钟，说明你把回归测试放错了地方。

## 第 2 步：注册标记，让 pytest 帮你发现拼写错误

pytest 建议在配置文件中注册自定义标记，比如 `smoke`：

```ini
# pytest.ini
[pytest]
markers =
    smoke: 部署后对关键路径的快速检查
```

验证：运行 `pytest --markers`，在列表中找到 `smoke` 这一行。运行测试时，始终加上 `--strict-markers`。开启这个参数后，用 `@pytest.mark...` 装饰器打上的任何未注册标记都会报错。拼错的 `@pytest.mark.smok` 会被立即拦下，而不是悄无声息地让这个测试永远不被选中。

## 第 3 步：一套测试适配所有客户环境

不要把 URL 写死。pytest 文档介绍了如何在 `conftest.py` 中通过 `pytest_addoption` 添加命令行选项，再通过 fixture 把值传给测试：

```python
# conftest.py
import pytest

def pytest_addoption(parser):
    parser.addoption("--target-url", action="store", default=None,
                     help="待检查环境的基础 URL")

@pytest.fixture
def target_url(request):
    url = request.config.getoption("--target-url")
    if not url:
        pytest.fail("缺少 --target-url")
    return url.rstrip("/")
```

验证：运行 `pytest --help`，在自定义选项中找到 `--target-url`。

## 第 4 步：为三条关键路径写三个测试

```python
# test_smoke.py
import os
import urllib.error
import urllib.request

import pytest

TIMEOUT = 5  # 秒

def get_status(url, token=None):
    req = urllib.request.Request(url)
    if token:
        req.add_header("Authorization", f"Bearer {token}")  # 假定的认证方式
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT) as resp:
            return resp.status
    except urllib.error.HTTPError as err:
        return err.code

@pytest.mark.smoke
def test_service_started(target_url):
    assert get_status(f"{target_url}/health") == 200

@pytest.mark.smoke
def test_database_reachable(target_url):
    assert get_status(f"{target_url}/ready") == 200

@pytest.mark.smoke
def test_auth_rejects_then_accepts(target_url):
    assert get_status(f"{target_url}/api/search?q=test") == 401
    token = os.environ["SMOKE_TOKEN"]
    assert get_status(f"{target_url}/api/search?q=test", token) == 200
```

第三个测试同时检查两个方向。不带令牌也能访问是安全漏洞，而不是成功。如果测试只检查“带令牌时返回 200”，那么即使认证层被彻底关闭，它照样会通过。

## 第 5 步：用退出码决定保留还是回滚

部署脚本需要读取的是 pytest 的退出码。0 表示所有测试通过；1 表示测试已收集并运行，但有失败；5 表示没有收集到任何测试，这正是陷阱所在。

```bash
pytest -m smoke --strict-markers --target-url "$TARGET_URL" -q
rc=$?
if [ "$rc" -ne 0 ]; then
  echo "冒烟测试失败（退出码 $rc），请考虑回滚"
  exit 1
fi
```

假设你在命令行里把 `-m smoek` 打错了。`--strict-markers` 只能发现装饰器中的拼写错误，管不到 `-m` 表达式，于是 pytest 一个测试也没选中，返回退出码 5。如果脚本只检查 `rc -eq 1`，部署就会在一个测试都没跑的情况下通过关口。所以正确的条件是 `-ne 0`。

**要点:** 一个测试都没运行的冒烟测试，必须按失败处理，而不是成功。

## 冒烟测试骗过你的三种方式

第一种就是上面说的退出码 5 陷阱。第二种是任由测试集膨胀到要跑十分钟：人们赶时间时就会跳过它，而那恰恰是最需要它的时候。

冒烟测试的价值在于快：测试一失败，你立刻知道出了问题，可以在用户察觉之前回滚。

第三种是以为系统会替你处理。正如开头 ArgoCD 的例子所示，PostSync hook 失败并不会移除新资源。在按下部署之前，先写好回滚流程，至少要指定一位有权做决定的负责人。

## 这项技能在客户现场是什么样子

Google SRE 把金丝雀发布定义为对变更进行部分的、有时限的部署，并同时对该变更进行评估。冒烟测试是这一评估步骤的简化版，在你到客户现场的第一周、还没有流量切分和监控面板时，它往往是唯一可行的方案。

第一周要做的第一件事，是请客户提供一个专用于冒烟测试的测试账号，这样 `SMOKE_TOKEN` 就不必借用真人的令牌。

这套测试也是沟通工具。客户问“装好了吗？”，你可以用三行绿色结果和一个退出码来回答，而不是“应该没问题”。

在面试或简历中，要讲具体：冒烟测试检查哪些路径，在流水线的哪个阶段运行，发现过哪些故障。这样的描述能表明，你能验证产品确实在运行，而不只是部署上去了。

流水线变绿，说明代码已经交付。产品是否真的在客户的基础设施上跑起来，只有那三个 pytest 测试能回答。

**本周动手试试:**

- 建立一个 smoke/ 目录，包含 pytest.ini、conftest.py 和 test_smoke.py，并对你手头某个项目的 URL 运行一遍。
- 故意拼错标记（-m smoek），看看 pytest 返回什么退出码，然后修改部署脚本，拦住这种情况。
- 为简历写一句话，描述你搭建过的部署后冒烟测试：检查什么、在哪里运行、发现过哪些故障。

## 信源

- [How to Implement Smoke Testing Strategies](https://oneuptime.com/blog/post/2026-01-25-smoke-testing-strategies/view)

- [How to mark test functions with attributes](https://docs.pytest.org/en/stable/how-to/mark.html)

- [Pass different values to a test function, depending on command line options](https://docs.pytest.org/en/stable/example/simple.html)

- [Exit codes](https://docs.pytest.org/en/stable/reference/exit-codes.html)

- [Chapter 16 - Canarying Releases](https://sre.google/workbook/canarying-releases/)

- [How to Run Smoke Tests After Deployment with PostSync Hooks in ArgoCD](https://oneuptime.com/blog/post/2026-02-26-argocd-postsync-smoke-tests/view)
