How to Turn a Postman Collection into a Maintainable pytest Suite

如何将 Postman 集合转换为可维护的 pytest 测试套件

2026年7月9日

/

#pytest

米哈伊尔·戈利科夫

Postman 集合是探索 API 的绝佳工具。但将其作为测试存储的位置却是个糟糕的选择。

大多数团队都是通过缓慢的方式意识到这一点的。某人导出集合，将请求转换为测试代码一次，然后继续前进。六个月后测试失败，没人信任它们，它们在流水线中被跳过。转换本身从来不是困难的部分。保持测试套件的活力才是真正的挑战。

本教程将带你从 Postman 集合转换为一个即使下个季度仍能通过的 pytest 测试套件。首先我们将分析为什么转换后的测试会失效，然后探讨四个保持测试活力的原则。示例保持简洁，以便你今天就能在自己的集合上尝试。

目录

• 转换前的准备
• 为什么转换后的测试会失效
• 原则 1：将环境配置与测试分离
• 原则 2：验证接口契约而不仅仅是状态码
• 原则 3：让每个测试独立运行
• 原则 4：从第一天起将测试套件集成到持续集成中
• 让工具处理机械性工作
• 总结

转换前的准备

要跟随本教程，你需要：

• 安装 Python 3.10 或更高版本，并安装 pytest 和 httpx（通过 pip install pytest httpx 安装）。
• 想要转换的 Postman 集合及其环境（基础 URL 和令牌）。
• 基础的 pytest 知识：了解 fixture 的工作原理以及如何从命令行运行 pytest。
• 如果想尝试持续集成步骤，需要一个 GitHub 仓库。你可以跳过这部分，但仍可继续后续内容。

该图示展示了工作的两个部分。左侧，Postman 集合（其请求和环境）被转换为生成的 pytest 测试套件，这是初稿。这个转换是简单的步骤。

真正的工作是右侧的可维护性层，它将初稿转换为可信赖的测试套件：环境配置通过 fixture 管理而非硬编码，测试验证响应契约而不仅仅是 200 状态码，每个测试独立运行，测试套件在每次提交时都会在持续集成中运行。

为什么转换后的测试会失效

当你一对一地转换 Postman 请求时，你会继承四个在第一天看似合理但到第三十天就会造成问题的习惯：

• 基础 URL 和令牌被硬编码到每个测试中，因此从预发布环境切换到生产环境意味着需要查找替换。
• 测试必须按固定顺序运行，因为第二个请求依赖于第一个请求设置的值，单个失败会导致连锁反应。
• 唯一的断言是状态码为 200，即使响应体错误也能通过。
• 设置代码被复制到每个测试中，因此修改认证方式意味着需要编辑二十个文件。

所有这些都是维护问题，合起来就是测试套件被弃用的原因。以下是避免这些问题的方法。

原则 1：将环境配置与测试分离

Postman 集合通过单独文件存储环境配置：基础 URL、令牌和其他变量。在 pytest 中也应采用相同方式。在 fixture 中一次性读取这些值，让每个测试通过依赖注入获取它们。

# conftest.py
import os

import httpx
import pytest

@pytest.fixture(scope="session")
def base_url():
    return os.environ["API_BASE_URL"]

@pytest.fixture(scope="session")
def auth_headers():
    return {"Authorization": f"Bearer {os.environ['API_TOKEN']}"}

@pytest.fixture()
def http():
    with httpx.Client(timeout=10) as client:
        yield client

现在测试用例中不再直接提及 URL 或 token：

def test_get_user(base_url, auth_headers, http):
    response = http.get(f"{base_url}/users/1", headers=auth_headers)
    assert response.status_code == 200

从预发布环境切换到生产环境只需修改一个环境变量，而无需在整个测试套件中搜索替换。

原则2：断言合同，而不仅仅是状态码

200 状态码仅表示服务器已响应，但无法证明响应内容正确。API 出现缺陷最常见的原因就是所有测试仅检查状态码。应断言响应数据结构和调用方依赖的字段。

def test_user_shape(base_url, auth_headers, http):
    response = http.get(f"{base_url}/users/1", headers=auth_headers)

    assert response.status_code == 200
    body = response.json()
    assert set(body) >= {"id", "email", "created_at"}
    assert isinstance(body["id"], int)
    assert "@" in body["email"]

你不需要为每个接口定义严格的 schema。即使只对关键字段进行少量校验，也能发现状态码检查会遗漏的一整类回归问题。

原则3：让每个测试独立运行

在 Postman 中，一个请求为后续请求提供数据是常见做法。但在测试套件中，这种耦合会带来隐患：测试顺序变更、单独运行某个测试或丢失第一个请求时，后续测试都会失败。

为每个测试提供其所需的初始状态。如果测试需要用户，就让它自己创建用户。

def test_delete_user(base_url, auth_headers, http):
    created = http.post(
        f"{base_url}/users",
        headers=auth_headers,
        json={"email": "temp@example.com"},
    )
    user_id = created.json()["id"]

    response = http.delete(f"{base_url}/users/{user_id}", headers=auth_headers)
    assert response.status_code == 204

独立的测试可以按任意顺序运行且支持并行执行，失败时能明确指向单一问题，而非一连串依赖关系。

原则4：第一天就将测试套件接入持续集成

仅在本地运行的测试套件一旦停止关注就会过时。在编写第二个测试前就将其接入流水线，确保每次提交都必须保持测试通过。

# .github/workflows/tests.yml
name: API tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pytest -v
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          API_TOKEN: ${{ secrets.API_TOKEN }}

一旦完成配置，测试失败会成为 Pull Request 中的讨论话题，而非生产环境中的突发故障。

让工具处理机械性工作

以上所有内容都值得你亲自关注。将每个请求转换为测试用例初稿属于机械性工作，这类工作值得自动化处理。

我维护了一个开源工具 postman2pytest ，专为这个步骤设计。它能读取 Postman 集合并生成可运行的 pytest 文件，让你从自动生成的测试用例出发，专注于可维护性层而非重复的模板代码。当集合变更时，只需重新生成而非手动修补差异。

你可以在以下地址找到它：https://github.com/golikovichev/postman2pytest

总结

将 Postman 集合转换为测试用例很简单。让这些测试保持可信才是真正的技能，这取决于几个习惯：将环境变量与测试分离，断言接口契约而不仅仅是状态码，确保每个测试独立，从一开始就将所有内容纳入持续集成流程。

做到这些，你本周生成的测试套件，明年依然可以依赖。

英国霍夫市的 QA 工程师。为测试人员构建开源 Python 工具：postman2pytest、secure-log2test、pytest-conversational。

如果这篇文章对你有帮助，请分享它。

免费学习编程。freeCodeCamp 的开源课程已帮助超过 40,000 人成为开发者。立即开始

ADVERTISEMENT