Mmock is a testing and fast prototyping tool for developers:

Easy and fast HTTP mock server.

• Download Mmock
• Create a mock definition.
• Configure your application endpoints to use Mmock
• Receive the expected responses
• Inspect the requests in the web UI
• Release it to a real server

Built with Go - Mmock runs without installation on multiple platforms.

Features

• Easy mock definition via JSON or YAML
• Variables in response (fake or request data)
• Route patterns may include named parameters (/hello/:name)
• Glob matching ( * hello * )
• Match request by method, URL params, query string, headers, cookies and bodies.
• Mock definitions hot replace (edit your mocks without restart)
• Web interface to view requests data (method,path,headers,cookies,body,etc..)
• Stateful behaviour with scenarios
• Verifying
• Proxy mode
• Fine grain log info in web interface
• Real-time updates using WebSockets
• Priority matching
• Crazy mode for failure testing
• Public interface auto discover
• Lightweight and portable
• No installation required

Example

Mock definition file example:

{
	"request": {
		"method": "GET",
		"path": "/hello/*"
	},
	"response": {
		"statusCode": 200,
		"headers": {
			"Content-Type":["application/json"]
		},
		"body": "{\"hello\": \"{{request.query.name}}, my name is {{fake.FirstName}}\"}"
	}
}

Or

---
request:
  method: GET
  path: "/hello/*"
response:
  statusCode: 200
  headers:
    Content-Type:
    - application/json
  body: '{"hello": "{{request.query.name}}, my name is {{fake.FirstName}}"}'

You can see more complex examples here.

Getting started

Either:

Run it from Docker using the provided Dockerfile or from Docker Hub

docker image pull jordimartin/mmock
docker run -v YOUR_ABS_PATH:/config -p 8082:8082 -p 8083:8083 jordimartin/mmock

Or run mmock locally from the command line. (Requires Go 1.8 at least)

go get github.com/jmartin82/mmock/...
mmock -h

To configure Mmock, use command line flags described in help.

    Usage of ./mmock:
	  -config-path string
		Mocks definition folder (default "execution_pathconfig")
	  -console
		Console enabled  (true/false) (default true)
	  -console-ip string
		Console server IP (default "public_ip")
	  -console-port int
		Console server Port (default 8082)
 	  -request-storage-capacity int
		Request storage capacity (0 = infinite) (default 100)
	  -results-per-page uint
		Number of results per page (default 25)
	  -server-ip string
		Mock server IP (default "public_ip")
	  -server-port int
		Mock server Port (default 8083)
	  -server-statistics
		Mock server sends anonymous statistics (default true)
	  -server-tls-port int
		Mock server TLS Port (default 8084)
	  -tls-path string
		TLS config folder (server.crt and server.key should be inside) (default "execution_path/tls")

The default logging level is INFO, but you can change it by setting the environment variable LOG_LEVEL to one of the following:

• CRITICAL
• ERROR
• WARNING
• NOTICE
• INFO
• DEBUG

Mock

Mock definition:

{
	"description": "Some text that describes the intended usage of the current configuration",
	"request": {
		"host": "example.com",
		"method": "GET|POST|PUT|PATCH|...",
		"path": "/your/path/:variable",
		"queryStringParameters": {
			"name": ["value"],
			"name": ["value", "value"]
		},
		"headers": {
			"name": ["value"]
		},
		"cookies": {
			"name": "value"
		},
		"body": "Expected Body"
	},
	"response": {
		"statusCode": "int (2xx,4xx,5xx,xxx)",
		"headers": {
			"name": ["value"]
		},
		"cookies": {
			"name": "value"
		},
		"body": "Response body"
	},
	"callback": {
		"method": "GET|POST|PUT|PATCH|...",
		"url": "http://your-callback/",
		"delay": "string (response delay in s,ms)",
		"headers": {
			"name": ["value"]
		},
		"body": "Response body"
	},
	"control": {
		"scenario": {
			"name": "string (scenario name)",
			"requiredState": [
				"not_started (default state)",
				"another_state_name"
			],
			"newState": "new_stat_neme"
		},
		"proxyBaseURL": "string (original URL endpoint)",
		"delay": "string (response delay in s,ms)",
		"crazy": "bool (return random 5xx)",
		"priority": "int (matching priority)",
		"webHookURL" : "string (URL endpoint)"
	}
}

Request

A core feature of Mmock is the ability to return canned HTTP responses for requests matching criteria.

• host: Request http host. (without port)
• method: Request http method. It allows more than one separated by pipes "|" Mandatory
• path: Resource identifier. It allows :value matching. Mandatory
• queryStringParameters: Array of query strings. It allows more than one value for the same key.
• headers: Array of headers. It allows more than one value for the same key. Case sensitive!
• cookies: Array of cookies.
• body: Body string. It allows * pattern. It also supports regular expressions for field values within JSON request bodies.

In case of queryStringParameters, headers and cookies, the request can be matched only if all defined keys in mock will be present with the exact or glob value.

Glob matching is available for:

• host
• path
• headers
• cookies
• query strings
• body

Query strings and headers support also global matches (*) in the header/parameter name. For example:

		"headers": {
			"Custom-Header-*": [
				"partial val*"
			]
		}

Regexp matching is available for:

• body
• query strings

See https://pkg.go.dev/regexp/syntax for regexp syntax

Response (Optional on proxy call)

• statusCode: Response status code
• headers: Array of headers. It allows more than one value for the same key and vars.
• cookies: Array of cookies. It allows vars.
• body: Body string. It allows vars.

Callback (Optional)

This is used to have mmock make an API request after receiving the mocked request.

• delay: Delay before making the callback
• url: URL to make a request to
• method: Request http method
• headers: Array of headers. It allows more than one value for the same key.
• body: Body string. It allows vars.
• timeout: Duration to allow the callback to respond (default 10s)

Control (Optional)

• scenario; A scenario is essentially a state machine whose states can be arbitrarily assigned.
• proxyBaseURL: If this parameter is present, it sends the request data to the BaseURL and resend the response to de client. Useful if you don't want mock a the whole service. NOTE: It's not necessary fill the response field in this case.
• delay: Delay the response. Simulate bad connection or bad server performance.
• crazy: Return random server errors (5xx) in some request. Simulate server problems.
• priority: Set the priority to avoid match in less restrictive mocks. Higher, more priority.
• webHookURL: After any match if this option is defined it will notify the match to the desired endpoint.

Variable tags

You can use variable data in response. The variables will be defined as tags like this {{nameVar}}

• URI
• description

Request data: Use them if you want to add request data in your response.

• request.scheme
• request.hostname
• request.port
• request.path (full path)
• request.path."key"
• request.query."key"
• request.cookie."key"
• request.fragment
• request.url (full url with scheme, hostname, port, path and query parameters)
• request.authority (return scheme, hostname and port (optional))
• request.body

You can extract information from the request body too, using a dot notation path:

• request.body."key" (support for application/json, application/xml and application/x-www-form-urlencoded requests)
• request.body."deep"."key" (support for application/json, application/xml requests)

Quick overview of the path syntax available to extract values form the request: https://github.com/tidwall/gjson#path-syntax

You can also use "regex" and "concat" commands to complement GJson query:

• request.body."deep"."key".regex() (support for application/json, application/xml requests)
• request.body."deep"."key".concat() (support for application/json, application/xml requests)
• request.body."deep"."key".regex().concat() (support for application/json, application/xml requests)

Example request data:

{
  "email": "hilari@sapo.pt",
  "age": 4,
  "uuid":"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
  "discarded": "do not return"
}

Example config mock data:

{
  "email": "{{request.body.email.regex((\@gmail.com))}}",
  "age": {{request.body.age}},
  "uuid": "{{request.body.uuid.regex(\b([0-9a-zA-Z]{4})\b).concat(-878787)}}",
  "discarded": "{{request.body.discarded.concat(, Please!)}}"
}

Example response data:

{
  "email": "",
  "age": 4,
  "uuid": "2307-878787",
  "discarded": "do not return, Please!"
}

External streams: Perfect for embedding big payloads or getting data from another service.

• file.contents(FILE_PATH)
• http.contents(URL)

Fake data: Useful to provide a more rich and random response.

• fake.Brand
• fake.Character
• fake.Characters
• fake.CharactersN(n)
• fake.City
• fake.Color
• fake.Company
• fake.Continent
• fake.Country
• fake.CreditCardVisa
• fake.CreditCardMasterCard
• fake.CreditCardAmericanExpress
• fake.Currency
• fake.CurrencyCode
• fake.Day
• fake.Digits
• fake.DigitsN(n)
• fake.EmailAddress
• fake.FirstName
• fake.FullName
• fake.LastName
• fake.Gender
• fake.Hex(n) - random hexidecimal string n characters in length
• fake.IPv4
• fake.Language
• fake.Model
• fake.Month
• fake.MonthShort
• fake.MonthNum
• fake.Year
• fake.Paragraph
• fake.Paragraphs