Run Postman Mock Servers on Localhost

Updated April 2024

One of Postman's many wonderful features is its ability to run a Postman Collection as a callable Mock Server with a few simple clicks.

Postman Mock Servers provide two major benefits:

Removing dependencies

Coding against mock servers removes a dependency on downstream APIs being available. Instead developers can build configure the mock servers, specify the examples that they want to be returned and implement their code to handle these use cases.

Likewise API testers are unblocked as they can write and validate their API tests against the mock servers and only switch to hitting real endpoints when the developers have deployed stable (testable) code.

Collaboration on expected state

Mock servers are a great way for teams to collaborate on the expected inputs and outputs of an API.

There's nothing quite like hitting an endpoint to see exactly what it's going to return. This is taken to the next level when developers, testers and consumers of an API are all given access to the same mock server. Everyone is seeing the same expected state, and everyone has a common shared goal.

All in all these are great features to have as part of any modern development lifecycle.

So what's the issue then?

One challenge with this is that even after removing a dependency on a downstream API provider you are still at the whim of Postman.

Postman's mock servers run on Postman's cloud (AWS), so if you are working in an environment where external internet access is tricky, or you simply need to run your mock servers closer to your client code, Postman Local Mock Server is the answer.

Postman Local Mock Server

This is a simple javascript package that you can import into your codebase to run a collection as a local server.

Pick the port you want it to run on and supply a collection JSON file and the postman-local-mock-server package will run it for you.

Getting Started

Step 1
Create a collection using Postman (or pick one from the Public API Network).

The only requirement here is that for every request in your collection you need to specify at least one example response with a valid status code.

The mock server will use the combination of paths and headers to determine which example response is the best to return, but you can also control this with some parameters.

Step 2
Install the dependency from npm.

npm install -g @jordanwalsh23/postman-local-mock-server

Step 3
Run the collection.

postman-local --collection <path-to-collection> --port 3555

Step 4
Send some API requests!

You can use any API Client (even #postman) or your application code to hit the endpoints on http://localhost:3555.

The server will automatically respond with the mocked examples you created in your collection.

How do I pick the response I want to come back?

There are 4 optional headers that you can supply in your requests to the local mock server to get it to respond how you want.

x-mock-response-name - Send this with the name of a specific response you want returned.

x-mock-response-code - Send this with the status code you would like returned from the API. If there is a matching example with this status code it will be returned.

x-mock-response-id - Send this with the ID of a specific example response you want returned. This ID is the internal Postman ID so you will need to look at the collection or use Postman's API to find this out.

x-mock-match-request-body - (Boolean, Default: false) If you are using POST/PUT/PATCH requests that have a body, you can use the following header to get the Postman Local Mock Server to match the body on one of your example responses.

Postman supports dynamic response data in mocks, does this?

Yes! If you use some of the faker library fields that Postman supports these will also resolve in the Postman Local Mock Server.

What about collection, environment and global variables?

The library doesn't currently support variables. Maybe in a future release if this is needed.

Does it run pre-request and test scripts?

No. Unfortunately not. If this is needed please raise an issue on the repo.

Feedback/Comments/Questions

Please feel free to create an issue on the repo if you have some feedback.

Thanks!