Postman Collection Import

Overview

Shift-Left Studio imports a Postman collection (v2.0 or v2.1 export) into a project. Each request becomes an endpoint, or joins one, and each request whose script checks something becomes its own test on that endpoint, with its own body, query parameters, headers and checks.

Studio models endpoints, and a collection holds requests. So when several requests call the same method and path, for example 23 POST /split-order/v2 requests with different payloads, you get one endpoint with one test per request. Nothing is merged across requests: each test keeps its own payload and its own checks.

This article covers what the import does with your requests and scripts, what it reports, how to convert checks it could not translate, and what happens when you import the collection again.

Key concepts

Before you begin

• Export the collection from Postman as a Collection v2.1 (or v2.0) JSON file.
• Open or create the project you want to import into.
• If you plan to convert checks with AI, make sure an AI provider is configured under Settings → AI Settings.
• For collections whose requests start with a variable such as {{baseUrl}}, know the real host so you can check the project's base URL after import.

Step 1 — Import the collection

1. In the sidebar, select the project, then click Endpoints. The Import API to Project dialog opens.
2. Choose Import from URL or upload the file, then click Import File (or import from the URL).
3. Studio recognizes the Postman format and imports it.

Step 2 — Read the import summary

When the import finishes, the dialog shows what happened to tests. Every request is accounted for.

Why some requests were skipped

A request with no checks is a saved request, not a test case. Importing every saved request as a test would add tests nobody wrote, each with a 200 check nobody asked for. So these requests are skipped by default, and the summary tells you how many.

If your collection uses bare requests as payload-only test cases, click Import those N request(s) as tests too. Studio re-runs the same import including them. Each one keeps its body, headers and query and expects a 200 response, which you can edit afterwards. The tests already imported are updated in place, not duplicated. Click Keep it as it is to leave the import as it stands.

A script that only saves a token or draws a visualizer chart, and checks nothing, is treated the same way as a request with no script.

Step 3 — Check how your checks were mapped

Open one of the imported tests and go to the Assertions tab.

• Simple checks become catalog assertions, for example pm.response.to.have.status(201) becomes Status Code Equals 201, and pm.expect(json.id).to.exist becomes a field-exists check.
• A local that holds the response is understood, for example const res = pm.response.json(); pm.expect(res.status).to.eql("OPEN").
• A set of statuses such as .to.be.oneOf([200, 201, 202]) is kept as a check that accepts exactly those statuses, not narrowed to 200.
• Checks whose subject is computed in the script, such as a loop that collects values and then checks them all, are compiled into one custom check per pm.test block. The card says Converted from a Postman script on import. It runs as written. When one fails, the result names the Postman test and the value.
• JSON-schema checks (jsonSchema(…), tv4.validate) become a JSON-schema check.
• Chai's .not is honored the way chai applies it: it negates every assertion word after it in the chain. So .to.not.be.null.and.to.be.an('object') fails on an object in Studio, exactly as it does in Postman.

Important: The collection's code is never run as written. Studio rebuilds each check from a restricted set of safe constructs. Anything outside that set, such as pm.sendRequest, lodash, cheerio or unbounded loops, is not compiled and stays Needs review. This protects the server that runs your tests.

A check that reads a Postman variable with no default, such as pm.environment.get("x"), also stays Needs review, because the value isn't available when the check runs. With a default, such as pm.environment.get("x") || "360", the default is used.

Step 4 — Convert the checks that need review

A Needs review check fails on every run until it's converted. There are three ways to convert it, and all three use the same converter:

The converter tries the most faithful method first:

1. The collection's own script. Studio keeps the original script on any test that still has an unconverted check, and re-translates it with today's translator. No AI is used.
2. The check's own code, compiled alone. This works when the check is a complete, self-contained pm.test block.
3. The AI, only for what is left. It sees the check, the stored script, the request, the documented response and the last observed response. It may only supply what the check referred to (for example, that r is the response body). The check itself must stay exactly as the collection wrote it, and a value the AI made up is refused.

From the import summary:

1. Click Convert the N check(s). Script-based conversions are applied at once, and the summary reports N check(s) converted on N test(s).
2. If some remain, click Use the AI for the N test(s) left. Studio processes 10 tests at a time. Click Continue with the next… for more.
3. AI conversions are never applied automatically. The summary says N test(s) have an AI conversion ready for you to review. Open each test to see the change in a side-by-side preview and accept it.

Note: If no AI provider is configured, the summary says so, and only script-based conversions run.

Step 5 — Check captured values and the base URL

Captured values. When a script saves a piece of the response for later requests, for example pm.environment.set("version", json[json.length-1].version), the import adds a data extraction to that request's success test. Open the test's Data tab to see it under Data extraction. A later request that uses {{version}} in its URL gets a path parameter whose value is {{version}}, filled in at run time.

• A value computed in the script, such as "Bearer " + token, can't be captured and is skipped.
• Captured values flow only to tests that run later in the same pack run. Put the producing test before the consuming tests when you build the pack.

Base URL. Postman treats the first part of a URL as the host. So a request such as {{_endpoint}}/services/data has {{_endpoint}} as its host, whatever the variable is called, and Studio does not turn it into a path segment. When the collection defines that variable as an http(s) URL, it becomes the project's base URL. If the collection leaves it empty (for example, when an OAuth flow fills it in Postman), set the project's base URL yourself.

Authentication. Inline credentials in a collection, such as a hard-coded cookie or bearer token, are not copied onto every test. They are mapped to an authentication profile and wired through the project's environment.

Step 6 — Import the collection again after it changes

You can import the same collection again at any time. Each test is matched on its endpoint, its folder path and name in the collection, and its scenario:

Nothing is duplicated. Requests with duplicate names in the same folder are told apart as name, name #2, name #3.

A re-import also upgrades tests imported by an older version of Studio: when a test still holds unedited Needs review checks that today's translator can convert, they are replaced. A check someone has already rewritten is never overwritten. Files you chose for file uploads are kept.

When the import needs approval

If the import changes endpoints already in the project, Studio may open Review API Changes instead of applying the changes straight away.

1. Review the summary and the list of changes. Breaking changes are called out.
2. Click Approve & Import to apply them, Reject to discard them, or Cancel to decide later.
3. After approval, the dialog shows Changes approved and imported. with the same test summary as a normal import, including Import those N request(s) as tests too for skipped requests.
4. Click Done.

Troubleshooting

Best practices

• Write a pm.test for every request you want as a test. It makes the import's choice obvious.
• Convert Needs review checks before you add the tests to a scheduled pack, or the pack will report failures that aren't about your API.
• Re-import the collection after you edit it in Postman rather than editing both copies.
• Keep the collection's own variable names. Studio understands the common idioms.

Related articles

• Import API definitions
• Test cases: open, edit and save
• File uploads and form bodies
• Assertions, results and custom checks
• Fix with AI
• Project Assistant actions