MockResponsePlugin

Simulates responses.

Screenshot of a command prompt with Dev Proxy simulating response for a request to GitHub API.

Configuration example

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/rc.schema.json",
  "plugins": [
    {
      "name": "MockResponsePlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/DevProxy.Plugins.dll",
      "configSection": "mocksPlugin"
    }
  ],
  "mocksPlugin": {
    "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.schema.json",
    "mocksFile": "mocks.json"
  }
}

Configuration properties

Property Description Default
mocksFile Path to the file containing mock responses mocks.json
blockUnmockedRequests Return 502 Bad Gateway response for requests that aren't mocked false

Command line options

Name Description Default
-n, --no-mocks Disable loading mock requests false
--mocks-file Path to the file containing mock responses -

Mocks file examples

Following are examples of mock objects.

Respond with body

Response to a request with a 200 OK response and a JSON body.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/me",
        "method": "GET"
      },
      "response": {
        "body": {
          "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
          "businessPhones": ["+1 412 555 0109"],
          "displayName": "Megan Bowen",
          "givenName": "Megan",
          "jobTitle": "Auditor",
          "mail": "MeganB@M365x214355.onmicrosoft.com",
          "mobilePhone": null,
          "officeLocation": "12/1110",
          "preferredLanguage": "en-US",
          "surname": "Bowen",
          "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
          "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
        },
        "headers": [
          {
            "name": "content-type",
            "value": "application/json; odata.metadata=minimal"
          }
        ]
      }
    }
  ]
}

Respond with error

Respond to a request with a 404 Not Found response.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/me/photo",
        "method": "GET"
      },
      "response": {
        "statusCode": 404
      }
    }
  ]
}

Respond with binary data

Respond to a request with a binary image loaded from a file on disk.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/users/*/photo/$value",
        "method": "GET"
      },
      "response": {
        "body": "@picture.jpg",
        "headers": [
          {
            "name": "content-type",
            "value": "image/jpeg"
          }
        ]
      }
    }
  ]
}

Respond on nth request

Respond only to the second matching request. Dev Proxy passes other requests to the API.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/external/connections/*/operations/*",
        "method": "GET",
        "nth": 2
      },
      "response": {
        "statusCode": 200,
        "body": {
          "id": "1.neu.0278337E599FC8DBF5607ED12CF463E4.6410CCF8F6DB8758539FB58EB56BF8DC",
          "status": "completed",
          "error": null
        }
      }
    }
  ]
}

Respond matching the request body

Respond to a request that contains a specific string in the body.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://login.microsoftonline.com/fa15d692-e9c7-4460-a743-29f29522229/oauth2/v2.0/token",
        "method": "POST",
        "bodyFragment": "scope=https%3A%2F%2Fapi.contoso.com%2FDocuments.Read"
      },
      "response": {
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json; charset=utf-8"
          }
        ],
        "body": {
          "token_type": "Bearer",
          "expires_in": 3599,
          "ext_expires_in": 3599,
          "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSU..."
        }
      }
    }
  ]
}

Mirror request data in response

Respond with data that mirrors values from the request body using @request.body.* placeholders.

File: mocks.json

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v4.0.0/mockresponseplugin.mocksfile.schema.json",
  "mocks": [
    {
      "request": {
        "url": "https://graph.microsoft.com/v1.0/users",
        "method": "POST"
      },
      "response": {
        "statusCode": 201,
        "body": {
          "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
          "id": "12345678-1234-1234-1234-123456789abc",
          "businessPhones": "@request.body.businessPhones",
          "displayName": "@request.body.displayName",
          "givenName": "@request.body.givenName",
          "jobTitle": "@request.body.jobTitle",
          "mail": "@request.body.mail",
          "userPrincipalName": "@request.body.userPrincipalName",
          "accountEnabled": "@request.body.accountEnabled",
          "createdDateTime": "2024-01-15T10:30:00Z"
        },
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json; odata.metadata=minimal"
          },
          {
            "name": "Location",
            "value": "https://graph.microsoft.com/v1.0/users/12345678-1234-1234-1234-123456789abc"
          }
        ]
      }
    }
  ]
}

Given the following request:

POST https://graph.microsoft.com/v1.0/users
Content-Type: application/json

{
  "displayName": "Megan Bowen",
  "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
  "accountEnabled": true,
  "givenName": "Megan",
  "surname": "Bowen",
  "jobTitle": "Product Manager"
}

The response is:

HTTP/1.1 200 Connection Established
Content-Length: 0

HTTP/1.1 201 Created
Cache-Control: no-store
x-ms-ags-diagnostic: 
Strict-Transport-Security: 
request-id: 12345678-1234-1234-1234-123456789abc
client-request-id: 12345678-1234-1234-1234-123456789abc
Date: 9/10/2025 10:28:35 AM
Content-Type: application/json; odata.metadata=minimal
Location: https://graph.microsoft.com/v1.0/users/12345678-1234-1234-1234-123456789abc
OData-Version: 4.0
Content-Length: 648

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
  "id": "12345678-1234-1234-1234-123456789abc",
  "businessPhones": null,
  "displayName": "Megan Bowen",
  "givenName": "Megan",
  "jobTitle": "Product Manager",
  "mail": null,
  "mobilePhone": null,
  "officeLocation": null,
  "preferredLanguage": null,
  "surname": "Bowen",
  "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
  "accountEnabled": true,
  "createdDateTime": "2024-01-15T10:30:00Z",
  "department": null,
  "companyName": null,
  "city": null,
  "country": null,
  "postalCode": null,
  "state": null,
  "streetAddress": null,
  "usageLocation": null
}

Mocks file properties

Property Description Required
request Request object that defines the request to respond to yes
response Response object that defines the response to return yes

Request object

Each request has the following properties:

Property Description Required Default value Sample value
url Absolute URL to an API endpoint to respond to yes https://jsonplaceholder.typicode.com/posts
method HTTP verb used to match request with url no GET GET
nth Respond only to the nth intercepted request that matches the mock's method, url, and bodyFragment no 2
bodyFragment A string that should be present in the request body no foo

Remarks

Use asterisk (*) in the url property if you want to match any series of characters in the URL. For example, https://jsonplaceholder.typicode.com/* matches https://jsonplaceholder.typicode.com/posts and https://jsonplaceholder.typicode.com/comments. On runtime, Dev Proxy converts each * into a regular expression .*.

Dev Proxy ignores case when matching the url property against the request URL. For example, a mock for https://jsonplaceholder.typicode.com/Posts matches a request to https://jsonplaceholder.typicode.com/posts. If you define multiple mocks for the same method with URLs that differ only in casing, Dev Proxy uses the first matching mock.

When defining mocks, place the most specific mocks first. For example, if you have two mocks, one for https://jsonplaceholder.typicode.com/posts and one for https://jsonplaceholder.typicode.com/*, place the first mock first. Otherwise, Dev Proxy matches the second mock first and return the response for https://jsonplaceholder.typicode.com/* for all requests.

Use the nth property if you need to send a different response to the same request URL. For example, use it to simulate a long-running operation. The first time you call the API, it returns a response with an inprogress message. The second time you call the API, it returns a response with the completed message. Dev Proxy counts every intercepted request that matches the mock's method, url, and bodyFragment, whether or not it returns a mock response for it. You don't need a fallback mock for the same URL: if no mock applies to a request, Dev Proxy passes it to the API. For more information about the nth property, see Mock nth request.

Using the bodyFragment property, you can match requests based on the body content. For example, if you want to match requests that contain the foo string in the body, set the bodyFragment property to foo. Dev Proxy uses bodyFragment only for requests other than GET.

Response object

Each response has the following properties:

Property Description Required Default value Sample value
body Body to send as the response to the request no empty { "foo": "bar" }
statusCode Response HTTP status code no 200 404
headers Array of headers to include in the response no empty [{ name: "content-type", "value": "application/json" }]

Remarks

If you set the body property to a JSON object or array, Dev Proxy serializes it to JSON. If you set it to a string, Dev Proxy sends the string as-is, without surrounding quotes. Use a string body to return plain text, HTML, XML, or other non-JSON content. Because Dev Proxy defaults the content-type header to application/json, also set the content-type header to match your content, for example text/plain.

If you want to return binary data, set the body property to a string value that starts with @ followed by file path relative to the mocks file. For example, @picture.jpg returns the image stored in the picture.jpg file in the same directory as the mocks file.

To mirror request data in the response, use @request.body.* placeholders in the response body. For example, @request.body.displayName returns the value of the displayName property from the request body. This feature works with nested objects and arrays, allowing you to create dynamic responses that reflect the incoming request data. The placeholder replacement supports various JSON value types including strings, numbers, booleans, and complex objects.

Next step

Mock responses

  • Last updated on