测试调用 X API 的代码而不烧配额

15 min readSocialAPI 工程团队

测试调用 X API 的代码而不烧配额

测试调外部 API 的代码有两种糟糕做法。一种是每个测试都真的去调——慢、烧配额、而且有人断网就挂。另一种是 mock 得太彻底,于是测试全绿而集成是坏的。

出路很具体:★真实响应录一次、永远重放,然后只保留一个会跟线上 API 说话的测试。★ 这样你得到的是跑得快、而且不会在你不知情的情况下和现实脱节的测试。

有个免费 demo 端点不需要 key,很适合用来录第一批 fixture。


从真实响应录 fixture

★手写的 fixture 编码的是你的假设,而你的假设恰恰是测试本该检验的东西。★ 改成录真的:

# tools/record_fixtures.py —— 刻意运行它, 不要放进 CI
import json, pathlib, requests

OUT = pathlib.Path("tests/fixtures")
OUT.mkdir(parents=True, exist_ok=True)

CASES = {
    "user_info_ok":   ("/v1/demo/user/info", {"username": "elonmusk"}),
    "user_info_401":  ("/v1/user/info",      {"username": "elonmusk"}),  # 不带 key
}

for name, (path, params) in CASES.items():
    r = requests.get(f"https://api.socialapi.tech{path}", params=params, timeout=30)
    (OUT / f"{name}.json").write_text(json.dumps({
        "status_code": r.status_code,
        "body": r.json(),
    }, indent=2), encoding="utf-8")
    print(f"{name}: {r.status_code}")

★状态码要和 body 一起录。★ 只有 body 的 fixture 测不了你的错误处理,而那恰恰是最容易写错的部分。

★录制器不要进 CI。★ 它是API 变了的时候你去运行的工具,不是测试。如果它自动跑,你的 fixture 就会悄悄跟着 API 走、不再是回归检查。

提交前脱敏。 把录到的东西里的 key 换成占位符,提交前扫一遍——录下来的 HTTP 是 key 进仓库的常见途径。


在测试里重放

import json, pathlib, pytest, requests

FIX = pathlib.Path(__file__).parent / "fixtures"

def load(name):
    return json.loads((FIX / f"{name}.json").read_text(encoding="utf-8"))

class FakeResponse:
    def __init__(self, status_code, body):
        self.status_code, self._body = status_code, body
        self.headers = {}
    def json(self):
        return self._body
    def raise_for_status(self):
        if self.status_code >= 400:
            raise requests.HTTPError(f"{self.status_code}")

@pytest.fixture
def fake_api(monkeypatch):
    """把 requests.get 打成返回指定 fixture。"""
    def use(name):
        f = load(name)
        monkeypatch.setattr(
            requests, "get",
            lambda *a, **k: FakeResponse(f["status_code"], f["body"]),
        )
    return use

def test_parses_follower_count(fake_api):
    fake_api("user_info_ok")
    user = my_client.get_user("elonmusk")
    assert isinstance(user["followers_count"], int)
    assert isinstance(user["id"], str)          # ← ID 必须保持字符串

★最后那条断言值得单独算一个测试。★ 推文和用户 ID 是超过浮点安全整数范围的 19 位值,所以任何让它们经过数字类型的改动都会静默损坏末几位。断言类型能在 CI 里抓到它,而不是在你的数据库里——道理在为什么 ID 该放 TEXT 列。


测失败路径,因为 bug 在那儿

★几乎所有人都只测成功路径就停了。而 bug 活在其他分支里:★

import pytest

@pytest.mark.parametrize("status,should_retry", [
    (429, True),    # 被限流 —— 不计费, 该重试
    (500, True),
    (502, True),
    (402, False),   # 额度用尽 —— 重试是死循环
    (401, False),
    (404, False),
    (400, False),
])
def test_retry_policy(status, should_retry):
    assert my_client.should_retry(status, attempt=0) is should_retry

def test_402_raises_distinctly(fake_api):
    """402 不能被通用错误 handler 吞掉。"""
    fake_api("payment_required")
    with pytest.raises(OutOfCredits):
        my_client.get_user("someone")

def test_timeout_does_not_advance_cursor(monkeypatch):
    """最重要的那个: 歧义性失败不能丢页。"""
    monkeypatch.setattr(requests, "get",
                        lambda *a, **k: (_ for _ in ()).throw(requests.Timeout()))
    state = {"cursor": "abc123"}
    my_collector.fetch_page(state)
    assert state["cursor"] == "abc123"          # 没变

★第三个测试是最值回票价的那个。★ 超时意味着你不知道那一页到底送达没有,所以推进游标会静默跳过数据——而被跳过的那一页此后永远不可见。它在 code review 里很难抓,在测试里却很容易抓。

把重试策略参数化,意味着往表里加一个状态码就强迫你对它做决定,而不是让它掉进一个没人考虑过的默认分支。完整策略在哪些错误该重试。


测翻页要用两页,不是一页

这只适用于真正会翻页的端点——粉丝、关注、转推者、列表成员。时间线一次就返回 limit 以内的全部,没什么可走的。对会翻页的那些,★单页 fixture 在翻页完全坏掉的情况下也会通过。★ 你至少需要两页,而且第二页必须没有游标:

def test_pagination_stops_and_collects_all(monkeypatch):
    pages = [
        {"status_code": 200, "body": {"data": [{"id": "2"}, {"id": "1"}],
                                      "meta": {"next_cursor": "c1"}}},
        {"status_code": 200, "body": {"data": [{"id": "0"}],
                                      "meta": {"next_cursor": None}}},
    ]
    calls = []
    def fake_get(url, params=None, **k):
        calls.append((params or {}).get("cursor"))
        p = pages[len(calls) - 1]
        return FakeResponse(p["status_code"], p["body"])
    monkeypatch.setattr(requests, "get", fake_get)

    rows = my_client.paginate("/v1/user/followers", {"username": "x"})
    assert len(rows) == 3                       # 没丢第二页
    assert calls == [None, "c1"]                # 把游标传回去了
    assert len({r["id"] for r in rows}) == 3    # 没有重复

★对 calls 做断言才让它成为真正的测试。★ 只检查行数的话,即使你忽略了游标、把第一页取了两遍也会通过。 验证游标被传回去了,才是证明翻页真的在工作的东西。


只保留一个实时测试

★mock 没法告诉你 API 变了。一次真实调用、跑在常规测试套件之外,可以。★

import os, pytest, requests

@pytest.mark.live
def test_live_contract():
    """抓上游结构变化。不属于默认运行。"""
    r = requests.get("https://api.socialapi.tech/v1/demo/user/info",
                     params={"username": "elonmusk"}, timeout=30)
    assert r.status_code == 200
    d = r.json()["data"]

    for field in ("id", "username", "followers_count", "created_at"):
        assert field in d, f"missing {field}"
    assert isinstance(d["id"], str)
    assert isinstance(d["followers_count"], int)
# pytest.ini —— 默认排除, 按计划运行
[pytest]
markers = live: 打真实 API; 每夜跑, 不是每次提交都跑
addopts = -m "not live"

★每夜跑,不要每次提交都跑。★ 上游变化该叫醒一个定时任务,而不是弄坏某个正在改无关错字的人的构建。而且因为 demo 端点不需要 key,这个测试在 CI 里压根不需要 secret。

★断言字段存在和类型,不要断言值。★ followers_count == 241431332 明天就会因为一个不是 bug 的原因失败。你真正在意的契约是这个字段存在、而且是整数。


不要测什么

值得说,因为过度测试集成本身也是个坑:

  • 不要测服务商的正确性。 粉丝数准不准不是你测试的职责。
  • 不要断言精确计数或具体文本。 它们每小时都在变。
  • 不要测 requests 能不能用。 mock 掉 HTTP 库来验证你调用了它,这是同义反复。
  • ★不要对整个响应做快照。★ 上游多一个字段不该让你的测试套件失败;只断言你用到的字段。

★最后这条比听起来更要紧。★ 全响应快照在每一次上游的新增改动上都会失败,于是人们习惯了不读 diff 就重新录制——然后某次真正的破坏性变更也被一起重新录进去了。


我们的 demo 端点不需要 key 就返回稳定的真实响应,所以它能当 CI 契约检查用。用 Google 一键注册送 $0.20 额度、不用信用卡,如果你还想要鉴权端点的 fixture。


常见问题

调 X API 的代码怎么测? 真实响应录一次当 fixture、在单元测试里重放,再按计划保留一个实时测试来抓上游变化。

测试里该调真实 API 吗? 一次,在一个测试里,跑在默认运行之外。 每个测试都打实时慢、烧配额、而且网络一抖就挂。

为什么要录 fixture 而不是手写? 因为手写的 fixture 编码的是你的假设,而你的假设正是测试本该检验的东西。

fixture 录制器该进 CI 吗? 不该。 自动跑的话你的 fixture 会悄悄跟着 API 走、不再是回归检查。API 变了的时候刻意去跑它。

fixture 里该放什么? 至少是状态码加 body。 只有 body 的 fixture没法演练错误处理,而那是大多数 bug 所在。

怎么避免把 API key 提交到 fixture 里? 尽量从不需要 key 的 demo 端点录、把 key 换成占位符、提交前扫一遍 diff。录下来的 HTTP 是常见的泄露路径。

最该先写的那个测试是什么? ★超时不会推进游标。★ 跳过一页的歧义性失败此后不可见、而且在 review 里几乎抓不到。

为什么要测 ID 是字符串? 因为它们是超过浮点安全整数上限的 19 位值。 一次把它们经过数字类型的重构会无声损坏它们,而一条类型断言能在 CI 里抓住。

重试逻辑怎么测? 按状态码参数化、带上预期的重试决定。 这样往表里加一个码就强迫你对它做决定,而不是让它撞上一个没考虑过的默认值。

402 该抛独立异常吗? 该,而且要测它真的抛了。 它需要人介入,所以绝不能被那个「记日志然后继续」的 handler 捕获。

测翻页需要几页? 至少两页,第二页没有游标。 单页 fixture 在翻页完全坏掉时也会通过。

翻页测试该断言什么? ★第二次调用时游标被传回去了。★ 只看行数在你把第一页取两遍的情况下也会通过。

pytest 里怎么 mock requests? monkeypatch.setattr(requests, "get", ...) 配一个小的假响应类。responses 和 respx 也挺好;原理是一样的。

VCR 那种录制方式值得用吗? 好用,而且把录制自动化了。 注意点和任何录制一样:清掉凭据,并且刻意地重新录制,而不是测试一失败就录。

为什么给实时测试打标记而不是删掉它? ★因为 mock 检测不到 API 变了。 一个定时的实时测试,是你和「fixture 悄悄过期」之间唯一的东西。★

实时测试该断言什么? 字段存在和类型,绝不断言值。 断言一个具体的粉丝数明天就会因为一个不是 bug 的原因失败。

实时测试该多久跑一次? 每夜通常是对的。 每次提交都跑意味着上游变化会弄坏下一个推代码的人的构建。

CI 里没有 secret 能跑实时测试吗? 能,如果服务商有不需要 key 的 demo 端点。 这让契约检查在 fork 和 PR 上也能跑。

该对整个响应做快照吗? 不该。 上游的新增改动会让你的套件失败,而人们会学会不读 diff 就重新录制——最终把一次真正的破坏也录进去。

怎么在不被限流的情况下测限流处理? 返回一个 429 fixture。 你测的是自己对状态码的反应,这不需要真的去撞一个限流。

这件事需要 staging 环境吗? 通常不需要。 对只读集成来说,fixture 加一个实时契约测试就够了。

流式和 webhook 代码怎么测? webhook:往你的 handler POST 一个构造好的 payload,断言验签——包括一个故意错误的签名,那套签名机制就是你在演练的东西。流:给你的解析器喂一段录下来的消息序列。

该对 demo 端点测还是付费端点测? 契约检查和第一批 fixture 用 demo,因为免费且稳定。demo 覆盖不到的结构用付费端点录 fixture。

一个 API 客户端该有多少测试? 够覆盖你错误处理的每个分支,加上翻页。 通常是十到十五个,比五十个成功路径的变体更有价值。

这里最常见的测试错误是什么? ★只测成功路径。 处理 429、402、404 和超时的那些集成代码,既是测得最少的、也是最可能写错的。★


录一次、永远重放、再按计划留一个实时测试——这个组合才是阻止 fixture 悄悄过期的东西。用 Google 注册送 $0.20 额度、不绑卡。