End-to-end testing best practices with Postman mock servers

End-to-end (E2E) tests focus on the complete user workflow. This type of testing approach begins from the end user’s perspective and simulates a real-world scenario.

E2E testing is only one type of test that every software system needs. Other types of testing include:

• Unit testing: Ensures that every component in a system works as expected.
• Integration testing: Combines individual software modules and tests them as a group.

Ideally, a software system has many unit tests, some integration tests, and only a few E2E tests. Unit tests are fast, while integration tests are slower, and E2E tests are the slowest of your tests.

E2E testing verifies that all components of a system can run under real-world scenarios. The goal of E2E testing is to simulate a user experience from start to finish. I recommend the fantastic article “The Practical Test Pyramid” by Martin Fowler that gives further insight into the different types of software tests.

The problem with external dependencies

It is a common situation to have dependencies that rely on third-party APIs:

In this diagram, the system sends and/or receives data from a third-party API. Issues arise when you face a dependency like this and you want to perform E2E tests on your system because:

• You can’t control the code of the external API; it belongs to another company or organization.
• You can’t get the contract (for example, an OpenAPI specification) for the third-party API.
• You require a running and accessible server that serves the endpoints you depend on.
• The server must be a staging or testing server.
• You can’t control the quality of the third party’s server.
• You can’t set up the external server to return HTTP 5XX errors for your tests.

To properly test your system, you should be able to mock a third-party API and have it return the appropriate values and responses for your E2E tests. You don’t need an actual external server you can’t control or must rely on for testing.

For example, you want to test what happens when the third-party API returns an HTTP 400 error or what happens if the service has an outage and the API returns an HTTP 500 error. With Postman, you can create mock servers that, together with the Postman API, let you set up a mock server so it returns what you need for your tests. In fact, you can use the Postman API to programmatically manage your mock servers!

Postman mock servers

Postman’s mock servers simulate the behavior of an API server by accepting requests and returning responses. When you create a mock server, Postman returns a public or private URL you can use to make calls. You can use this URL in your system to replace the need for an external server.

A mock server is based on a Postman Collection and its examples. When you make a request to a mock server, Postman evaluates the request’s path, verb, headers, and body. Based on this information, it determines which collection example it should return. To read more about this behavior, see our Postman Learning Center documentation for Mocking with examples.

It is important to note the following about Postman’s mock servers:

• A mock server actually mocks a Postman Collection.
• A mock server’s collection must include examples.
• A mock server analyzes a request and, based on the request, determines the example response it should return.

Use a mocking strategy with Postman and the Postman API

When mocking with an external service, you want the third-party’s service to behave in different ways, depending on the test. For example, if you want to mock a paginated endpoint, the possible response behaviors may include:

• The endpoint returns an empty list.
• The endpoint returns a list with fewer elements than the page size.
• The endpoint returns a full list and pagination information.
• The endpoint fails with an HTTP 401, 403, and/or a 500 error.

To keep it simple, imagine your API uses the external GET /items/{id} paginated endpoint. How can you set up your mock server so you can test for all possible behaviors without changing your API’s code?

Given that mock servers calculate the responses based on collection examples, you should be able to change the collection linked to the mock server. Using the Postman API, you can create the examples you need for any scenario before performing the test.

Using this information, let’s set up a Postman Collection to set up our E2E testing.

Step 1. Create a mock server with collections and examples

First, you’ll need to create a mock server and its sample collection in Postman:

1. Make sure that you have a valid Postman API key. You need it to use the Postman API.
2. Create your sample collection. Add the GET /items/{id} request, then add a basic example to the request. The example doesn’t need to be correct or valid; you just need it for the mock server you are setting up.
3. Create a mock server and link it to the sample collection you just created.
4. Use the mock server’s URL as the base URL for the third-party service in your API server code’s settings for your E2E environment. This lets you use the mock server’s URL in the instance of your API (usually a Docker instance) that’s dedicated to running E2E tests.
5. Create a new Postman Collection with response examples for each test scenario. For this example, you’ll create the following:
   • A collection with a request and an example that returns an HTTP 200 response with a JSON body.
   • A collection with request and example that returns an HTTP 500 error and an empty body.

Step 2. Create the E2E test collection

Create a new folder in your Postman Collection for each E2E test:

Each test folder contains the following:

• The mock server’s E2E test setup (for example, Mock Setup).
• The E2E tests.

Step 3. Create the mock server setup folder in the E2E test collection

Create the Mock Setup folder in your first mock server test folder:

This folder contains requests that set up the mock server collection with the responses your tests will receive. You can use the Postman API and the collections created to set up the mock server collection.

Step 4. Create collection variables

Create a collection variable using the IDs of the collections you created in Step 1. You will reference these variables later.

Step 5. Create the mock server’s requests

In your Mock Setup folder, create two requests: a GET request to read your collection and a PUT request to overwrite and set the examples you need for your E2E tests.

The GET request

The GET request, Get 200 response collection, reads the test scenario collection’s data using the Postman API’s Get a collection endpoint. You will also use a test in the request’s Tests tab to set the collection’s test data as a collection variable:

var jsonData = pm.response.json();
pm.collectionVariables.set("collection_contents", JSON.stringify(jsonData));

The PUT request

The PUT request, Overwrite mock server collection, runs the Postman API’s Update a collection endpoint on the mock server collection. It uses the collection data you fetched with the previous GET request to set the examples for the folder’s E2E test.

The request uses collection variables to reference the IDs and contents of the collections you previously created. This overwrites the collection the mock server uses with the examples you need for your E2E tests.

Next steps

Once the mock server collection contains all the examples you need for your E2E test behavior, the rest of the requests in the E2E folder will run the actual tests. The mock server will behave as the specific scenario collection until you change the collection to another scenario, following the same strategy.

You can follow the same strategy for your remaining E2E test folders, setting up the mock server at the beginning, and then running the rest of the tests.

Get started with the Postman API

This is just one of the ways you can use the Postman API to help you automate your testing processes. Explore the Postman API documentation and let us know in a comment below if you discover any other great ways to automate your test with the Postman API!