Миграция с Postman / Newman

Если ваши CI-сборки уже запускают коллекции Postman через Newman, начните здесь.
Коллекцию Postman v2.1 можно запустить через Mockarty CLI и сравнить отчёты
перед переключением пайплайна. Если вы пишете новый набор тестов на Go, Python,
Java или Kotlin, откройте переход на Mockarty Tester.

TL;DR

# Newman
newman run api.postman_collection.json \
    --env staging.postman_environment.json \
    --iterations 5 \
    --reporter cli,junit --reporter-junit-export=report.xml

# Mockarty CLI — используйте готовые файлы коллекции и окружения
mockarty-cli postman run api.postman_collection.json \
    --env staging.postman_environment.json \
    --iterations 5 \
    --reporter cli,junit --out junit:report.xml

Файл коллекции менять не нужно. Перед заменой Newman в CI проверьте результаты
и код завершения на своём наборе, особенно если в нём есть собственные скрипты
или отчёты. Успешный запуск завершается с кодом 0, ошибка проверки — с 1.

Зачем мигрировать?

• Без Node.js / npm: Mockarty CLI — один Go-бинарник. Никаких
  npm install -g newman, никаких security-алёртов на транзитивные
  зависимости. Air-gapped развёртывание работает из коробки.
• Шире протокольная поверхность: тот же скрипт может ходить в gRPC,
  Kafka, RabbitMQ, GraphQL, SOAP через mk.* extensions
  (опционально — ваша Newman-коллекция использует только pm.* и
  продолжает работать как есть).
• First-class Allure + JUnit + JSON reporters с парностью схеме
  вывода Newman.

Что поддерживается

Mockarty’s Postman runner поддерживает полную схему Postman v2.1 и
sandbox-поверхность Newman 6.x:

• Все 11 auth-стратегий: Basic, Bearer, API Key, OAuth 1.0a (каждый
  метод подписи), OAuth 2.0 (каждый grant flow), Digest (MD5 + SHA-256
  • qop), NTLM v2, AWS Signature v4, Hawk, Akamai EdgeGrid, JWT (HS/RS/
    ES/PS, custom headers).
• Все 6 body-режимов: raw (json/xml/html/text/javascript),
  urlencoded, formdata (с file uploads), file, graphql, binary. Файловые
  поля при импорте сохраняют исходное имя файла как подсказку (сами байты
  непереносимы между машинами) — API Tester показывает «Прикрепите заново:
  <имя>» и предупреждает перед отправкой пустой файловой части.
• Полная pm. поверхность*: pm.environment,
  pm.collectionVariables, pm.variables, pm.globals, pm.request,
  pm.response, pm.test, pm.expect (вся chai chain),
  pm.sendRequest, pm.iterationData, pm.execution (skipRequest /
  setNextRequest / stopRunning), pm.cookies (mutable jar), pm.info.
• Variable scope precedence идентична Newman: local > data >
  environment > collection > globals.
• Path-переменные в URL (/users/:userId/posts/{postId}) — обе
  формы (через : и в фигурных скобках) подставляются из таблицы
  url.variable[] запроса. Если плейсхолдер не найден в этой таблице,
  он переписывается в {{userId}} и резолвится через scope chain
  (environment / collection переменные).
• Iteration data из CSV или JSON. Вложенные объекты в JSON
  поддерживаются.
• Reporters: cli, json, newman-json (Newman-совместимый),
  junit, allure.
• Мультипротокольные запросы при импорте: HTTP, GraphQL (body mode
  graphql), gRPC (запросы grpc:// / grpcs:// — service, method и
  сообщение мапятся в gRPC-тестер Mockarty; grpcs включает TLS) и
  WebSocket (запросы ws:// / wss://). Каждый после импорта
  открывается в своей панели протокола. Запросы MQTT и Socket.IO пока не
  имеют нативного аналога и импортируются как HTTP-заглушки.

Если нужная вам возможность Postman не покрыта выше — напишите нам:
поверхность совместимости расширяется с каждым релизом.

Проверка импорта в API Tester

После импорта коллекции Postman, Insomnia или Bruno API Tester показывает,
сколько коллекций, запросов и папок сохранено. Если часть элементов не удалось
сохранить или требуется адаптация, внутри приложения открывается отчёт.
В нём перечислены затронутые названия и предупреждения о совместимости —
открывать консоль браузера не нужно. В больших отчётах показано до 50 записей
в каждом разделе, длинный текст сокращается. Перед повторным импортом проверьте
сохранённые коллекции, чтобы не создать дубликаты. Если папку не удалось
сохранить, её запросы могут находиться в корне коллекции.
Если у элемента HTTP, gRPC или WebSocket схема в raw URL противоречит отдельному
полю protocol, этот элемент пропускается и указывается в отчёте с подсказкой. Исправьте
исходную коллекцию перед повторным импортом: Mockarty не меняет транспортный
режим молча.

Когда коллега создаёт, импортирует, изменяет или удаляет коллекцию в том же
пространстве имён, открытая вкладка API Tester обновляет список автоматически.
Дерево запросов выбранной коллекции тоже обновляется. Несохранённые правки в
редакторе запроса при этом не заменяются содержимым списка.
Если другой пользователь удалит выбранный запрос, редактор остановит его
сохранение и покажет ошибку; удалённый запрос не будет создан повторно.
Пустые папки сохраняются. Дерево может содержать до 128 уровней. Более глубокая
коллекция Postman отклоняется, а слишком глубокие ветки Bruno или Insomnia
пропускаются и перечисляются в предупреждениях импорта. Экспорт коллекции в
Postman и её повторный импорт также сохраняют пустые папки.

Необязательное имя коллекции, введённое в диалоге импорта, применяется к
сохранённой коллекции. Сохранённые примеры ответов Postman переносятся при импорте
и последующем экспорте, даже если создание моков из примеров выключено.
Явная настройка Без авторизации сохраняется и не подменяется авторизацией
родительской папки или коллекции.
Отключённые заголовки и query-параметры сохраняются, показаны без галочки в
редакторе и экспортируются с признаком отключения. Повторяющиеся активные ключи
заголовков и query-параметров также остаются отдельными строками после открытия
и сохранения запроса.
Большие целые значения в окружениях Postman и Insomnia сохраняются точно, в том
числе за пределами диапазона безопасных целых JavaScript.
Файлы окружения и глобальных переменных Postman загружаются через
Импорт окружения. В результате указано, сколько отключённых строк и строк
без имени пропущено. Если активный ключ переменной повторяется, сохраняется
последнее активное значение, а число перезаписанных строк показывается в
результате. Проверьте его перед запуском тестов.

При дублировании сохранённой коллекции сохраняются вложенность папок, порядок
запросов, скрипты и их включённое или выключенное состояние. Запросы и папки
копии независимы от исходных. Если исходный запрос не удаётся прочитать или он
ссылается на отсутствующую родительскую папку, операция завершается ошибкой,
не оставляя частичную копию.

Установка

# Скачать релизный бинарник
curl -L https://mockarty.ru/download/cli/latest/linux-amd64 -o mockarty-cli
chmod +x mockarty-cli

# Или через Homebrew
brew install mockarty/tap/mockarty-cli

Команды

Запуск коллекции

mockarty-cli postman run collection.json

Дефолтное поведение: 1 итерация, timeout запроса 60 с, follow redirects.

Environment + globals

mockarty-cli postman run collection.json \
    --env staging.postman_environment.json \
    --globals globals.postman_globals.json

Inline-override:

mockarty-cli postman run collection.json \
    --env-var baseUrl=https://api.example.com \
    --env-var apiKey=abc123

--env-var выигрывает у --env, как в Newman.

Iteration data

# CSV (RFC 4180, header row обязателен)
mockarty-cli postman run collection.json --data users.csv

# JSON array
mockarty-cli postman run collection.json --data users.json

Iteration count = len(rows). Если --data не задан — используйте
--iterations N.

Фильтр по папке

mockarty-cli postman run collection.json --folder "Healthchecks"

Фильтр — case-insensitive substring match на путь папки.

Reporters

mockarty-cli postman run collection.json \
    --reporter cli,junit,newman-json,allure \
    --out junit:report.xml \
    --out newman-json:newman.json \
    --out allure:allure.json

cli пишет в stderr; остальные — в файлы, указанные в --out.

Bail / failfast

mockarty-cli postman run collection.json --bail

Останавливается на первом failing assertion.

TLS

mockarty-cli postman run collection.json --insecure

Отключает проверку сертификатов.

Перенос Newman CI-скриптов

Mockarty CLI принимает каждый флаг Newman 6.x. Drop-in compatible:

Реже используемые флаги Newman принимаются как no-op alias’ы для
гладкости миграции (--insecure-file-read, --working-dir, --bigInt,
--color, --disable-unicode, --ssl-client-cert,
--ssl-extra-ca-certs). Сегодня они не меняют поведение; уберите их
из вашего вызова, когда сочтёте нужным.

Примеры

GitHub Actions

name: API tests
on: [push]
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Установить Mockarty CLI
        run: |
          curl -L https://mockarty.ru/download/cli/latest/linux-amd64 \
            -o mockarty-cli && chmod +x mockarty-cli
      - name: Запустить Postman-коллекцию
        run: |
          ./mockarty-cli postman run tests/api.postman_collection.json \
              --env tests/staging.postman_environment.json \
              --reporter cli,junit \
              --out junit:report.xml
      - uses: actions/upload-artifact@v4
        with:
          name: junit-report
          path: report.xml

GitLab CI

api-tests:
  image: debian:stable-slim
  script:
    - curl -sSL https://mockarty.ru/install.sh | sh
    - mockarty-cli postman run tests/api.json --reporter junit --out junit:report.xml
  artifacts:
    reports:
      junit: report.xml

Jenkins

pipeline {
  agent any
  stages {
    stage('API tests') {
      steps {
        sh '''
          mockarty-cli postman run api.json \\
              --env staging.json \\
              --reporter cli,junit \\
              --out junit:report.xml
        '''
        junit 'report.xml'
      }
    }
  }
}

Лимиты анонимного режима

Когда Mockarty CLI работает без подключения к серверу (нет
mockarty-cli auth login), Postman runner лимитирован 50 запросами на
коллекцию и 5 итерациями. Этого хватает для smoke-прогона; снять лимит
можно, подключившись к серверу (self-hosted или desktop).

Troubleshooting

parse_failed: empty input

Файл коллекции пустой или это не валидный JSON. Проверьте, что это
реальный экспорт .postman_collection.json, а не отдельный фрагмент.

unknown collection schema "..."

Mockarty принимает схемы Postman v2.0.0 и v2.1.0 (URL’ы в SchemaURLs).
Экспорты Bruno + Insomnia вообще не содержат поле schema и парсятся
нормально. Warning здесь — не фатальная ошибка; прогон продолжается.

Текст assertion-ошибок отличается от Newman

Текст ошибки assertion может отличаться — Newman поставляется с
custom-расширениями Chai. Количество провалов должно совпадать. Если
видите несовпадение по числу — заведите issue с приложенной коллекцией.

oauth2: token endpoint returned 401

OAuth 2 token endpoint отверг сконфигурированные client credentials.
Проверьте clientId / clientSecret в auth-параметрах коллекции и что
token URL доступен из сети runner’а.

Ошибки digest: ...

Digest authentication требует, чтобы сервер сначала прислал Digest
challenge на 401. Если сервер отвечает 401 без заголовка
WWW-Authenticate: Digest realm="...", runner не может подписать
retry. Убедитесь, что сервер настроен на Digest, а не на Basic.

429 IMPORT_BUSY при импорте

Сервер уже обрабатывает доступное число импортов. Этот импорт не начался:
подождите время из заголовка Retry-After (сейчас одна секунда) и отправьте
тот же файл повторно. Правило действует для Postman, Bruno, Insomnia и других
импортов API Tester. Не отправляйте много больших коллекций одновременно.

Дополнительные возможности импорта

Saved responses → моки (seed на импорте)

Если коллекция Postman содержит сохранённые примеры ответов, при импорте из
них можно создать моки Mockarty. API принимает JSON коллекции в поле
collectionJson. Этот пример читает файл и собирает запрос:

python3 - <<'PY' | curl -fsS -X POST http://localhost:5770/api/v1/api-tester/import/postman \
  -H "Authorization: Bearer ${MOCKARTY_API_TOKEN:?set MOCKARTY_API_TOKEN}" \
  -H "Content-Type: application/json" --data-binary @-
import json
from pathlib import Path
collection = json.loads(Path("api.postman_collection.json").read_text())
print(json.dumps({"collectionJson": collection, "collectionName": "Imported", "seedMocks": True}))
PY

Задайте MOCKARTY_API_TOKEN — токен с правом импортировать коллекции и
создавать моки в нужном пространстве. В ответе поле seededMocks покажет,
сколько моков создано или пропущено и почему.

Если у одного запроса несколько сохранённых примеров, Mockarty
автоматически активирует магический header x-mock-response-code от
Postman — curl с x-mock-response-code: 404 будет всегда подбирать
вариант 404, как описано в Postman matching algorithm.

pm.vault.{get,set,has,unset}

API Postman Vault теперь доступен в скриптах:

var token = pm.vault.get('production-token');
pm.request.headers.add({key: 'Authorization', value: 'Bearer ' + token});
pm.vault.set('last-run', new Date().toISOString());

Секреты изолированы per-namespace на сервере и никогда не утекают
между тенантами. Если platform-админ ещё не подключил secret-backend,
биндинг молча возвращает пустую строку на get и пишет предупреждение в
run-log на set.

pm.cookies.jar()

Postman cookie jar поддержан для set / get / getAll / unset /
clear. Принимаются обе формы вызова — (url, name, value, callback)
и (url, cookieObject, callback). Callback’и срабатывают inline (JS-движок
однопоточный), но контракт API 1:1 с Postman.

var jar = pm.cookies.jar();
jar.set('https://api.example.com/', 'session', 'abc123');
jar.get('https://api.example.com/', 'session', function(err, c) {
  console.log('session =', c.value);
});

Модули require() в пространстве имён Mockarty

В дополнение к существующим require('mockarty/http') и
require('mockarty/sql'), скрипты теперь подгружают эти лёгкие хелперы
без многомегабайтного Newman UMD-стека:

Если ваш Postman-скрипт использует require('lodash') /
require('moment') — замените на mk.faker.* / нативные JavaScript
эквиваленты. Мы целенаправленно НЕ vendor’им эти библиотеки — они
занимают большую часть Newman-binary, а реальных use case’ов немного.

Импорт из Insomnia v4 / v5

Mockarty также принимает Insomnia v4 и v5 экспорты через новый
эндпоинт:

curl -X POST http://localhost:5770/api/v1/api-tester/import/insomnia \
  -H "Content-Type: application/json" \
  -d '{
    "exportJson":    <вставьте insomnia export file>,
    "collectionName": "Imported from Insomnia"
  }'

Группы запросов становятся папками с сохранением порядка. Если экспорт содержит
несколько рабочих пространств, каждое становится отдельной папкой верхнего уровня.
Отсутствующие родители, повторяющиеся идентификаторы и циклы папок отклоняются
до сохранения: запросы не могут исчезнуть незаметно. Поддерживаемые настройки
авторизации сохраняются; netrc не переносится, об этом появляется предупреждение.

Окружения Insomnia сохраняются отдельно в API Tester с именами
Коллекция / Окружение. Каждое включает переменные своего родительского окружения;
соседние окружения остаются раздельными. Они приватные и неактивные.
Перед отправкой запросов выберите нужное окружение. Импорт не заменяет уже
существующее окружение и не меняет текущее активное окружение.

При импорте ZIP Bruno каждый файл environments/*.bru также сохраняется как
отдельное приватное неактивное окружение с относительным путём файла в имени.
Отключённые переменные пропускаются. Ни порядок файлов ZIP, ни порядок ресурсов
Insomnia не назначает production-значения переменными коллекции по умолчанию.
Авторизация коллекции и папок Bruno наследуется запросами; явная настройка
Без авторизации останавливает наследование. Переменные коллекции остаются
значениями коллекции по умолчанию. Скрипты коллекции и папок сохраняются на
запросах, но выключаются до проверки. Для наследуемых заголовков и переменных
папок действуют разные правила: заголовки коллекции и папок наследуются запросами;
одноимённый заголовок ближайшей папки или запроса (без учёта регистра) заменяет
родительский. Отключённый заголовок запроса также не отправляет родительское
значение. Повторяющиеся заголовки одного уровня остаются отдельными строками.
Переменные папок и запросов сохраняются с каждым импортированным запросом.
Значение ближайшей папки или запроса имеет приоритет над активным окружением
и значением коллекции по умолчанию; отключённое значение снимает локальное
переопределение. Редактирование и сохранение запроса сохраняет эти переменные.
Если наследуемые заголовки и переменные после разворачивания во все запросы
превысят 32 МиБ, импорт отклоняется.
Простые ссылки Insomnia
вида {{ _.base }} преобразуются в {{base}} в URL, заголовках, параметрах,
теле запроса и настройках авторизации.

Ответ содержит environments с сохранёнными ID и именами, а также счётчики
summary.environments / summary.totalEnvironments. Значения переменных в этом
списке не возвращаются. Если окружение не удалось сохранить, ответ имеет статус
207 Multi-Status, а failures содержит запись kind: environment; успешно
сохранённые коллекции и окружения остаются доступны. Один импорт поддерживает
до 256 окружений; для наследования Insomnia действуют ограничения в 100 000
развёрнутых значений и 50 МиБ их суммарного размера.

Insomnia gRPC и WebSocket-запросы импортируются как HTTP-плейсхолдеры с
подсказкой в description о исходном типе. Mockarty эти протоколы
выполняет нативно в других местах — направляйте тестовые скрипты на
соответствующие моки.

Ограничения

Размер загружаемой коллекции Postman ограничен 50 МиБ. Если загрузка прервана
или тело не удалось прочитать полностью, Mockarty отклоняет его и не сохраняет
частичный импорт.

При импорте GraphQL переменные принимаются как JSON-объект или строка с таким
объектом. Пустые переменные и null допустимы. Некорректные переменные Postman
отклоняют импорт; запросы Bruno или Insomnia с некорректными переменными попадают
в отчёт об отказах, а не сохраняются без переменных. Исправьте переменные в
источнике и повторите импорт. Сохранённые переменные GraphQL, введённые текстом
JSON, проверяются перед отправкой запроса. Переменные должны быть объектом или
null, а не массивом или скалярным значением. Числа, введённые в редакторе
переменных, отправляются без округления. Числа в импортированных переменных также
сохраняют точность при открытии и сохранении запроса в редакторе. Подстановки окружения внутри строковых
значений остаются строками, даже если содержат кавычки или переносы строк.
Импортированные GraphQL-запросы также сохраняют авторизацию (в том числе
унаследованную от коллекции), прокси, ссылки на сертификаты и настройки
HTTP-профиля. Файлы сертификатов нужно настроить на принимающей стороне.
Импортированные настройки HTTP Bearer, Basic, API-ключа и OAuth 2 открываются
заполненными на вкладке «Авторизация» и сохраняются вместе с запросом. Секретные
значения не попадают в локальное восстановление черновика браузера: сохраните
запрос, если они нужны после перезагрузки страницы. OAuth-токен относится только
к текущему запросу и автоматически не переиспользуется другим запросом.

Пути записей в ZIP-архиве Bruno должны быть относительными, с разделителем /.
Записи с абсолютными путями, префиксами дисков Windows, обратными косыми чертами
или отдельными сегментами ./.. пропускаются с предупреждением. Точки внутри
обычного имени, например users..v2.bru, поддерживаются.

Скрипты из Bruno и Insomnia сохраняются, но остаются выключенными. Перед
включением в редакторе запроса адаптируйте используемые скриптовые API к Mockarty
и выполните запрос для проверки результата. Предупреждения импорта указывают
затронутые запросы. Скрипты перед запросом и тесты из Postman остаются включёнными,
если они присутствуют в коллекции.

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

Несколько редких Postman-фич принимаются, но работают в усечённом виде:

• pm.visualizer.set(template, data): вызов записывается в run
  report, но HTML-визуализация не генерируется.
• OAuth 2 implicit / authorization_code grant: access token должен
  уже быть в коллекции (Postman вписывает его после interactive browser
  flow). Mockarty не запускает interactive browser.
• pm.cookies.jar().getAllForRequest(url): возвращает snapshot всего
  jar; реальное domain matching выполняется Go-стороной, когда запрос
  действительно отправляется.

Все остальные deviations задокументированы в COMPAT_MATRIX.md.

Поддержка

• Issue: https://github.com/mockarty/mockarty — приложите коллекцию (или
  минимальный reproduction) и команду, которую запускали.
• Telegram-канал Mockarty (ссылка в основном README).