postman2pytest: как превратить Postman-коллекцию в pytest-набор за одну команду / Хабр

Вот есть Postman-коллекция из 40 запросов. Разложена по папкам, и с тестовыми скриптами, которые проверяют статус-коды. Вы потратили на неё время, она хороша.

И ещё у вас есть CI-пайплайн, который про Postman никогда не слышал и слышать не собирается.

Эти две вещи мирно сосуществовали месяцами, потому что никто не хочет быть тем человеком, который вручную переписывает 40 запросов в pytest-функции. Newman, конечно, есть, но Newman гоняет тесты, а не генерирует код, который можно прочитать, отредактировать и нормально положить в систему контроля версий.

Получается, коллекция документирует API. CI тестирует API. Они описывают одну и ту же систему и при этом никогда не встречались.

Я написал postman2pytest, чтобы их познакомить.

(мы) Одна команда

pip install postman2pytest

postman2pytest \
  --collection my_api.postman_collection.json \
  --out tests/test_api.py

BASE_URL=https://staging.example.com pytest tests/test_api.py -v

На выходе — обычный Python, который читается, редактируется и кладётся в git. Никакого framework lock-in. Никакой runtime-обёртки. Просто сгенерированный Python-код.

Как выглядит результат

Допустим, в Postman-коллекции есть папка Users с запросом POST /api/v1/users и тестовым скриптом, проверяющим статус 201:

def test_users_post_create_user():
    """POST ENV_base_url/api/v1/users (users)"""
    url = f"{BASE_URL}/api/v1/users"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ.get('token', '')}",
    }
    body = json.loads('{"name": "John Doe", "email": "john@example.com"}')
    response = requests.post(url, headers=headers, json=body)
    assert response.status_code == 201, (
        f"Expected 201, got {response.status_code}: {response.text[:200]}"
    )

Несколько моментов, на которые стоит обратить внимание.

Имена папок попадают в имена функций. Create user внутри Users превращается в test_users_post_create_user. Если у вас 40 запросов и три папки с названием List, потом скажете спасибо за это.

Переменные Postman становятся переменными окружения. {{base_url}} превращается в env-переменную BASE_URL. {{token}} в Authorization-заголовке становится os.environ.get('token', '') в f-строке. Сгенерированные тесты по умолчанию знают, в каком окружении бегут.

Статус-коды берутся из ваших существующих тестовых скриптов. Если в Postman вы написали pm.response.to.have.status(201), сгенерированный тест ожидает ровно 201. Никаких дефолтов в 200.

Отключённые заголовки остаются отключёнными. Вы выключили их в Postman не просто так.

Архитектура

Два этапа, чисто разделённые.

Parse (core/parser.py): читает JSON Postman-коллекции и строит плоский список объектов ParsedRequest, валидированных через Pydantic v2. Вложенные папки рекурсивно разворачиваются. Битые элементы коллекции пропускаются с warning-ом, остальная часть всё равно генерируется.

class ParsedRequest(BaseModel):
    name: str
    method: str
    url: str
    headers: dict[str, str]
    body: str | None
    expected_status: int
    folder: str | None

Generate (core/generator.py): берёт плоский список и рендерит Jinja2-шаблон. Самая хитрая часть — подстановка переменных. {{base_url}}/api/v1/users должен превратиться в f"{BASE_URL}/api/v1/users" на Python, а Bearer {{token}} в заголовке — в f"Bearer {os.environ.get('token', '')}". Этим занимаются два кастомных Jinja2-фильтра: strip_base_url для URL и render_header_value для значений заголовков.

Разделение сделано осознанно. Парсер можно использовать самостоятельно, чтобы генерировать другой формат вывода. Шаблон — единственное место, которое знает, как выглядит pytest.

Что пока не делает

Postman environments (отдельный файл .postman_environment.json)
OAuth 2.0 flows
Pre-request скрипты
Проверки тела ответа (response body assertions)

Всё это решаемо. v1.0 достаточно маленький, чтобы ему можно было доверять. Лучше используйте его и расскажите, чего не хватает, чем я буду обещать функции, которые ещё не написал.

36 тестов, потому что собственный dogfood важен

pip install postman2pytest pytest
pytest tests/ -v  # 36 passed

CI прогоняется на Python 3.10, 3.11 и 3.12 через GitHub Actions.

Почему не просто Newman?

Newman гоняет ваши Postman-тесты. Это полезно. Но он не генерирует код, он генерирует отчёт. Когда тест упал в CI, Newman говорит, что он упал. pytest говорит, что он упал, показывает diff, позволяет добавить fixture, распараметризовать кейс, интегрироваться с уже существующей тестовой инфраструктурой.

Если ваша команда уже использует pytest для unit-тестов, integration-тестов и контракт-тестов, наличие API smoke-тестов в том же раннере означает одну команду, один отчёт и одну интеграцию в существующий CI-step.

Откуда оно вообще взялось

Я QA-инженер. На бэкенд-команде, где я sole tester среди трёх PHP-разработчиков, исторически жили две параллельные истории:

Postman-коллекция с ~40 запросами. Использовалась для ручного API-тестирования и обмена примерами между разработкой и QA.
pytest-набор тестов для CI. Гонялся при каждом merge.

Каждое изменение API требовало апдейта обоих. Поначалу терпимо. Через год — раздражение. Через два — реальная статья расходов времени.

Я искал готовый инструмент. Нашёл Newman (нет, это другое), нашёл генераторы тестов на основе LLM (медленные, недетерминированные, лезут в production-данные). Не нашёл то, что хотел: одношотовый детерминированный конвертер, который выдаёт читаемый pytest-код.

Поэтому написал.

Как это устроено внутри (если интересно глубже)

Архитектура из двух стадий — это не теоретическая чистота, это практическое решение.

Parser работает с одной задачей: достать структуру коллекции в predictable формат. Pydantic-модели делают входные данные валидируемыми. Если Postman завтра поменяет схему v2.1, я меняю парсер, шаблон не трогаю.

Generator работает с другой задачей: взять структуру и нарендерить pytest. Jinja2 — потому что Jinja2. Шаблон сам по себе читаемый, можно открыть и посмотреть, что именно генерируется.

Между этими двумя слоями стоят кастомные фильтры — мост, который переводит Postman-семантику в Python-семантику. Эти фильтры — единственное место, где живёт «магия» инструмента. Всё остальное — обычный Python.

@register_filter
def strip_base_url(url: str, base_var: str = "base_url") -> str:
    """{{base_url}}/api/v1 -> /api/v1 (для использования в f"{BASE_URL}{...}")"""
    pattern = re.compile(r"\{\{" + re.escape(base_var) + r"\}\}")
    return pattern.sub("", url)


@register_filter
def render_header_value(value: str) -> str:
    """Bearer {{token}} -> f"Bearer {os.environ.get('token', '')}" """
    if "{{" not in value:
        return repr(value)
    parts = re.split(r"\{\{(\w+)\}\}", value)
    expressions = []
    for i, part in enumerate(parts):
        if i % 2 == 0:
            if part:
                expressions.append(repr(part))
        else:
            expressions.append(f"os.environ.get({part!r}, '')")
    return f"f\"\"\"" + "\".join({})".format(" + ".join(expressions))

(Это упрощённая версия; в реальном коде есть дополнительные edge-кейсы для пустых и enabled/disabled заголовков.)

Что я узнал, пока писал

Pydantic v2 — реально хороший выбор. Изначально хотел обойтись без зависимостей и парсить вручную. Через 200 строк кода понял, что Pydantic делает то же самое за 30 строк, плюс даёт мне валидацию входных данных бесплатно. Зависимость стоит того.

Jinja2 в стороне от pytest. Шаблон сам по себе не запускает pytest. Это плюс: я могу тестировать сам шаблон рендером в строку без запуска тестов. Развязка ускоряет dev-loop.

Edge-кейсы прячутся в коллекциях. Postman достаточно гибкий, чтобы пользователи делали странное: пустые тела запросов, headers с переменными внутри значений, multipart-формы, дублирующиеся имена в разных папках. v1.0 закрывает основные случаи. Для редких кейсов рекомендую завести issue с примером коллекции.

Roadmap

Слежу за реальными use-кейсами. Что в очереди:

Поддержка .postman_environment.json (priority 1, многие пишут про это)
Pre-request скрипты — но только когда поведение можно перевести в Python однозначно
Response body assertions с поддержкой схем (JSON Schema или Pydantic-модели)
Параметризация через CSV-файл (как Newman это делает)

Если у вас сложный кейс конверсии, который не работает — открывайте issue с примером коллекции (sanitize sensitive data сначала). Я просмотрю и либо допишу поддержку, либо документирую workaround.

Ссылки

Если коллекция, которая у вас есть, не работает с конвертером — открывайте issue.