Mock Server

Purpose

The mock server lets you test Hook requests against a local HTTP endpoint without depending on an external API. Define routes with fixed responses and run the server on localhost.

Routes JSON format

The mock server reads routes from a JSON file. Each route maps an HTTP method and path to a fixed response.

[
  {
    "method": "GET",
    "path": "/api/users",
    "status_code": 200,
    "content_type": "application/json",
    "body": "[{\"id\":1,\"name\":\"Alice\"}]",
    "delay_ms": 0
  },
  {
    "method": "POST",
    "path": "/api/users",
    "status_code": 201,
    "content_type": "application/json",
    "body": "{\"id\":2,\"name\":\"Bob\"}",
    "delay_ms": 100
  },
  {
    "method": "GET",
    "path": "/health",
    "status_code": 200,
    "content_type": "text/plain",
    "body": "ok",
    "delay_ms": 0
  }
]

Route fields

• method (string, required): HTTP method to match. Case-sensitive. Examples: “GET”, “POST”, “PUT”, “DELETE”.
• path (string, required): request path to match. Must start with “/”.
• status_code (integer, required): HTTP status code to return.
• content_type (string, required): value of the Content-Type response header.
• body (string, required): response body string. Use escaped JSON for JSON responses.
• delay_ms (integer, optional): delay in milliseconds before sending the response. Default: 0 (no delay). Use this to simulate slow endpoints.

Route matching

Routes are matched by method and path. The first matching route wins. If no route matches, the server returns 404 with an empty body.

Path matching is exact. There is no wildcard or regex support.

Starting from the GUI

1. Open the Mock Server panel.
2. Click Load Routes and select a routes JSON file (or click New for a starter template, or paste JSON directly).
3. Set the port (default: 18080).
4. Click Start.

The server runs in a background thread. The status label below the buttons shows the current state:

• Stopped – server is not running.
• Running on port N – server accepted Start and is listening.
• Error: ... – Start failed; the rest of the line names the cause. Common cases:
  • no routes loaded -- use New, Load, or paste JSON (the routes textarea was empty).
  • invalid port (must be 1-65534) (port outside the valid range).
  • failed to start (check JSON syntax and port N) (malformed routes JSON, port already in use, or thread create failed).
  • cannot write temp routes file (check permissions) (can’t write to the OS temp directory).

The error message persists until the next successful Start or a Stop click.

To stop the server, click Stop.

Starting from the CLI

hook mock routes.json [--port N]

Arguments:

• routes.json: path to the routes JSON file (required).
• --port N: TCP port to listen on (optional). Default: 18080.

The server runs in the foreground. Press Ctrl+C to stop it.

Example:

hook mock test-routes.json --port 9090

Testing against the mock server

Once the server is running, point your requests at it.

1. Set the URL to http://localhost:18080/api/users (or whatever port you chose).
2. Send the request.
3. The mock server responds with the fixed response defined in the routes file.

With environments, set a variable:

{
  "name": "local",
  "variables": {
    "base_url": "http://localhost:18080"
  }
}

Then use {{base_url}}/api/users in your request URL.

Simulating latency

Set delay_ms on a route to simulate a slow server. The mock server waits the specified number of milliseconds before sending the response. This is useful for testing timeout behavior.

Example: a route with "delay_ms": 5000 waits 5 seconds before responding. A request with a 3000ms timeout will time out.

Limitations

• The mock server listens on HTTP only, not HTTPS.
• Path matching is exact; no wildcards or path parameters.
• Request headers and body are not considered in route matching.
• Only one mock server instance can run at a time.
• The server binds to all interfaces (0.0.0.0).