Options

How to define options

There are multiple methods for defining Mocks Server configuration:

• Programmatic configuration
• Configuration File
• Environment variables
• Command line arguments

tip

Read the previous chapter for further info about how to define configuration using different methods.

Option names

The name of the options in this page use the "dot notation". But option names may differ depending on the chosen method to set them. Here you have a brief example of how the same option (mock.routes.delay) must be defined when using different methods:

Programmatic

// Set mock.routes.delay option

const server = new Core({
  mock: {
    routes: {
      delay: 3000,
    },
  },
});

info

Convert the "dot notation" into an object when setting programmatic configuration.

JS Config file

// Set mock.routes.delay option

module.exports = {
  mock: {
    routes: {
      delay: 3000,
    },
  },
};

info

Convert the "dot notation" into an object when setting configuration using the config file.

YAML Config file

mock:
  routes:
    delay: 3000

info

Convert the "dot notation" into an object when setting configuration using the config file.

Environment

MOCKS_MOCK_ROUTES_DELAY=3000 npm run mocks

info

Convert the "dot notation" into "screaming snake case", adding the MOCKS prefix.

Command line argument

npm run mocks -- --mock.routes.delay=3000

info

Use the same "dot notation".

Core options

These options are provided by the core of Mocks Server, so they can be used in any Mocks Server distribution.

config.allowUnknownArguments

(Boolean): When set to true, it allows to define unknown command line arguments. Default is false. It can be defined in any source.

Examples

YAML config file

config:
  allowUnknownArguments: true

Argument

npm run mocks -- --config.allowUnknownArguments

Environment

MOCKS_CONFIG_ALLOW_UNKNOWN_ARGUMENTS=true npm run mocks

Programmatic

const server = new Core({
  config: {
    allowUnknownArguments: true,
  },
});

config.fileSearchFrom

(String): Start searching for the configuration file from this folder, and keep searching up in the parent directories until arriving at the config.fileSearchStop folder. Default is process.cwd.

Examples

Arguments

npm run mocks -- --config.fileSearchFrom configs/mocks-server

Environment

MOCKS_CONFIG_FILE_SEARCH_FROM='configs/mocks-server' npm run mocks

Programmatic

const server = new Core({
  config: {
    fileSearchFrom: "configs/mocks-server"
  },
});

caution

Note that it will search in all parent folders recursively until finding a file or arriving at the config.fileSearchStop folder, which by default is also process.cwd. So, if you define a config.fileSearchFrom folder that is not under the process.cwd path, you should also provide the config.fileSearchStop folder. Otherwise, it would search recursively until the root path if no config file is found.

mocks-server --config.fileSearchFrom=../configs --config.fileSearchStop=../configs

config.fileSearchPlaces

(Array of Strings): Paths to search for the configuration file. Default is described in the configuration methods chapter. It can be defined in any source, except configuration files.

Examples

Arguments

npm run mocks -- --config.fileSearchPlaces path/to/my-config.js path/to/my-config.yml

Environment

MOCKS_CONFIG_FILE_SEARCH_PLACES='["path/to/my-config.js","path/to/my-config.yml"]' npm run mocks

Programmatic

const server = new Core({
  config: {
    fileSearchPlaces: [
      "path/to/my-config.js",
      "path/to/my-config.yml"
    ],
  },
});

config.fileSearchStop

(String): Directory where the search for the configuration file will stop. Default is process.cwd.

Examples

Arguments

npm run mocks -- --config.fileSearchStop /path/to/stop-folder

Environment

MOCKS_CONFIG_FILE_SEARCH_STOP='/path/to/stop-folder' npm run mocks

Programmatic

const server = new Core({
  config: {
    fileSearchStop: "/path/to/stop-folder",
  },
});

config.readArguments

(Boolean): If false, it disables the ability of defining options using command line arguments. Default is true. It can be defined only using programmatic configuration.

Examples

Programmatic

const server = new Core({
  config: {
    readArguments: false,
  },
});

config.readEnvironment

(Boolean): If false, it disables the ability of defining options using environment variables. Default is true. It can be defined using programmatic configuration or command line arguments.

Examples

Argument

npm run mocks -- --no-config.readEnvironment

Programmatic

const server = new Core({
  config: {
    readEnvironment: false,
  },
});

config.readFile

(Boolean): If false, it disables the ability of reading configuration file. Default is true. Obviously, it would be ignored if it is defined in the configuration file.

Examples

Argument

npm run mocks -- --no-config.readFile

Environment

MOCKS_CONFIG_READ_FILE=false npm run mocks

Programmatic

const server = new Core({
  config: {
    readFile: false,
  },
});

files.enabled

(String): Allows to disable loading routes and collections from files, which may be useful when used programmatically. Default is true.

Examples

YAML config file

files:
  enabled: false

Argument

npm run mocks -- --no-files.enabled

Environment

MOCKS_FILES_ENABLED=false npm run mocks

Programmatic

const server = new Core({
  files: {
    enabled: false,
  },
});

files.path

(String): Path to the folder containing collections and routes to be loaded by the server. Default is mocks. When relative, it is resolved from the current process.cwd().

Examples

YAML config file

files:
  path: custom-folder

Argument

npm run mocks -- --files.path=custom-folder

Environment

MOCKS_FILES_PATH=custom-folder npm run mocks

Programmatic

const server = new Core({
  files: {
    path: path.resolve(__dirname, "custom-folder"),
  },
});

files.watch

(Boolean): Watch the /mocks folder and restart server on changes. Default is true.

Examples

YAML config file

files:
  watch: false

Argument

npm run mocks -- --no-files.watch

Environment

MOCKS_FILES_WATCH=false npm run mocks

Programmatic

const server = new Core({
  files: {
    watch: false,
  },
});

files.babelRegister.enabled

(Boolean): Enables Babel compilation for files inside the /mocks folder.

Examples

YAML config file

files:
  babelRegister:
    enabled: true

Argument

npm run mocks -- --files.babelRegister.enabled

Environment

MOCKS_FILES_BABEL_REGISTER_ENABLED=true npm run mocks

Programmatic

const server = new Core({
  files: {
    babelRegister: {
      enabled: true,
    },
  },
});

files.babelRegister.options

(Object): Options for @babel/register when babelRegister is enabled. Properties in this object are passed directly to @babel/register as options, so refer to its documentation for further info. You can also see some usage examples in the "using Babel" chapter of this docs.

Examples

JS config file

module.exports = {
  files: {
    babelRegister: {
      enabled: true,
      options: {
        only: (filePath) => {
          return filePath.includes("/mocks/") || filePath.includes("/my-folder-to-include/");
        },
      },
    },
  },
};

Programmatic

const server = new Core({
  files: {
    babelRegister: {
      enabled: true,
      options: {
        only: (filePath) => {
          return filePath.includes("/mocks/") || filePath.includes("/my-folder-to-include/");
        },
      },
    },
  },
});

Argument

npm run mocks -- --files.babelRegister.options="{\"extensions\":[\".ts\"]}"

Environment

MOCKS_FILES_BABEL_REGISTER_OPTIONS='{"extensions":[".ts"]}' npm run mocks

log

(String): Logs level. Can be one of silly, debug, verbose, info, warn, error or silent.

Examples

YAML config file

log: "silly"

Argument

npm run mocks -- --log=silent

Environment

MOCKS_LOG=debug npm run mocks

Programmatic

const server = new Core({
  log: "verbose"
});

mock.collections.selected

(String): Collection to use when the server is started.

Examples

YAML config file

mock:
  collections:
    selected: "my-collection"

Argument

npm run mocks -- --mock.collections.selected=my-collection

Environment

MOCKS_MOCK_COLLECTIONS_SELECTED=my-collection npm run mocks

Programmatic

const server = new Core({
  mock: {
    collections: {
      selected: "my-collection"
    }
  }
});

mock.routes.delay

(Number): Responses delay time in milliseconds. This is a global setting that can be overridden in specific routes or route variants using their options.

Examples

YAML config file

mock:
  routes:
    delay: 1000

Argument

npm run mocks -- --mock.routes.delay=1000

Environment

MOCKS_MOCK_ROUTES_DELAY=1000 npm run mocks

Programmatic

const server = new Core({
  mock: {
    routes: {
      delay: 1000
    }
  }
});

plugins.register

(Array of Plugin): Array of Plugins, defined as described in the plugins chapter.

Example

Programmatic

import FooPlugin from "./FooPlugin";

const server = new Core({
  plugins: {
    register: [
      FooPlugin,
    ]
  }
});

server.cors.enabled

(Boolean): Built-in CORS middleware. Default is true. Use false to disable it.

Examples

YAML config file

server:
  cors:
    enabled: false

Argument

npm run mocks -- --no-server.cors.enabled

Environment

MOCKS_SERVER_CORS_ENABLED=false npm run mocks

Programmatic

const server = new Core({
  server: {
    cors: {
      enabled: false
    }
  }
});

server.cors.options

(Object): Options for the built-in CORS middleware. By default, it sets the preflightContinue property as false, which means that Mocks Server will respond to all OPTIONS requests with a 204 status and correspondent CORS headers. If you want to handle OPTIONS requests by yourself, you should set that property to true.

Examples

YAML config file

server:
  cors:
    options:
      preflightContinue: true

Argument

npm run mocks -- --server.cors.options="{\"preflightContinue\":true}"

Environment

MOCKS_SERVER_CORS_OPTIONS='{"preflightContinue":true}' npm run mocks

Programmatic

const server = new Core({
  server: {
    cors: {
      options: {
        preflightContinue: true
      }
    }
  }
});

server.host

(String): Host for the server. Default is 0.0.0.0 (Reachable to all IPv4 addresses on the local machine).

Examples

YAML config file

server:
  host: "192.168.1.100"

Argument

npm run mocks -- --server.host=192.168.1.100

Environment

MOCKS_SERVER_HOST=192.168.1.100 npm run mocks

Programmatic

const server = new Core({
  server: {
    host: "192.168.1.100"
  }
});

server.https.enabled

(Boolean): Enables HTTPS protocol in the mock server. Default is false

Examples

YAML config file

server:
  https:
    enabled: true

Argument

npm run mocks -- --server.https.enabled

Environment

MOCKS_SERVER_HTTPS_ENABLED=true npm run mocks

Programmatic

const server = new Core({
  server: {
    https: {
      enabled: true
    }
  }
});

caution

When enabling the server.https.enabled option, it is also needed to provide HTTPS certificate and key using the server.https.cert and server.https.key options. For further info read the "Enabling HTTPS" guide.

server.https.cert

(String): Path to a valid SSL/TLS certificate to be used when HTTPS is enabled. It must be relative to the current process.cwd() or absolute. This option has no effect when server.https.enabled is false.

Examples

YAML config file

server:
  https:
    cert: "certs/cert.pem"

Argument

npm run mocks -- --server.https.cert=certs/cert.pem

Environment

MOCKS_SERVER_HTTPS_CERT=certs/cert.pem npm run mocks

Programmatic

const server = new Core({
  server: {
    https: {
      cert: "certs/cert.pem"
    }
  }
});

server.https.key

(String): Path to a valid SSL/TLS certificate key to be used when HTTPS is enabled. It must be relative to the current process.cwd() or absolute. This option has no effect when server.https.enabled is false.

Examples

YAML config file

server:
  https:
    key: "certs/key.pem"

Argument

npm run mocks -- --server.https.key=certs/key.pem

Environment

MOCKS_SERVER_HTTPS_KEY=certs/key.pem npm run mocks

Programmatic

const server = new Core({
  server: {
    https: {
      key: "certs/key.pem"
    }
  }
});

server.jsonBodyParser.enabled

(Boolean): If false, it disables the json body-parser built-in Express middleware. Default is true.

Examples

YAML config file

server:
  jsonBodyParser:
    enabled: false

Argument

npm run mocks -- --no-server.jsonBodyParser.enabled

Environment

MOCKS_SERVER_JSON_BODY_PARSER_ENABLED=false npm run mocks

Programmatic

const server = new Core({
  server: {
    jsonBodyParser: {
      enabled: false,
    }
  }
});

server.jsonBodyParser.options

(Object): Options for the json body-parser built-in Express middleware.

Examples

YAML config file

server:
  jsonBodyParser:
    options:
      limit: "200kb"

Argument

npm run mocks -- --server.jsonBodyParser.options="{\"limit\":\"200kb\"}"

Environment

MOCKS_SERVER_JSON_BODY_PARSER_OPTIONS='{"limit":"200kb"}' npm run mocks

Programmatic

const server = new Core({
  server: {
    jsonBodyParser: {
      options: {
        limit: "200kb"
      }
    }
  }
});

server.port

(Number): Port number for Mocks Server to be listening at. Default is 3100.

Examples

YAML config file

server:
  port: 3500

Argument

npm run mocks -- --server.port=3500

Environment

MOCKS_SERVER_PORT=3500 npm run mocks

Programmatic

const server = new Core({
  server: {
    port: 3500
  }
});

server.urlEncodedBodyParser.enabled

(Boolean): If false, it disables the urlencoded body-parser built-in Express middleware. Default is true.

Examples

YAML config file

server:
  urlEncodedBodyParser:
    enabled: false

Argument

npm run mocks -- --no-server.urlEncodedBodyParser.enabled

Environment

MOCKS_SERVER_URL_ENCODED_BODY_PARSER_ENABLED=false npm run mocks

Programmatic

const server = new Core({
  server: {
    urlEncodedBodyParser: {
      enabled: false,
    }
  }
});

server.urlEncodedBodyParser.options

(Object): Options for the urlencoded body-parser built-in Express middleware.

Examples

YAML config file

server:
  urlEncodedBodyParser:
    options:
      limit: "200kb"

Argument

npm run mocks -- --server.urlEncodedBodyParser.options="{\"limit\":\"200kb\"}"

Environment

MOCKS_SERVER_URL_ENCODED_BODY_PARSER_OPTIONS='{"limit":"200kb"}' npm run mocks

Programmatic

const server = new Core({
  server: {
    urlEncodedBodyParser: {
      options: {
        limit: "200kb"
      }
    }
  }
});

variantHandlers.register

(Array of Variant Handlers): Array of Variant Handlers to be added. Other variant handlers are not removed.

Example

Programmatic

import FooVariantHandler from "./FooVariantHandler";

const server = new Core({
  variantHandlers: {
    register: [
      FooVariantHandler,
    ]
  }
});

Plugins options

Each plugin can add its own options when it is installed. These options can also be defined and changed using the same methods as the core options. Note that all plugins options must be defined under the plugins namespace, and all options of a plugin must be defined under its own plugin id namespace (plugins.[plugin-id].[option])

info

These extra options are added by the plugins included in the @mocks-server/main distribution.

For another plugins options, please refer to their own documentation.

plugins.inquirerCli.enabled

(Boolean): Start interactive CLI plugin or not. Default is true.

Examples

YAML config file

plugins:
  inquirerCli:
    enabled: false

Argument

npm run mocks -- --no-plugins.inquirerCli.enabled

Environment

MOCKS_SERVER_PLUGINS_INQUIRER_CLI_ENABLED=false npm run mocks

Programmatic

const server = new Core({
  plugins: {
    inquirerCli: {
      enabled: false,
    }
  }
});

plugins.inquirerCli.emojis

(Boolean): Defines whether the inquirer CLI uses emojis or not. Default is true.

Examples

YAML config file

plugins:
  inquirerCli:
    emojis: false

Argument

npm run mocks -- --no-plugins.inquirerCli.emojis

Environment

MOCKS_SERVER_PLUGINS_INQUIRER_CLI_EMOJIS=false npm run mocks

Programmatic

const server = new Core({
  plugins: {
    inquirerCli: {
      emojis: false,
    }
  }
});

plugins.adminApi.host

(String): Host for the administration REST API. Default is 0.0.0.0 (Reachable to all IPv4 addresses on the local machine).

Examples

YAML config file

plugins:
  adminApi:
    host: "192.168.1.100"

Argument

npm run mocks -- --plugins.adminApi.host=192.168.1.100

Environment

MOCKS_SERVER_PLUGINS_ADMIN_API_HOST_=192.168.1.100 npm run mocks

Programmatic

const server = new Core({
  plugins: {
    adminApi: {
      host: "192.168.1.100",
    }
  }
});

plugins.adminApi.https.enabled

(Boolean): Enables HTTPS protocol in the admin API server. Default is false

Examples

YAML config file

plugins:
  adminApi:
    https:
      enabled: true

Argument

npm run mocks -- --plugins.adminApi.https.enabled

Environment

MOCKS_PLUGINS_ADMIN_API_HTTPS_ENABLED=true npm run mocks

Programmatic

const server = new Core({
  plugins: {
    adminApi: {
      https: {
        enabled: true
      }
    }
  }
});

caution

When enabling the plugin.adminApi.https.enabled option, it is also needed to provide HTTPS certificate and key using the plugin.adminApi.https.cert and plugin.adminApi.https.key options. For further info read the "Enabling HTTPS" guide.

plugins.adminApi.https.cert

(String): Path to a valid SSL/TLS certificate to be used when HTTPS is enabled in the adminApi plugin. It must be relative to the current process.cwd() or absolute. This option has no effect when server.https.enabled is false.

Examples

YAML config file

plugins:
  adminApi:
    https:
      cert: "certs/cert.pem"

Argument

npm run mocks -- --plugins.adminApi.https.cert=certs/cert.pem

Environment

MOCKS_PLUGINS_ADMIN_API_HTTPS_CERT=certs/cert.pem npm run mocks

Programmatic

const server = new Core({
  plugins: {
    adminApi: {
      https: {
        cert: "certs/cert.pem"
      }
    }
  }
});

plugins.adminApi.https.key

(String): Path to a valid SSL/TLS certificate key to be used when HTTPS is enabled. It must be relative to the current process.cwd() or absolute. This option has no effect when plugins.adminApi.https.enabled is false.

Examples

YAML config file

plugins:
  adminApi:
    https:
      key: "certs/key.pem"

Argument

npm run mocks -- --plugins.adminApi.https.key=certs/key.pem

Environment

MOCKS_PLUGINS_ADMIN_API_HTTPS_KEY=certs/key.pem npm run mocks

Programmatic

const server = new Core({
  plugins: {
    adminApi: {
      https: {
        key: "certs/key.pem"
      }
    }
  }
});

plugins.adminApi.port

(Number): Port for the administration REST API. Default is 3110.

Examples

YAML config file

plugins:
  adminApi:
    port: 3510

Argument

npm run mocks -- --plugins.adminApi.port=3510

Environment

MOCKS_SERVER_PLUGINS_ADMIN_API_PORT=3510 npm run mocks

Programmatic

const server = new Core({
  plugins: {
    adminApi: {
      port: 3510,
    }
  }
});

plugins.openapi.collection.id

(String | Null): Id for the collection to be created with all routes from all OpenAPI documents. Default is "openapi". When it is set to null, no collection will be created.

Examples

YAML config file

plugins:
  openapi:
    collection:
      id: "all-openapi-routes"

Argument

npm run mocks -- --plugins.openapi.collection.id=all-openapi-routes

Environment

MOCKS_SERVER_PLUGINS_OPENAPI_COLLECTION_ID=all-openapi-routes npm run mocks

Programmatic

const server = new Core({
  plugins: {
    openapi: {
      collection: {
        id: "all-openapi-routes"
      },
    }
  }
});

plugins.openapi.collection.from

(String): Id of the collection to extend from when creating the collection with all routes from all OpenAPI documents.

Examples

YAML config file

plugins:
  openapi:
    collection:
      from: "base"

Argument

npm run mocks -- --plugins.openapi.collection.from="base"

Environment

MOCKS_SERVER_PLUGINS_OPENAPI_COLLECTION_FROM=base npm run mocks

Programmatic

const server = new Core({
  plugins: {
    openapi: {
      collection: {
        from: "base"
      },
    }
  }
});