Skip to main content
This guide walks you through starting MockServer, creating an expectation, making a request, and verifying it was received.
1

Start MockServer

Run MockServer as a Docker container, exposed on port 1080:
docker run -d --rm -p 1080:1080 mockserver/mockserver
MockServer is now listening at http://localhost:1080. A single port handles both HTTP and HTTPS.
If you prefer not to use Docker, see Running MockServer for other deployment options including the standalone JAR, Maven plugin, npm module, and JUnit integrations.
2

Create an expectation

An expectation tells MockServer what requests to match and what response to return. Create one using the REST API, the Java client, or the JavaScript client.
curl -s -X PUT http://localhost:1080/mockserver/expectation \
  -H "Content-Type: application/json" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/api/books"
    },
    "httpResponse": {
      "statusCode": 200,
      "headers": {
        "Content-Type": ["application/json"]
      },
      "body": "[{\"id\": 1, \"title\": \"Effective Java\"}]"
    }
  }'
MockServer responds with 201 Created when the expectation is registered successfully.
3

Make a request to the mock

Send a request to MockServer on the path you configured:
curl -s http://localhost:1080/api/books
MockServer matches the request against your expectation and returns the configured response:
[{"id": 1, "title": "Effective Java"}]
4

Verify the request was received

After your test runs, verify that MockServer received the expected request. Use the REST API or a client SDK.
curl -s -X PUT http://localhost:1080/mockserver/verify \
  -H "Content-Type: application/json" \
  -d '{
    "httpRequest": {
      "method": "GET",
      "path": "/api/books"
    },
    "times": {
      "atLeast": 1
    }
  }'
MockServer returns 202 Accepted if the verification passes, or a 406 Not Acceptable with a description of what was received if it fails.
The request log is only captured when the log level is INFO or more verbose. MockServer defaults to INFO, so verification works out of the box.

​
Next steps

Creating expectations

Learn all the ways to match requests and define responses, including callbacks and forwarding.

Request matchers

Match on headers, cookies, query parameters, body content, and more.

OpenAPI mocking

Auto-generate expectations from an OpenAPI v3 specification.

Verification

Assert request sequences and counts after your tests run.