Postman / Newman Migration Guide

If your CI already runs Postman collections with Newman, start here. You can
run a Postman v2.1 collection with Mockarty CLI and compare the reports before
switching your pipeline. For a new test suite written in Go, Python, Java, or
Kotlin, see Migrating to 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 — use the collection and environment files you already have
mockarty-cli postman run api.postman_collection.json \
    --env staging.postman_environment.json \
    --iterations 5 \
    --reporter cli,junit --out junit:report.xml

The collection file stays the same. Check the reported results and exit code
on your own suite before replacing Newman in CI, especially if it uses custom
scripts or reporters. A passing run exits with 0; an assertion failure exits
with 1.

Why migrate?

• No Node.js / npm: Mockarty CLI is a single Go binary. No npm install -g newman, no security alerts on a transitive dependency. Air-gapped
  deployments work out of the box.
• Wider protocol surface: same script can target gRPC, Kafka,
  RabbitMQ, GraphQL, SOAP through mk.* extensions (optional — your
  Newman collection uses pm.* only and keeps working).
• First-class Allure + JUnit + JSON reporters with parity to Newman’s
  output schema.

What’s supported

Mockarty’s Postman runner supports the full Postman v2.1 schema and the
Newman 6.x pm.* sandbox surface:

• All 11 auth strategies: Basic, Bearer, API Key, OAuth 1.0a (every
  signature method), OAuth 2.0 (every grant flow), Digest (MD5 + SHA-256
  • qop), NTLM v2, AWS Signature v4, Hawk, Akamai EdgeGrid, JWT (HS/RS/
    ES/PS, custom headers).
• All 6 body modes: raw (json/xml/html/text/javascript), urlencoded,
  formdata (with file uploads), file, graphql, binary. File fields keep
  the original filename as a re-attach hint on import (the bytes aren’t
  portable across machines) — the API Tester shows a “Re-attach: <name>”
  prompt and warns before sending an empty file part.
• Full pm. surface*: pm.environment, pm.collectionVariables,
  pm.variables, pm.globals, pm.request, pm.response, pm.test,
  pm.expect (full chai chain), pm.sendRequest, pm.iterationData,
  pm.execution (skipRequest / setNextRequest / stopRunning),
  pm.cookies (mutable jar), pm.info.
• Variable scope precedence identical to Newman: local > data >
  environment > collection > globals.
• Path variables in URLs (/users/:userId/posts/{postId}) — both
  colon-prefix and brace forms are substituted from the request’s
  url.variable[] table. Unknown placeholders fall through to the
  scope chain (so /users/:userId with no path-var match becomes
  /users/{{userId}} and resolves against environment / collection
  variables).
• Iteration data from CSV or JSON. Nested objects in JSON data
  files are supported.
• Reporters: cli, json, newman-json (Newman-compatible),
  junit, allure.
• Multi-protocol requests on import: HTTP, GraphQL (graphql body
  mode), gRPC (grpc:// / grpcs:// requests — service, method and
  message are mapped onto Mockarty’s gRPC tester; grpcs enables TLS),
  and WebSocket (ws:// / wss:// requests). Each opens in its
  matching protocol panel after import. MQTT and Socket.IO requests have
  no native target yet and import as HTTP placeholders.

If a specific Postman feature you rely on isn’t covered above, reach
out — the compatibility surface is expanding with each release.

Checking an API Tester import

After importing a Postman, Insomnia or Bruno collection, API Tester shows how
many collections, requests and folders were saved. If some items could not be
saved or need compatibility adjustments, a report opens inside the application.
It lists the affected names and compatibility warnings; the browser console is
not required. Long reports show up to 50 entries per section and shorten long
text. Review the saved collections before importing again to avoid duplicates.
If an HTTP, gRPC or WebSocket item’s raw URL scheme conflicts with its separate
protocol field, that item is skipped and named with a correction hint in the report. Correct the
source collection before retrying; Mockarty does not silently change its
transport security setting.
When a teammate creates, imports, edits or removes a collection in the same
namespace, an open API Tester tab refreshes its collection list automatically.
The currently selected collection’s request tree also refreshes. Unsaved edits
in the request editor are not replaced by this list refresh.
If another user removes the selected request, the editor stops saving it and
shows an error; it does not recreate the removed request.
If a folder could not be saved, its requests may appear at the collection root.
Empty folders are preserved. Folder trees may contain up to 128 levels. A deeper
Postman tree is rejected; over-deep Bruno or Insomnia branches are skipped and
listed in the import warnings. Exporting a collection to Postman and importing
it again also preserves empty folders.

An optional collection name entered in the import dialog is applied to the saved
collection. Saved Postman response examples survive import and subsequent export,
even when Seed mocks is disabled. An explicit No Auth setting is retained;
it does not fall back to authentication inherited from a folder or collection.
Disabled headers and query parameters are retained, shown unchecked in the editor,
and exported with their disabled state. Repeated enabled header and query keys
also retain their separate rows when the request is opened and saved.
Large integer values in imported Postman and Insomnia environments retain their
exact digits, including values larger than JavaScript’s safe integer range.
Postman environment and globals files import through Import Environment.
The result shows counts of disabled and unnamed rows that were skipped. If a
file repeats an enabled variable key, the last enabled value is kept and the
number of overwritten rows is reported. Review that count before running tests.

Duplicating a saved collection preserves its folder hierarchy, request order,
scripts and their enabled/disabled state. The copy has independent request and
folder identities. If a source request cannot be read or refers to a missing
parent folder, duplication fails without leaving a partial copy.

Installation

# Download a release binary
curl -L https://mockarty.ru/download/cli/latest/linux-amd64 -o mockarty-cli
chmod +x mockarty-cli

# Or via Homebrew
brew install mockarty/tap/mockarty-cli

Command reference

Run a collection

mockarty-cli postman run collection.json

Default behaviour: 1 iteration, request timeout 60 s, follow redirects.

Environment + globals

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

Inline overrides:

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

--env-var wins over --env, mirroring Newman.

Iteration data

# CSV (RFC 4180, header row required)
mockarty-cli postman run collection.json --data users.csv

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

The iteration count comes from len(rows). If --data is not supplied,
use --iterations N.

Filter to one folder

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

The filter is a case-insensitive substring match on the folder path.

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

The cli reporter writes to stderr; everything else goes to the path
named on --out.

Bail / failfast

mockarty-cli postman run collection.json --bail

Stops at the first failing assertion.

TLS

mockarty-cli postman run collection.json --insecure

Disables certificate verification.

Migrating Newman CI scripts

The Mockarty CLI accepts every Newman 6.x flag. Drop-in compatible:

Less common Newman flags are accepted as no-op aliases for migration
smoothness (--insecure-file-read, --working-dir, --bigInt,
--color, --disable-unicode, --ssl-client-cert,
--ssl-extra-ca-certs). They don’t change behaviour today; you can
remove them from your invocation when ready.

Examples

GitHub Actions

name: API tests
on: [push]
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Mockarty CLI
        run: |
          curl -L https://mockarty.ru/download/cli/latest/linux-amd64 \
            -o mockarty-cli && chmod +x mockarty-cli
      - name: Run Postman collection
        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'
      }
    }
  }
}

Anonymous mode limits

When you run Mockarty CLI without connecting to a Mockarty server (no
mockarty-cli auth login), the Postman runner is capped at 50 requests
per collection and 5 iterations. This is enough for a smoke run; remove
the cap by connecting to a server (self-hosted or desktop).

Troubleshooting

parse_failed: empty input

The collection file is empty or not valid JSON. Check that the file is a
real .postman_collection.json export, not just a request snippet.

unknown collection schema "..."

Mockarty accepts Postman v2.0.0 and v2.1.0 schemas (the URLs listed in
SchemaURLs). Bruno + Insomnia exports drop the schema field entirely
and parse fine. A warning here is non-fatal — the run proceeds.

Assertion failures look different from Newman

The text of an assertion failure can differ — Newman ships custom Chai
extensions. The count of failures must match. If you see a count
mismatch, please file an issue with the collection attached.

oauth2: token endpoint returned 401

The OAuth 2 token endpoint rejected the configured client credentials.
Check clientId / clientSecret in the collection’s auth params, and
make sure the token URL is reachable from the runner’s network.

digest: ... errors

Digest authentication requires the server to advertise a Digest
challenge on the first 401 response. If the server returns 401 without a
WWW-Authenticate: Digest realm="..." header, the runner can’t sign the
retry. Verify the server is configured for Digest, not Basic.

429 IMPORT_BUSY during import

The server is processing its current import capacity. The import was not
started; wait for the Retry-After interval (currently one second) and send
the same file again. This applies to Postman, Bruno, Insomnia and other API
Tester imports. Avoid sending many large collections at once.

Optional import features

Saved responses → mocks (seed at import time)

If your Postman collection contains saved response examples, you can create
Mockarty mocks from them during import. The API accepts the collection as JSON
inside collectionJson; this example reads the file and builds that request:

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

Set MOCKARTY_API_TOKEN to a token allowed to import collections and create
mocks in the target namespace. The response includes seededMocks with the
number created or skipped and the reasons for any skipped examples.

When a request item has more than one saved example, Mockarty
automatically activates the Postman x-mock-response-code magic
header — a curl with x-mock-response-code: 404 will always pull the
404 variant, matching Postman’s documented matching algorithm.

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

The Postman Vault API is available inside scripts:

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

Secrets are namespace-scoped server-side and never leak across tenants.
When the platform admin has not yet wired the secret backend the
binding silently degrades to empty reads + write-warnings in the run
log.

pm.cookies.jar()

The Postman cookie jar API works out of the box for set / get /
getAll / unset / clear. Both the (url, name, value, callback)
and (url, cookieObject, callback) shapes are accepted. Callbacks fire
inline (the JS runtime is single-threaded) but the call surface matches Postman
1:1.

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);
});

Mockarty-namespaced require() modules

In addition to the historic require('mockarty/http') and
require('mockarty/sql'), scripts can now pull these light-weight
helpers without the multi-MB Newman UMD stack:

If a Postman script you’re migrating uses require('lodash') /
require('moment'), replace with the equivalent mk.faker.* / native
JavaScript built-ins. We deliberately do NOT vendor those libraries —
they account for the majority of Newman’s binary size and very few
real-world scripts genuinely need them.

Importing from Insomnia v4 / v5

Mockarty also accepts Insomnia v4 and v5 exports through the new
endpoint:

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

Request groups become folders and their ordering is preserved. If an export
contains several workspaces, each workspace becomes a separate top-level folder.
Missing parents, duplicate resource IDs and cyclic groups are rejected before
saving, so requests cannot silently disappear. Supported authentication settings
are retained; netrc cannot be imported and produces a warning.

Insomnia environments are saved separately in API Tester, named
Collection / Environment. Each includes values inherited from its parent
environment; sibling environments stay separate. They are private and inactive.
Select the required environment before sending requests. Importing does not
replace an existing environment or change your current active environment.

Bruno ZIP imports also save each environments/*.bru file as a separate private,
inactive environment, retaining the relative file path in its name. Disabled
variables are skipped. Neither ZIP entry order nor the order of Insomnia resources
selects production values as collection defaults.
Bruno collection and folder authentication is inherited by requests; explicit
No Auth stops inheritance. Collection variables remain collection defaults.
Collection and folder scripts are retained on requests but disabled for review.
Collection and folder headers are inherited by requests. A header at a nearer
folder or request replaces the same name (case-insensitively); disabling it on
the request also prevents the inherited value from being sent. Repeated headers
at one level remain separate rows. Folder and request variables are saved with
each imported request. A nearer folder or request value wins over the active
environment and collection default; disabling a nearer value removes that
local override. Editing and saving the request keeps its imported variables.
The importer rejects archives whose inherited headers and variables would
expand beyond 32 MiB across the saved requests.
Plain Insomnia references such as {{ _.base }} become {{base}} in request
URLs, headers, parameters, bodies and authentication settings.

The response includes environments with saved IDs and names, and
summary.environments / summary.totalEnvironments counts. Variable values are
not returned in this list. If an environment cannot be saved, the response is
207 Multi-Status with a kind: environment entry in failures; successfully
saved collections and environments remain available. An import supports up to
256 environments, with at most 100,000 expanded values and a 50 MiB expanded
value budget for Insomnia inheritance.

gRPC and WebSocket Insomnia requests are imported as HTTP placeholders
with a description hint explaining what the original type was. Mockarty
runs those protocols natively elsewhere — point your test scripts at
the appropriate mock instead.

Limitations

Postman collection uploads are limited to 50 MiB. If the upload is interrupted
or cannot be read completely, Mockarty rejects it without saving a partial import.

GraphQL imports accept variables as a JSON object or a string containing that
object. Empty variables and null are allowed. Invalid Postman variables reject
the import; invalid Bruno or Insomnia variables appear as failed requests in the
import report, rather than becoming requests with missing variables. Correct the
source variables and import again. Saved GraphQL variables entered as JSON text
are validated before the request is sent. Variables must be an object or null,
not an array or scalar. Numbers typed in the variables editor are sent without
rounding. Imported variable numbers also retain their precision when you open
and save the request in the editor. Environment placeholders inside string values remain string values,
including when their replacements contain quotes or line breaks.
Imported GraphQL requests also retain authentication (including inherited
collection authentication), proxy, certificate references and HTTP profile
settings. Certificate files still need to be configured on the receiving side.
Imported HTTP Bearer, Basic, API-key and OAuth 2 settings open pre-filled in the
Auth tab and remain attached after saving the request. Secret values are not
kept in browser draft recovery; save the request if you need them after a page
reload. OAuth access tokens belong to the current request and are never reused
automatically by another request.

Bruno ZIP entry paths must be relative and use / separators. Entries with
absolute paths, Windows drive prefixes, backslashes or ./.. path segments
are skipped with a warning. Dots inside ordinary names, such as
users..v2.bru, are supported.

Scripts imported from Bruno and Insomnia are preserved but disabled. Before
enabling them in the request editor, adapt their scripting APIs to Mockarty and
run the request to check the result. Import warnings identify affected requests.
Native Postman pre-request and test scripts remain enabled when present.

File paths in exported requests do not transfer the files themselves. Only the
filename is retained as a hint; attach the file again before running the request.
The server does not read files from paths recorded in an imported collection.
Running a saved request with a missing file attachment returns an error instead
of silently sending an incomplete upload.

A few rare Postman features are accepted but degraded:

• pm.visualizer.set(template, data): the call is recorded in the
  run report but no HTML visualisation is produced.
• OAuth 2 implicit / authorization-code grant: the access token must
  already be in the collection (Postman fills it in after the
  interactive browser flow). Mockarty doesn’t drive an interactive
  browser.
• pm.cookies.jar().getAllForRequest(url): returns the full jar
  snapshot; the Go side handles real domain matching when the request is
  actually sent.

All other deviations are noted in COMPAT_MATRIX.md inside the
mockarty source tree.

Getting help

• Open an issue at https://github.com/mockarty/mockarty — include the
  collection (or a minimal reproduction) and the command you ran.
• Reach out on the Mockarty Telegram channel (link in the main README).