Mockaco is an HTTP-based API mock server with fast setup.

• Simple JSON-based configuration
• Pure C# scripting - you don't need to learn a new specific language or API to configure your mocks
• Fake data generation - built-in fake data generation
• Callback support - trigger another service call when a request hits your mocked API
• State support - stateful mock support allow a mock to be returned based on a global variable previously set by another mock
• Portable - runs in any .NET Core compatible environment

• Get Started
  • Running the application
  • Creating a request/response template
  • Sending a request and get the mocked response
• Request Template Matching
  • Method attribute
  • Route attribute
  • Condition attribute
• Response Template
  • Delay attribute
  • Status attribute
  • Headers attribute
  • Body attribute
  • Indented attribute
• Callback Template
  • Headers attribute
  • Body attribute
  • Delay attribute
  • Timeout attribute
  • Indented attribute
• Scripting
  • Example: Accessing request data
  • Example: Generating fake data

You can run Mockaco from the official Docker image (replace /your/folder with an existing directory of your preference):

$ docker run -it --rm -p 5000:80 -v /your/folder:/app/Mocks natenho/mockaco

Or using .NET Core dotnet CLI, you can run the latest binaries:

$ dotnet Mockaco.dll

Or your can run it directly from sources:

$ git clone https://github.com/natenho/Mockaco.git
$ cd Mockaco\src\Mockaco
$ dotnet run

Create a file named PingPong.json under Mocks folder:

{
  "request": {
	"method": "GET",
	"route": "ping"
  },
  "response": {
	"status": "OK",
	"body": {
	  "response": "pong"
	}
  }
}

This example contains a request/response template, meaning "Whenever you receive a GET request in the route /ping, respond with status OK and the body { "response": "pong" }"

curl -iX GET http://localhost:5000/ping

HTTP/1.1 200 OK
Date: Wed, 13 Mar 2019 00:22:49 GMT
Content-Type: application/json
Server: Kestrel
Transfer-Encoding: chunked

{
	"response": "pong"
}

Use the request attribute to provide the necessary information for the engine to decide which response will be returned. All criteria must evaluate to true to produce the response of a given template.

Any request with the matching HTTP method will return the response. Supported HTTP methods: GET, PUT, DELETE, POST, HEAD, TRACE, PATCH, CONNECT, OPTIONS. If omitted, defaults to GET.

{
  "request": {
	"method": "GET"
  },
  "response": {
	"status": "OK"
  }
}

Any request with the matching route will return the response. Any AspNet route template is supported.

If omitted, empty or null, defaults to base route (/).

{
  "request": {
	"route": "customers/{id}/accounts/{account_id}"
  },
  "response": {
	"status": "OK"
  }
}

Any condition that evaluates to true will return the response. The condition is suitable to be used with C# scripting.

If omitted, empty or null, defaults to true.

{
  "request": {
	"condition": "<#= DateTime.Now.Second % 2 == 0 #>"
  },
  "response": {
	"status": "OK"
  }
}

Defines a minimum response time in milliseconds.

If omitted, empty or null, defaults to 0.

{
  "request": {
	"method": "GET"
  },
  "response": {
	"delay": 4000,
	"status": "OK"
  }
}

Sets the HTTP status code for the response. Can be a string or a number, as defined in System.Net.HttpStatusCode enumeration.

If omitted, empty or null, defaults to OK (200).

{
  "request": {
	"method": "GET"
  },
  "response": {    
	"status": "Forbidden"
  }
}

Sets any HTTP response headers.

{
  "request": {
	"method": "GET"
  },
  "response": {    
	"status": "OK",
	"headers": {
		"X-Foo": "Bar"
	}
  }
}

Sets the HTTP response body.

If omitted, empty or null, defaults to empty.

The Content-Type header is used to process output formatting for certain MIME types. If omitted, defaults to application/json.

{
  "request": {
	"method": "GET"
  },
  "response": {    
	"status": "OK",
	"body": {
	  "foo": "Bar"
	}
  }
}

See also:

• Mocking XML responses
• Mocking Binary/Raw responses

Sets the response body indentation for some structured content-types. If ommited, defaults to true.

{
  "request": {
	"method": "GET"
  },
  "response": {    
	"status": "OK",
	"body": {
	  "this": "json content",
	  "is": "supposed to be",
	  "in": "the same line"
	},
	"indented": false
  }
}

Result:

curl -iX GET http://localhost:5000

HTTP/1.1 200 OK
Date: Wed, 31 Jul 2019 02:57:30 GMT
Content-Type: application/json
Server: Kestrel
Transfer-Encoding: chunked

{"this":"json content","is":"supposed to be","in":"the same line"}

Calls another API whenever a request arrives.

{
  "request": {
	"method": "GET"
  },
  "response": {
	"status": "OK",
	"body": {
	  "currentTime": "<#= DateTime.Now.ToString() #>"
	}
  },
  "callback": {
	"method": "POST",
	"timeout": 2000,
	"headers": {		
		"X-Foo": "Bar"
	},
	"body": {
		"message": "The response was <#= Response.Body["currentTime"]?.ToString() #>"
	},
	"url": "https://postman-echo.com/post",
	"delay": 5000
  }
}

Sets any HTTP callback request headers.

Sets the HTTP callback request body.

If omitted, empty or null, defaults to empty.

The Content-Type header is used to process output formatting for certain MIME types. If omitted, defaults to application/json.

The time to wait after a response before performing the callback.

Defines a time in milliseconds to wait the callback response before cancelling the operation.

Sets the callback body indentation for some structured content-types. If ommited, defaults to true.

Every part of the template file is scriptable, so you can add code to programatically generate parts of the template.

Use C# code surrounded by <#= and #>.

The template code and generation will run for each request.

It's possible to access request data within the response template. In the same way, response data can be used within the callback request template.

The scripts are compiled and executed via Roslyn.

{
  "request": {
	"method": "GET"
  },
  "response": {
	"status": "OK",
	"body": {
	  "currentYear": "<#= DateTime.Now.Year #>"
	}
  }
}

The code tag structure resembles T4 Text Template Engine. In fact, this project leverages parts of T4 engine code to parse mock templates.

There is a Request object available to access request data.

{
  "request": {
	"method": "PUT",
	"route": "customers/{id}"
  },
  "response": {
	"status": "OK",
	"body": {
	  "url": "<#= Request.Url?.ToString() #>",
	  "customerId": "<#= Request.Route["id"]?.ToString() #>",
	  "acceptHeader": "<#= Request.Header["Content-Type"]?.ToString() #>",
	  "queryString": "<#= Request.Query["dummy"]?.ToString() #>",
	  "requestBodyAttribute": "<#= Request.Body["address"]?[0]?.ToString() #>"
	}
  }
}

There is a Faker object available to generate fake data.

{
  "request": {
	"method": "GET"
  },
  "response": {
	"status": "OK",
	"body": {
	  "id": "<#= Faker.Random.Guid() #>",
	  "fruit": "<#= Faker.PickRandom(new[] { "apple", "banana", "orange", "strawberry", "kiwi" }) #>",
	  "recentDate": <#= JsonConvert.SerializeObject(Faker.Date.Recent()) #>
	}
  }
}

The built-in fake data is generated via Bogus. The faker can also generate localized data using Accept-Language HTTP header. Defaults to en (english) fake data.

Icon made by Freepik from www.flaticon.com is licensed by CC 3.0 BY