Mock server
Mock, match, modify and manipulate a HTTP request/response payload using flexible expectations with types
%20div%201000&label=coverage)
# Navigation
- [Basics](#basics)
- [How it works](#how-it-works)
- [Install](#install)
- [Start](#start)
- [GUI](#gui)
- [Mock](#mock)
- [Expectations](#expectations)
- [Schema](#schema)
- [Forwarding](#forwarding)
- [Context](#context)
- [Utils](#utils)
- [Operators](#operators)
- [Typings](#typings)
- [Storage](#storage)
- [Containers](#containers)
- [Cache](#cache)
- [State](#state)
- [Seeds](#seeds)
- [XML](#xml)
- [API](#api)
- [Ping](#ping)
- [Create expectation](#create-expectation)
- [Update expectation](#update-expectation)
- [Delete expectation](#delete-expectation)
- [Additional](#additional)
- [Configuration](#configuration)
- [Logger](#logger)
- [Meta](#meta)
# Basics
## Install
```bash
npm i @n1k1t/mock-server
```
## How it works
According on the picture above, main idea is to generate or modify response from some backend service. The mock server provides many scenarios to do that
**In case of mocking without request forwarding:**
1. Start mock server (for example on `localhost:8080`)
2. Register expectation using CLI (cURL) or application lib
3. Make request to `localhost:8080/...`
1. The mock server matches a request payload with registered expectations
2. Build a response using an expectation configuration
**In case of mocking with request forwarding:**
0. Lets imagine that you have a service that hosts on `localhost:8081`
1. Start mock server (for example on `localhost:8080`)
2. Register expectation using CLI (cURL) or application lib
3. Make request to `localhost:8080/...`
1. The mock server matches a request payload with registered expectations
2. Next is forwarding a request payload to `localhost:8081/...`
3. Using response fetched from `localhost:8081/...` the mock server builds a response
## Start
### CLI
```bash
npx mock -h localhost -p 8080
```
### JavaScript
```js
const { MockServer } = require('@n1k1t/mock-server');
MockServer.start({ host: 'localhost', port: 8080 });
```
### TypeScript
```ts
import { MockServer } from '@n1k1t/mock-server';
MockServer.start({ host: 'localhost', port: 8080 });
```
## GUI
The mock server provides built-in web panel to track everything that is going through. There are two tabs `Expectations` and `History`
By default it can be found on `/_system/gui` of a host of mock server. Example: `localhost:8080/_system/gui`
Also it provides convenient util to navigate through payload of expectations and requests payload
## Mock
Simple examples can be found in [expectation creation API](#create-expectation)
# Expectations
## Schema
An expectation schema can contain some rules to handle `request`, `response` and `forward`
| Property | Nested | Type | Optional | Description |
|--|--|--|--|--|
| request | [Operators](#operators) | `object` | * | Describes a way to catch by request and how to manipulate it |
| response | [Operators](#operators) | `object` | * | Describes how to manipulate response. Also can be used to catch response in case of forwarding |
| forward | [Forwarding](#forwarding) | `object` | * | Describes configuration to forward a request to another host |
**Example**
```ts
await server.client.createExpectation({
schema: {
request: {
$and: [],
},
response: {
$or: [],
},
forward: {
baseUrl: 'https://example.com',
url: '/some/path',
},
},
});
```
## Forwarding
| Property | Nested | Type | Optional | Description |
|--|--|--|--|--|
| url | | `string` | * | Absolute URL to target |
| baseUrl | | `string` | * | Base URL to target. The path will be provided from request |
| options | | `string` | * | Forwarding options |
| | host | `origin` | * | Provides `Host` header as same as mock server host (if not specified). If specified to `origin` then value for `Host` header will be taken from url |
| cache | | `object` | * | [Cache](#cache) configuration for a payload of forwarded requests |
| | storage | `redis` | * | Storage to read/write a cache |
| | key | `string` | * | Key to get read/write access of cached payload |
| | prefix | `string` | * | Prefix of the `key` of cache |
| | ttl | `number` | * | Time to live of cache in seconds |
## Context
| Property | Nested | `$location` | Type | Optional | Description |
|--|--|--|--|--|--|
| storage | [Storage](#storage) | | `object` | | A storage of `container` entities |
| container | [Container](#containers) | `container` | `object` | * | A temporary cell in `storage`. Should be useful to sync expectations between each other or store and use any data each request |
| state | | `state` | `object` | | An [object](#state) with custom data |
| seed | | `seed` | `string` | * | Incoming request [seed](#seeds) |
| cache | | `cache` | `object` | | [Cache](#cache) configuration |
| | isEnabled | | `boolean` | | Toggle of cache usage |
| | key | | `string ∣ object` | * | Key to get read/write access of cached payload. Value provided as `object` will hashed using [FNV1A-64](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) algorithm |
| | prefix | | `string` | * | Prefix of the `key` of cache |
| | ttl | | `number` | * | Time to live of cache in seconds |
| incoming | | | `object` | | Payload with data of incoming request |
| | path | `path` | `string` | | Incoming request path |
| | method | `method` | `string` | | Incoming request method in **uppercase** |
| | headers | `incoming.headers` | `object` | | Incoming request headers with keys in **lowercase** |
| | dataRaw | `incoming.dataRaw` | `string` | | Incoming request source data |
| | data | `incoming.data` | `object` | * | Incoming request parsed data |
| | query | `incoming.query` | `object` | * | Incoming request query search parameters |
| | delay | `delay` | `number` | * | Delay that can be applied with [operators](#operators) |
| | error | `error` | `string` | * | Error that can be applied with [operators](#operators) |
| outgoing | | | `object` | | Payload with data of response |
| | status | `outgoing.status` | `number` | | Response status code |
| | headers | `outgoing.headers` | `number` | | Response headers |
| | dataRaw | `outgoing.dataRaw` | `string` | | Response source data |
| | data | `outgoing.data` | `any` | * | Response data |
## Utils
Additional utils in `$exec` operator
| Property | Description |
|--|--|
| `context` | A request [context](#context) |
| `logger` | [Logger](#logger) of mock server |
| `mode` | A mode of expectation execution. Has `match` on catching request or `manipulate` on manipulation over [context](#context) |
| `meta` | A [meta](#meta) of a request |
| `_` | [Lodash](https://www.npmjs.com/package/lodash) |
| `d` | [DayJS](https://www.npmjs.com/package/dayjs) |
| `faker` | [Faker](https://www.npmjs.com/package/@faker-js/faker). Uses [seed](#seeds) if it was provided |
## Operators
> **!NOTE** Each schema that using operators can have only one nested operator. To use more than one operator use `$and` or `$or` operators
| Operator | Optional | Description |
|--|--|--|
| [$has](#has) | * | Catches a request/response or checks a payload in [context](#context) |
| [$set](#set) | * | Sets payload in [context](#context) |
| [$merge](#merge) | * | Merges object payload in [context](#context) with provided `$value` |
| [$remove](#remove) | * | Removes payload in [context](#context) |
| [$exec](#exec) | * | Function to catch a request/response or check/manipulate payload in [context](#context) |
| [$and](#and) | * | Logical `and` |
| [$or](#or) | * | Logical `or` |
| [$not](#not) | * | Logical `not` |
| [$if](#if) | * | Logical `if` |
| [$switch](#switch) | * | Logical `switch/case` |
**Example**
```ts
await server.client.createExpectation({
schema: {
request: {
$and: [
{
$has: {
$location: 'path',
$value: '/foo',
},
},
{
$has: {
$location: 'method',
$value: 'GET',
},
},
],
},
},
});
```
### $has
> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
| $value | `any` | `any` | * | Checks by value equality in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $valueAnyOf | `any[]` | `any[]` | * | Checks by any of value equality in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $regExp | `RegExp` | `{ source: string, flags?: string }` | * | Checks by regular expression in context using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $regExpAnyOf | `RegExp[]` | `{ source: string, flags?: string }[]` | * | Checks by any of regular expression in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $match | `string ∣ object` | `string ∣ object` | * | Checks by minimatch for `string` and `number` (example `/foo/*/bar` or `2**`) or similar `object` by passing object payload in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $matchAnyOf | `(string ∣ object)[]` | `(string ∣ object)[]` | * | Checks by any of minimatch for `string` and `number` (example `/foo/*/bar` or `2**`) or similar `object` by passing object payload in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $exec | `(payload, utils) => boolean` | `string` | * | Checks payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$has: {
$location: 'path',
$regExp: /^\/foo/,
},
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$has": {
"\$location": "method",
"\$regExp": { "source": "^\/foo" }
}
}
}
}
EOF
```
### $set
> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
| $value | `any` | `any` | * | Sets value to [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $exec | `(payload, utils) => any` | `string` | * | Sets payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$set: {
$location: 'incoming.data',
$path: 'foo',
$exec: (payload, { _ }) => _.clamp(payload, 0, 10),
},
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$set": {
"\$location": "incoming.data",
"\$path": "foo",
"\$exec": "_.clamp(payload, 0, 10)"
}
}
}
}
EOF
```
### $merge
> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
| $value | `object` | `object` | * | Merges value in [context](#context) using `$location` (and `$path`, `$jsonPath` if it was specified) |
| $exec | `(payload, utils) => any` | `string` | * | Merges payload in [context](#context) by function with arguments where `payload` is selected entity using `$location` (and `$path`, `$jsonPath` if it was specified) and `utils` is [utils](#utils) |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$merge: {
$location: 'incoming.data',
$value: { has_mocked: true },
},
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$merge": {
"\$location": "incoming.data",
"\$value": {"has_mocked": true}
}
}
}
}
EOF
```
### $remove
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
| $path | `string` | `string` | * | Specifies a path to payload using [lodash get](https://lodash.com/docs/4.17.15#get) |
| $jsonPath | `string` | `string` | * | Specifies a path to payload using [JSON path](https://www.npmjs.com/package/jsonpath-plus) |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$remove: { $location: 'outgoing.data' },
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$remove": {"\$location": "outgoing.data"}
}
}
}
EOF
```
### $exec
> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
| Type (application) | Type (cURL) | Description |
|--|--|--|
| `(utils) => boolean ∣ unknown` | `string` | Does something you want or catch request/response payload in [context](#context) by function with arguments where `utils` is [utils](#utils) |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$exec: ({ context, logger }) => {
logger.info(context);
return context.incoming.path === '/foo';
},
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$exec": "{ logger.info(context); return context.incoming.path === '/foo' }"
}
}
}
EOF
```
### $and
| Type (application) | Type (cURL) | Description |
|--|--|--|
| `object[]` | `object[]` | Provides [operators](#operators) schemas |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$and: [
{ $has: { $location: 'path', $match: 'foo/*' } },
{ $has: { $location: 'method', $valueAnyOf: ['GET', 'POST'] } },
],
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$and": [
{"\$has": {"\$location": "path", "\$match": "foo/*"}},
{"\$has": {"\$location": "method", "\$valueAnyOf": ["GET", "POST"]}}
]
}
}
}
EOF
```
### $or
| Type (application) | Type (cURL) | Description |
|--|--|--|
| `object[]` | `object[]` | Provides [operators](#operators) schemas |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$or: [
{ $has: { $location: 'path', $match: 'foo/*' } },
{ $has: { $location: 'method', $valueAnyOf: ['GET', 'POST'] } },
],
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$or": [
{"\$has": {"\$location": "path", "\$match": "foo/*"}},
{"\$has": {"\$location": "method", "\$valueAnyOf": ["GET", "POST"]}}
]
}
}
}
EOF
```
### $not
| Type (application) | Type (cURL) | Description |
|--|--|--|
| `object` | `object` | Provides an [operators](#operators) schema |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$not: { $has: { $location: 'path', $match: 'foo/*' } },
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$not": {"\$has": {"\$location": "path", "\$match": "foo/*"}}
}
}
}
EOF
```
### $if
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $condition | `object` | `object` | | Condition to check. Should contain one of `$and`, `$exec`, `$has`, `$or` or `$not` [operators](#operators) schema |
| $then | `object` | `object` | * | Logical `then`. Should contain an [operators](#operators) schema |
| $else | `object` | `object` | * | Logical `else`. Should contain an [operators](#operators) schema |
**Example using application**
```ts
await server.client.createExpectation({
schema: {
request: {
$if: {
$condition: { $has: { $location: 'path', $match: 'foo/*' } },
$then: { $set: { $location: 'delay', $value: 5000 } },
$else: { $set: { $location: 'error', $value: 'ECONNABORTED' } },
},
},
},
});
```
**Example using cURL**
```bash
curl -H "Content-type: application/json" -X POST --location "localhost:8080/_system/expectations" --data-binary @- << EOF
{
"schema": {
"request": {
"\$if": {
"\$condition": {"\$has": {"\$location": "path", "\$match": "foo/*"}},
"\$then": {"\$set": {"\$location": "delay", "\$value": 5000}},
"\$else": {"\$set": {"\$location": "error", "\$value": "ECONNABORTED"}}
}
}
}
}
EOF
```
### $switch
> **!NOTE** `$exec` operators [have restrictions](#api) when it defined over `HTTP API` or `RemoteClient`
| Property | Type (application) | Type (cURL) | Optional | Description |
|--|--|--|--|--|
| $location | `string` [enum](#context) | `string` [enum](#context) | | Location that describes what [context](#context) entity is selecting for operator to work with |
| $cases | `Record