Вот есть 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 passedCI прогоняется на 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.