Version: Next

mocksServer API


Mocks Server provides the mocksServer instance to plugins, middlewares and other system pieces. The mocksServer instance is the Mocks Server core itself, and it contains methods allowing to configure, start or stop it, getters returning information, etc.

You could also create your own mocksServer instance programmatically. Read the programmatic usage chapter for further info.


Initialization methods#

  • init([programmaticOptions]): Register plugins, initialize options and prepare all other internal dependencies needed to start the server. Returns a promise. Accepts next arguments:
    • programmaticOptions (Object): All Mocks Server main options or plugins options. Command line arguments and configuration file options will override the values defined here. Options are internally called settings once they are initialized.
  • start(): Start the server and plugins. Returns a promise.
  • stop(): Stop the server and plugins. Returns a promise.
  • restartServer(): Restart the server.

Event listeners methods#

  • onChangeMocks(callback): Add a callback to be executed when mocks or routes changes. Returns a function for removing the added callback.
    • callback() (Function): Function to be executed on change mocks.
  • onChangeSettings(callback): Add a callback to be executed when settings are changed. Returns a function for removing the added callback.
    • callback([changedSettings]) (Function): Function to be executed on change settings.
      • changedSettings (Object): Settings properties that have changed, with new values.
  • onChangeAlerts(callback): Add a callback to be executed when alerts change. Returns a function for removing the added callback.
    • callback([currentAlerts]) (Function): Function to be executed on change alerts.
      • currentAlerts (Array): Current alerts.

Customization methods#

  • addSetting(customSetting): Register a new setting (which will be available also as an option during initialization). Has to be called before the mocksServer.init method is called. (It should be usually used by Plugins in their register method)
    • customSetting (Object): containing next properties:
      • name (String): Name of the new option.
      • type (String): One of string, number, boolean. Defines the type of the new option.
      • description (String): Used for giving help to the user in command line arguments, for example.
      • default(Any): Default value for the new option.
      • parse (Function) Custom parser for the option when it is defined using command line arguments.
  • addRouter(path, expressRouter): Add a custom express router to the server. Custom routers will be added just before the middleware that serves the routes, so if a custom router path matches with a route path, the first one will have priority.
    • path (String): Api path for the custom router
    • expressRouter (Express Router): Instance of an express router.
  • removeRouter(path, expressRouter): Remove a custom express router previously added with the addRouter method.
    • path(String): Api path of the custom router to be removed.
    • expressRouter (Express Router): Instance of the express router to be removed.
  • addRoutesHandler(RoutesHandler): Add a custom routes handler. This allows to add new formats of defining route variants.


  • tracer: Contains methods for using the built-in Mocks Server formatted tracer. Depending of the current log setting, the message will be printed or not:
    • error(message)
    • warn(message)
    • info(message
    • verbose(message)
    • debug(message)
    • silly(message)
    • set(level, [transport]): Sets the tracer current log level.
      • level (String): Level can be one of silent, error, warn, info, verbose, debug or silly.
      • transport (String): The tracer transport in which the level has to be set. Can be one of console, store. Default is console.
    • store: Returns an array with logs (only last 1000 are stored). The level of logs stored can be changed using tracer.set(level, "store").
    • deprecationWarn(oldMethodName, newMethodName) Call to tracer.warn for giving feedback about a method that is going to be deprecated.
  • settings: Contains methods for interacting with the Mocks Server settings. Settings are equivalent to options, but another name is used because they are already initialized and contains definitive values, taking into account command line arguments or other configuration methods. Available methods are:
    • set(key, value): Changes the value of a setting.
      • key (String): The name of the setting to be changed. Equivalent to option name.
      • value (Any): New value for the specific setting to be set.
    • get(key): Returns current value of an specific setting.
      • key (String): The name of the setting to be returned. Equivalent to option name.
    • all: Getter returning all current settings. Never modify returned object if you want to change settings, as it will have no effect. Use the settings.set method instead.
    • getValidOptionName(optionName): Returns valid option name if it exists, or new option name if it is deprecated but is still supported, and null if it does not exist.
      • optionName (String): Option name to check.
  • mocks: Returns methods and getters related to currently available mocks and routes.
    • useRouteVariant(variantId): Define a route variant to be used by the current mock. Route variants are restored whenever the current mock changes.
      • variantId (String): Route variant id, with the format "[routeId]:[variantId]".
    • restoreRoutesVariants(): Restore current mock route variants. It removes all variants defined with the useRouteVariant method.
    • customRoutesVariants: Getter returning array of currently used routes variants ids.
    • current: Getter returning current mock id.
    • ids: Getter returning an array with all mocks ids.
    • plainMocks: Returns an array with current mocks in plain format.
    • plainRoutes: Returns an array with current routes in plain format.
    • plainRoutesVariants: Returns an array with current routes variants in plain format.
  • alerts: Returns an array of current alerts.