Configuration Syntax for Mockintosh
The Config YAML
The mock server is defined via a simple and intuitive YAML file. You can easily pass this configuration of the mock server to your colleagues to explain what kind of response is expected from the mock service.
templatingEngine: Handlebars
services:
- name: Mock for Service1
hostname: service1.example.com
port:8001
endpoints:
- path: "/users"
method: GET
response:
headers:
Content-Type: "application/json. charset=UTF-8"
useTemplating: true
body: "@templates/users.json.hbs"
- path: "/users/{{ id }}
method: GET
response:
headers:
Content-Type: "application/json; charset=UTF-8"
useTemplating: true
body: "@templates/user.json.hbs"
- name: Mock for Service2
hostname: service2.example.com
port: 8002
endpoints:
- path: "/companies"
method: POST
response:
headers:
Content-Type: "application/json; charset=UTF-8"
useTemplating: true
body: "@templates/companies.json.hbs
}
The Services Field
Every config.yaml
must have a services field to define a list of services. It should define at least one service.
- The port field defines what port should the service listen to.
- The endpoints field defines a list of endpoints for the given service.
- The path field defines what path the endpoint should match into.
- The response field is the response that will be returned from the given endpoint.
services:
- port: 8081 # the port to listen
endpoints: # list of endpoints
- path: "/example" # path matching criteria
response: "hello world" # response body
Simple hello-world
Let's run mockintosh 01.yaml
and visit localhost:8081/example
.
We can see that hello world
is returned as the response:
Responding with a JSON
In this next example, the response is detailed into other fields rather than being a plain string.
services:
- port: 8081
endpoints:
- path: "/example"
response:
headers:
Content-Type: "application/json"
body: '{"message": "hello world"}' # response body
Headers field here is a list of key value pairs to describe the response headers.
So in this example, the Content-Type: "application/json"
header will be included into each response with this endpoint.
The Body field describes the response text. In this case we're responding with a JSON file.
If we visit localhost:8081/example
we can see that message: hello world
is returned as the response.
Responding with a Status Code
It's possible to set the status code of the response to any HTTP status code including 400 and 500 class error codes.
services:
- port: 8081
endpoints:
- path: "/example"
response:
status: 403 # status code response
Content-Type: "application/json"
body: '{"message": "hello world"}'
If we visit localhost:8081/example
we can see that 403
is the response status.
Status
The status field can be more than just an integer. It can take special RST and FIN string values to simulate the behavior of sudden TCP connection reset or close.
services:
- port: 8081
endpoints:
- path: "/reset"
response:
status: "RST" # RST string
- path: "/close"
response:
status: "FIN" # FIN string
We can visit localhost:8081/reset
and localhost:8081/close
to experience the TCP connection errors.
Schema Validation error
Using fields that are not defined in the syntax or an incomplete usage throws a JSON Schema Validation error, much like a syntax error in programming languages.
This error describes the problem in detail so it's easy to understand what's wrong with the config file.
jsonschema.exceptions.ValidationError: [] is too short
Templating
Mockintosh supports two different templating engines: Handlebars and Jinja2. Handlebars is default. Templating is possible in various places including request matching and responses.
services:
- port: 8081
endpoints:
- path: "/example/{{ id }}"
response: "id is {{ id }} and a random integer: {{ random.int 1 100}}"
For a request like /example/3
above, we see at localhost:8081/example/3
the response id is 3 and a random integer.
templatingEngine Field
It's possible to set the templating engine to Jinja2 using the templatingEngine
field.
templatingEngine: Jinja2 # set templating engine
services:
- port: 8081
endpoints:
- path: "/example/{{ id }}"
response: "id is {{ id }} and a random integer: {{ random.int 1 100}}"
You can see how the syntax is changed into Jinja2 syntax. If you make a syntax error in templating, you get a not rendered result and a warning in the standard output:
id is {{ id }} and a random integer: {{ random.int 1 100 }}
Globals Field
With the globals
field at the top you can define headers that will be set for all responses defined in the configuration file.
globals: # globals field
headers:
Content-Type: "application/json"
services:
- port: 8081
endpoints:
- path: "/example"
response:
status: 200
body: '{"message": "hello world"}'
- port: 8082
endpoints:
- path: "/example2"
response:
status: 202
body: '{"message": "hello universe"}'
A common header like Content-Type: "application/json"
can be returned with all responses without the need of redefining it for each response. If we visit localhost:8082/example2
we can see all responses:
Support
You can view these examples in action in this video, and learn more at Mockintosh and UP9. Join our community Slack at up9.slack.com.