|
| 1 | +--- |
| 2 | +title: "Mock API Server" |
| 3 | +weight: 55 |
| 4 | +draft: false |
| 5 | +description: "Serve OpenAPI-described mock APIs for Lab tests or standalone fixture access." |
| 6 | +--- |
| 7 | + |
| 8 | +# Mock API Server |
| 9 | + |
| 10 | +Lab can serve OpenAPI-described mock APIs over HTTP. Use mock APIs when a test needs stable REST responses without depending on an external service. |
| 11 | + |
| 12 | +During `lab run`, mock service URLs are passed to FQL under `@lab.mock`. |
| 13 | + |
| 14 | +## Serve a mock API during a test run |
| 15 | + |
| 16 | +Use `run --mock` to serve an OpenAPI-compatible mock API while tests run. |
| 17 | + |
| 18 | +{{< terminal >}} |
| 19 | +lab run --mock ./users.yaml@api tests/ |
| 20 | +{{< /terminal >}} |
| 21 | + |
| 22 | +The service URL is available as `@lab.mock.api`. |
| 23 | + |
| 24 | +{{< code lang="fql" >}} |
| 25 | +LET response = IO::NET::HTTP::GET(@lab.mock.api + "/users/123") |
| 26 | +LET user = JSON_PARSE(TO_STRING(response)) |
| 27 | + |
| 28 | +RETURN user.id == "123" |
| 29 | +{{< /code >}} |
| 30 | + |
| 31 | +Multiple mock APIs can be served in the same run: |
| 32 | + |
| 33 | +{{< terminal >}} |
| 34 | +lab run \ |
| 35 | + --mock ./users.yaml@users \ |
| 36 | + --mock ./billing.yaml@billing \ |
| 37 | + tests/ |
| 38 | +{{< /terminal >}} |
| 39 | + |
| 40 | +## Start standalone mock APIs |
| 41 | + |
| 42 | +Use `lab serve --mock` when you want a mock API service without running tests. |
| 43 | + |
| 44 | +{{< terminal >}} |
| 45 | +lab serve --mock ./users.yaml@api |
| 46 | +{{< /terminal >}} |
| 47 | + |
| 48 | +Standalone `serve` entries must be explicit. Positional service entries are rejected; use `--mock` for mock API specs. |
| 49 | + |
| 50 | +Lab prints the URL for each started service and runs until the process is cancelled. |
| 51 | + |
| 52 | +## Entry syntax |
| 53 | + |
| 54 | +Mock entries use this binding syntax: |
| 55 | + |
| 56 | +| Syntax | Meaning | |
| 57 | +| --- | --- | |
| 58 | +| `<path>` | Serve the spec on a dynamic port with the filename, without extension, as the alias. | |
| 59 | +| `<path>:<port>` | Serve the spec on a fixed port with the filename, without extension, as the alias. | |
| 60 | +| `<path>@<alias>` | Serve the spec with an explicit alias. | |
| 61 | +| `<path>@<alias>:<port>` | Serve the spec with an explicit alias and fixed port. | |
| 62 | + |
| 63 | +Mock entries must point to existing files. The default alias is the spec filename without its extension. |
| 64 | + |
| 65 | +Aliases must start with a letter or underscore and may contain letters, numbers, underscores, and hyphens. Use bracket access for aliases that are not valid FQL dotted-property names: |
| 66 | + |
| 67 | +{{< code lang="fql" >}} |
| 68 | +RETURN @lab.mock["users-api"] + "/users/123" |
| 69 | +{{< /code >}} |
| 70 | + |
| 71 | +Duplicate aliases are rejected. |
| 72 | + |
| 73 | +## Fixed ports |
| 74 | + |
| 75 | +Use a fixed port when another process needs a stable URL. |
| 76 | + |
| 77 | +{{< terminal >}} |
| 78 | +lab serve --mock ./users.yaml@api:8081 |
| 79 | +{{< /terminal >}} |
| 80 | + |
| 81 | +The fixed port is part of the service binding. The alias is still `api`, so test scripts use `@lab.mock.api`. |
| 82 | + |
| 83 | +## Mock API specs |
| 84 | + |
| 85 | +Mock specs use OpenAPI `paths` with operation-level `x-lab-mock` blocks. |
| 86 | + |
| 87 | +```yaml |
| 88 | +openapi: 3.1.0 |
| 89 | +info: |
| 90 | + title: Users API |
| 91 | + version: 1.0.0 |
| 92 | +paths: |
| 93 | + /users/{id}: |
| 94 | + get: |
| 95 | + x-lab-mock: |
| 96 | + status: 200 |
| 97 | + headers: |
| 98 | + X-Test-Server: lab |
| 99 | + body: |
| 100 | + id: "{{ .Path.id }}" |
| 101 | + name: "User {{ .Path.id }}" |
| 102 | +``` |
| 103 | +
|
| 104 | +The mock server currently handles `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` operations. Paths must start with `/`. |
| 105 | + |
| 106 | +`x-lab-mock` supports: |
| 107 | + |
| 108 | +| Field | Meaning | |
| 109 | +| --- | --- | |
| 110 | +| `status` | HTTP status code. Defaults to `200`. | |
| 111 | +| `headers` | Response headers as string values. | |
| 112 | +| `body` | Structured JSON response body. String values are rendered as templates. | |
| 113 | +| `bodyTemplate` | Raw text response template. Mutually exclusive with `body`. | |
| 114 | + |
| 115 | +When `body` is used, Lab writes JSON and defaults `Content-Type` to `application/json` unless the mock sets it. When `bodyTemplate` is used, Lab writes text and defaults `Content-Type` to `text/plain; charset=utf-8`. |
| 116 | + |
| 117 | +## Template context |
| 118 | + |
| 119 | +Mock response templates use Go template syntax. They receive this context: |
| 120 | + |
| 121 | +| Field | Meaning | |
| 122 | +| --- | --- | |
| 123 | +| `.Method` | Request method. | |
| 124 | +| `.Path` | Path parameters from routes such as `/users/{id}`. | |
| 125 | +| `.Query` | Query parameters. | |
| 126 | +| `.Headers` | Request headers. | |
| 127 | +| `.Body` | Parsed JSON request body, or `nil`. | |
| 128 | + |
| 129 | +Example: |
| 130 | + |
| 131 | +```yaml |
| 132 | +paths: |
| 133 | + /echo/{name}: |
| 134 | + post: |
| 135 | + x-lab-mock: |
| 136 | + status: 201 |
| 137 | + body: |
| 138 | + method: "{{ .Method }}" |
| 139 | + name: "{{ .Path.name }}" |
| 140 | + active: "{{ .Body.active }}" |
| 141 | +``` |
| 142 | + |
| 143 | +Request bodies used by templates must be JSON. If the request body is not valid JSON, the mock server returns `400 Bad Request`. |
| 144 | + |
| 145 | +## Bind and advertised hosts |
| 146 | + |
| 147 | +By default, mock services bind to `127.0.0.1` and advertise URLs with `127.0.0.1`. |
| 148 | + |
| 149 | +Use `--serve-bind` to choose the listener host. Use `--serve-host` to choose the host placed in generated URLs. |
| 150 | + |
| 151 | +{{< terminal >}} |
| 152 | +lab run \ |
| 153 | + --mock ./users.yaml@api \ |
| 154 | + --serve-bind 0.0.0.0 \ |
| 155 | + --serve-host host.docker.internal \ |
| 156 | + tests/ |
| 157 | +{{< /terminal >}} |
| 158 | + |
| 159 | +Both values are hosts only. Do not include a port. |
| 160 | + |
| 161 | +When `--serve-host` is set and `--serve-bind` is omitted, Lab binds to a wildcard host so remote runtimes can reach the service: `0.0.0.0` for IPv4 and hostnames, or `::` for IPv6 literals. |
0 commit comments