Skip to content

Usage Examples (v4)

Matthew Herman edited this page May 13, 2019 · 4 revisions

The following examples are for version 4.X.X of the package. If you are still using a previous version, please see Usage Examples (v1), Usage Examples (v2), or Usage Examples (v3).

Creating Imposters

This example shows how to create an HTTP imposter on port 8080. All imposter types are supported except for SMTP.

var client = new MountebankClient();
var imposter = client.CreateHttpImposter(8080);

You can also submit multiple imposters at the same time.

var client = new MountebankClient();
var imposterList = new List<Imposter>();

Adding Stubs to Imposters

Simple Responses

This example shows how to add a stub to our imposter that will return a 400 status code.


A response object can also be returned from the imposter. The ReturnsJson and ReturnsXml methods will serialize the object into their respective formats and automatically set the Content-Type response header.

var obj = new TestObject { Name = "Ten", Value = 10 };
imposter.AddStub().ReturnsJson(HttpStatusCode.OK, obj);

If you would like to return plain text or a body of something other than XML or JSON, use the ReturnsBody method.

Complex Responses If setting up a more complicated response, such as one including headers, the Returns method can be called with a created response object.

var responseFields = new HttpResponseFields
    StatusCode = HttpStatusCode.BadRequest,
    Headers = new Dictionary<string, string> {{ "Location", "http://localhost:4545/customers/123" }}

var response = new IsResponse<HttpResponseFields>(responseFields);


Simple Predicates

Predicates can be specified on a stub as well. The following will return a response object if a request is made to the "/test" path.

imposter.AddStub().ReturnsJson(HttpStatusCode.OK, obj).OnPathEquals("/test");

A specific HTTP method can also be specified on the predicate.

imposter.AddStub().ReturnsStatus(HttpStatusCode.MethodNotSupported).OnPathAndMethodEqual("/test", Method.Post);

Complex Predicates

Similar to responses, a more complicated predicate can be added using the On method.

var complexPredicateFields = new HttpPredicateFields
    Method = Method.Post,
    Path = "/test",
    QueryParameters = new Dictionary<string, string> { { "first", "1" }, { "second", "2" } },
    Headers = new Dictionary<string, string> { { "Accept", "text/plain" } }

var complexPredicate = new EqualsPredicate<HttpPredicateFields>(complexPredicateFields);


Currently, the above method of predicate creation is required to be used for any supported predicate other than "equals".

An alternate predicate constructor exists that will let you specify whether matches should be case sensitive (false by default), define a regex expression to remove prior to matching, or an xpath selector to that can be used to select values from an XML document.

Using Multiple Stubs/Predicates/Responses

Any number of stubs can be added to an imposter. If there are multiple, the stub with the first set of predicates to match the request will be used by mountebank.

Multiple responses/predicates can also be added to a single stub. If a stub has multiple responses, they will be returned in order. In the following example, the first request will get an 200 status code, but the next will receive a 404 status code.


When a stub has multiple predicates, they will be treated as an AND condition. For example:

imposter.AddStub().ReturnsStatus(HttpStatus.OK).OnPathAndMethodEqual("/test", Method.Get);

is equivalent to:

var firstPredicate = new EqualsPredicate<HttpPredicateFields>(new HttpPredicateFields { Path = "/test" });
var secondPredicate = new EqualsPredicate<HttpPredicateFields>(new HttpPredicateFields { Method = Method.Get});


Proxy responses are also supported for all imposter types. A proxy can be created using the ReturnsProxy method of the stub:

var proxyImposter = client.CreateHttpImposter(5000);

var predicateGenerators = new List<MatchesPredicate<HttpBooleanPredicateFields>>
    new MatchesPredicate<HttpBooleanPredicateFields>(new HttpBooleanPredicateFields
        QueryParameters = true

    new System.Uri($""), 
    ProxyMode.ProxyOnce, predicateGenerators);

This will create a proxy to "" using the provided predicate generators. In this case, we are using the HttpBooleanPredicateFields with QueryParameters set to true, which will result in predicates and proxy responses being generated based on the query parameters passed to the proxied site.

You can also use the regular HttpPredicateFields in your predicate generators in order to generate predicates based on specific values.

For more information on responses and predicates, see the mountebank documentation at

Deleting Imposters

All existing imposters can be removed by calling the DeleteAllImposters methods on the client.


To remove a single imposter, use the DeleteImposter method.

const int port = 8080;

Retrieving Imposters

Existing imposters can be retrieved for inspection or mock verification using the protocol-specific retrieval method on the client. For example, to retrieve an HTTP imposter:


If an imposter does not exist on the specified port, an ImposterNotFoundException will be thrown. If an imposter exists, but does not match the expected protocol, an InvalidProtocolException will be thrown.

If mountebank has been run with the --mock flag, the returned object will have its NumberOfRequests and Requests properties populated. The NumberOfRequests property reports how many requests have been made to the imposter and the Requests collection will have specific information about each of those requests.

More Examples

The DocumentationTests.cs file in the MbDotNet.Acceptance.Tests project includes code samples for many of the examples shown in the mountebank documentation.

You can’t perform that action at this time.