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: First_HelloWorld

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:

Hello_Universe

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.