File-based configuration

File-based configuration lets you define stubs in a YAML file and load them at startup — without writing any Kotlin code.

Minimal example

1stubs:
2  - name: ping
3    method: GET
4    path: /ping
5    response:
6      body: '{"response":"Pong"}'
7      status: 200

Load the file and start the server:

1val mokksy = Mokksy().start()
2mokksy.loadStubsFromFile("/path/to/stubs.yaml")

1Mokksy mokksy = Mokksy.create().start();
2mokksy.loadStubsFromFile("/path/to/stubs.yaml");

Stub fields

Field	Required	Default	Description
`name`	no	—	Optional identifier shown in logs and error messages
`method`	no	`GET`	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`
`path`	yes	—	Exact request path to match
`match`	no	—	Additional matching criteria (see below)
`response`	yes	—	Response definition

Matching criteria

1match:
2  bodyContains:
3    - '"userId":"42"'       # request body must contain this string
4    - '"type":"order"'      # multiple strings — all must match
5  headers:
6    Authorization: Bearer token123   # request must carry this header value
7    Content-Type: application/json

Response fields

Field	Required	Default	Description
`type`	no	`plain`	`plain`, `sse`, or `stream`
`body`	no	—	Response body (`plain` type only)
`status`	no	`200`	HTTP status code
`headers`	no	—	Response headers as a map
`delayMs`	no	`0`	Delay before the response is sent (milliseconds)
`chunks`	yes*	—	Ordered list of chunks (`sse` and `stream` types)
`delayBetweenChunksMs`	no	`0`	Delay between chunks (milliseconds)
`contentType`	no	—	Override content type for `stream` responses

* Required when type is sse or stream.

Response types

Plain response

 1stubs:
 2  - name: create-order
 3    method: POST
 4    path: /orders
 5    match:
 6      bodyContains:
 7        - '"product":"widget"'
 8    response:
 9      body: '{"orderId":"abc-123"}'
10      status: 201
11      headers:
12        Location: /orders/abc-123
13      delayMs: 50

Server-Sent Events (SSE)

 1stubs:
 2  - name: order-updates
 3    method: POST
 4    path: /orders/stream
 5    response:
 6      type: sse
 7      chunks:
 8        - '{"status":"processing"}'
 9        - '{"status":"shipped"}'
10        - '{"status":"delivered"}'
11      delayBetweenChunksMs: 100

The response content type is automatically set to text/event-stream; charset=UTF-8.

Plain text stream

 1stubs:
 2  - name: data-feed
 3    method: GET
 4    path: /feed
 5    response:
 6      type: stream
 7      chunks:
 8        - "chunk-one\n"
 9        - "chunk-two\n"
10        - "chunk-three\n"
11      contentType: text/plain; charset=UTF-8
12      delayBetweenChunksMs: 50

Loading the config

Explicit path

1val mokksy = Mokksy().start()
2mokksy.loadStubsFromFile("/app/stubs.yaml")  // absolute path
3mokksy.loadStubsFromFile("stubs.yaml")       // relative to working directory

1Mokksy mokksy = Mokksy.create().start();
2mokksy.loadStubsFromFile("/app/stubs.yaml");  // absolute path
3mokksy.loadStubsFromFile("stubs.yaml");       // relative to working directory

Environment variable or system property

loadStubsFromEnv() checks MOKKSY_CONFIG first, then the -Dmokksy.config system property. When either is set, start() loads the stubs automatically — you do not need to call loadStubsFromEnv() explicitly in that case.

1// explicit load — useful when MOKKSY_CONFIG is not in the environment
2val mokksy = Mokksy().start()
3mokksy.loadStubsFromEnv()

1// explicit load — useful when MOKKSY_CONFIG is not in the environment
2Mokksy mokksy = Mokksy.create().start();
3mokksy.loadStubsFromEnv();

1# via environment variable — stubs are loaded automatically on start()
2MOKKSY_CONFIG=/app/stubs.yaml java -jar app.jar
3
4# via system property
5java -Dmokksy.config=/app/stubs.yaml -jar app.jar

Validation errors

Mokksy validates the config at load time and reports clear errors when something is wrong:

Problem	Error message
File not found	`Mokksy config file not found: /path/to/stubs.yaml`
Malformed YAML	`Invalid YAML in Mokksy config file '/path/...': <parser message>`
Unknown HTTP method	`<name>: unknown HTTP method 'BREW'. Valid methods: GET, POST, ...`
Stream with no chunks	`<name>: response type 'sse' requires at least one chunk`

Combining file config with code stubs

File-based configuration and the code API can be used together — they register stubs on the same server:

1val mokksy = Mokksy().start()
2
3// load shared stubs from file
4mokksy.loadStubsFromFile("shared-stubs.yaml")
5
6// add test-specific stubs via DSL
7mokksy.get { path("/health") } respondsWithStatus HttpStatusCode.OK

1Mokksy mokksy = Mokksy.create().start();
2
3// load shared stubs from file
4mokksy.loadStubsFromFile("shared-stubs.yaml");
5
6// add test-specific stubs via Java API
7mokksy.get("/health").respondsWith(builder -> builder.body("OK"));