Skip to main content
Version: 3.0.0

mocksServer API

Preface

Mocks Server provides the mocksServer core instance to plugins, middlewares and other system pieces. The core 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 core instance programmatically. Read the programmatic usage chapter for further info.

API

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, environment variables and configuration file options will override the values defined here. Options are internally available using the config API 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.
  • 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

  • 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.

Getters

  • 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.
  • config: Returns the core config instance. Read config for further info.
  • 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.

Config methods

The core exposes a getter named config which returns an instance of the config object. Here you have described its API partially. For further information about this object, please read the @mocks-server/config docs.

  • addNamespace(name): Add namespace to the root. Returns a namespace instance.
    • name (String): Name for the namespace.
  • addOption(optionProperties): Equivalent to the addOption method in namespaces, but it add the option to the root. Returns an option instance.
    • optionProperties (Object): Properties defining the option. See the addOption method in namespaces for further info.
  • addOptions(optionsProperties): Add many options. Returns an array of option instances.
    • optionsProperties (Array): Array of optionProperties.
  • namespace(name): Returns the namespace instance in the root config with name equal to name.
  • option(optionName): Returns the option instances in the root config with name equal to optionName.
  • set(configuration): Set configuration properties to each correspondent namespace and options.
    • configuration (Object): Object with programmatic configuration. Levels in the object correspond to namespaces names, and last level keys correspond to option names.
  • validate(configuration, options): Allows to pre-validate a configuration before setting it, for example. It returns an object with valid and errors properties. See AJV docs for further info.
    • configuration (Object): Object with configuration. Levels in the object correspond to namespaces names, and last level keys correspond to option names.
    • options (Object): Object with extra options for validation:
      • allowAdditionalProperties (Boolean): Default false. If true, additional properties in the configuration would not produce validation errors.
  • value: Getter returning the current values from all namespaces and options as an object. Levels in the object correspond to namespaces names, and last level keys correspond to option names. It can be also used as setter as an alias of the set method, with default options.
  • loadedFile: Getter returning the file path of the loaded configuration file. It returns null if no configuration file was loaded.
  • namespaces: Getter returning array with all root namespaces.
  • options: Getter returning array with all root options.

Config namespace instance

  • addNamespace(name): Add another namespace to the current namespace. Returns a namespace instance.
    • name (String): Name for the namespace.
  • addOption(optionProperties): Adds an option to the namespace. Returns an option instance.
    • optionProperties (Object): Properties defining the option.
      • name (String): Name for the option.
      • description (String): Optional. Used in help, traces, etc.
      • type (String). One of string, boolean, number, array or object. Used to apply type validation when loading configuration and in option.value setter.
      • itemsType (String). Can be defined only when type is array. It must be one of string, boolean, number or object.
      • default - Optional. Default value. Its type depends on the type option.
      • extraData - (Object). Optional. Useful to store any extra data you want in the option. For example, Mocks Server uses it to define whether an option must be written when creating the configuration scaffold or not.
  • addOptions(optionsProperties): Add many options. Returns an array of option instances.
    • optionsProperties (Array): Array of optionProperties.
  • namespace(name): Returns the namespace instance in this namespace with name equal to name.
  • option(optionName): Returns the option instances in this namespace with name equal to optionName.
  • name: Getter returning the namespace name.
  • namespaces: Getter returning an array with children namespaces.
  • options: Getter returning an array object with children options.
  • set(configuration): Set configuration properties to each correspondent child namespace and options.
    • configuration (Object): Object with configuration. Levels in the object correspond to child namespaces names, and last level keys correspond to option names.
  • value: Getter returning the current values from all child namespaces and options as an object. Levels in the object correspond to namespaces names, and last level keys correspond to option names. It can be also used as setter as an alias of the set method, with default options.

Config option instance

  • value: Getter of the current value. It can be also used as setter as an alias of the set method, with default options..
  • set(value): Set value.
  • onChange(callback): Allows to add a listener that will be executed whenever the value changes. It only emit events after calling to the config.start method. It returns a function that removes the listener once executed.
    • callback(value) (Function): Callback to be executed whenever the option value changes. It receives the new value as first argument.
  • name: Getter returning the option name.
  • type: Getter returning the option type.
  • description: Getter returning the option description.
  • extraData: Getter returning the option extra data.
  • default: Getter returning the option default value.