Skip to main content
Version: 4.0.0

JavaScript API

Preface​

Mocks Server provides its core instance to plugins, middlewares and other system elements. It contains methods allowing to configure it, start or stop it, listen to its events, etc. Using it also enables to tap into, modify, or extend its internal behavior.

caution

Use only the API methods described in this docs. Use other methods under your own risk, and take into account that they may change in minor versions without considering it as a breaking change.

Constructor​

new Core([config], [advancedOptions]): Creates a new Mocks Server core instance. Read the Javascript integrations for further info.

  • config (Object): Any of Mocks Server core options or plugins options. Command line arguments, environment variables and configuration file options would override the values defined here.
  • advancedOptions (Object):
    • pkg (Object): Useful when creating custom distributions. It allows to define a different package name and version to check for updates. For example, the @mocks-server/main distribution provides its name and version to the core using this parameter, so when the core checks for updates, it uses these properties instead of its own.
      • name (String): Package name
      • version (String): Current package version
const Core = require("@mocks-server/core");

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

core.init().then(async () => {
  await core.start();
  await core.stop();
});
caution

The Core constructor is exported only by the @mocks-server/core package, and it doesn't include any pre-installed plugins, so you should install them by yourself if you choose this method for starting Mocks Server programmatically. Read the next section for an alternative method of creating a core instance using the @mocks-server/main package, which includes pre-installed plugins and other optimal configuration to start it programmatically.

Creating an instance with pre-installed plugins​

The @mocks-server/main distribution includes some plugins providing useful integrations, such as the Admin Api Plugin, etc. If you create a new server instance using the @mocks-server/core package as in the example above, you would have to install your desired plugins by your own (which may be useful to create your own distribution, for example).

Note also that the default configuration of @mocks-server/core is intended to be used in CLI, so it tries to load files, read arguments and environment variables, etc. which might not be ideal to start it programmatically in Jest tests, for example.

But it is also possible to create an instance with all @mocks-server/main distribution plugins and configuration optimized for a programmatic usage using the next function exported by the library:

createServer([config]): Returns a new core instance. The config provided is merged with the default package config, which includes some pre-installed plugins and optimized configuration for a programmatic usage:

  • It disables the files load. The scaffold is not created and routes and collections must have to be loaded using the JavaScript API.
  • It disables loading configuration from file, environment variables or arguments. So, possible conflicts are avoided and all configuration has to be provided programmatically.
  • It disables the interactive CLI plugin.
const { createServer } = require("@mocks-server/main");
const { routes, collections } = require("./fixtures");

const core = createServer({
  server: {
    port: 3500
  },
});

core.init().then(async () => {
  const { loadRoutes, loadCollections } = core.mock.createLoaders();
  loadRoutes(routes);
  loadCollections(collections);
  
  await core.start();
});
Creating an instance with pre-installed plugins and custom configuration

You can also use the createServer method to create an instance programmatically, but loading files from the mocks folder and configuration files, for example. In the next example, the server would be started as it was started using the mocks-server CLI command:

const { createServer } = require("@mocks-server/main");

const core = createServer({
  config: {
    readArguments: true,
    readEnvironment: true,
    readFile: true,
  },
  plugins: {
    inquirerCli: {
      enabled: true,
    },
  },
  files: {
    enabled: true,
  },
});

core.start();

Other ways of accessing to the core instance​

Apart from creating your own core instance programmatically, you can also use it from other system elements, because it is passed as an argument to them. Some elements to which the core instance is passed are:

  • Plugins: A plugin receives the core instance on its constructor and in all of its standardized methods. Read plugins development for further info.
  • Variant handlers: A variant handler receives the core instance on its constructor. Read variant handlers development for further info.
    • middleware variants: The core is passed from the middleware variant handler to the middleware functions defined in that type of variants. So, it can be used directly in Express middlewares. Read the middleware variant chapter for further info.
tip

Read the plugins development and variant handlers development chapters for further info.

API​

Here are described the methods that are available at first level of the core instance.

init()​

core.init([config]): Register plugins, initialize options and prepare all other internal dependencies needed to start the server. Returns a promise. Accepts next arguments:

  • config (Object): Any of Mocks Server options or plugin options. If provided, the config passed in the constructor would be merged with this one. Command line arguments, environment variables and configuration file options would override the values defined here. Options are internally available using the core.config API once they are initialized.

start()​

core.start(): Start the server, plugins, and all other internal elements. Returns a promise. It calls to the init method internally if it was not done before.

stop()​

core.stop(): Stop the server, plugins, and all other internal elements. Returns a promise.

Children objects APIs​

Continue reading to check out the API docs of other objects available in the core instance: