Mockium is a simple but powerful CLI mock server based on Node.js technology. Its main purpouse is to offer to developers the posibility of building up their own mock-server in an easy and confortable way.

Surprisingly, you will see the server running in your terminal, with all the logs that you could expect, as well as a CLI aside letting you to switch among diferents features in live. No reload is required.

Mocking is cool!

Table of Contents

1. Why should I use Mockium?
2. Installation
3. Windows users
4. Usage
5. Configuration
6. CI mode
7. Getting started
8. Feature
9. Mock
10. Scaffolding
11. Dynamic responses
12. Project example

Why should I use Mockium?

There are a lot of mock server in the Node.js ecosystem. Most of them, great packages with a lot features. Besides, Mockium offers us a simple way to load our mocks with minimum rules, plus the following characteristics:

• Simple installation and boostrap
• Easy way to mock your server responses
• Scalable way to extend features and mocks
• Hot feature exchange. Choose your feature in live. No reloads are needed
• Hot mock and features reloading. You can extend and modify your mocks and features without having to stop an restart the process
• UMD compatibility mode
• Continuous Integration ready

Installation

Install Mockium using npm:

npm i -g mockium

Mockium should be installed as global dependancy. It is necessary for using the command wherever you need in any project on your system. Furthermore, you will notice that stmux is installed as a global dependency too. It is a command-line tool which permits to Mockium to split and manage terminal activities throughout tmux.

Alternatively, you could install Mockium as a local dependancy. In this case, you will need to add a command in your scripts section in your package.json:

// package.json
{
...
    "scripts": {
        ...
        "mockium": "mockium"
    }
}

On the other hand, you could want to use it as a not installed dependancy with npx instead of npm installation:

npx mockium

It is discouraged because this command will download always third dependancies, like stmux, which increases the execution time.

Windows users

Mockium uses stmux as terminal window manager (based on tmux), which implies that it is mainly focused on Unix system users. Although it is completly functional in Windows systems too, it is necessary to install additional software in this operative system, in order to enjoy Stmux experience properly

• You will need to install Windows build tools in its 2015 version. It is important because node-gyp (which is the Node.js tool for building packages) in Windows is only compatible with 2015 Visual Studio tools. To do that, yo have to type this command in your windows terminal (with admin privileges):

npm install --global --production windows-build-tools --vs2015

• Next, you will need to set the version of Visual Studio tools in npm, throughout the following command:

npm config set msvs_version 2015 –global

Python 3 users (on Windows)

This process will install Python as development dependency waiting for 2.7.x version. Perhaps, you could have installed another different version (such as 3.x.x) which is not compatible with windows-build-tools. Just in that case, you will need to do an extra step and install the 2.7.x version from the official Python download website.

Finally, you only need to tell Node.js what Python version needs to use:

npm config set python python2.7

Usage

Just one command and the magic happens:

mockium

Mockium will understand that all your features and mocks are placed in the root folder of your project, inside features and mocks folder by default. Of course, you can change this configuration using some of the following optional parameters:

| Property | Default | | | -------------------------- | -------- | --------------------------------------------------- | | -s, --server-folder  | . | Relative path that contains all the Mockium's stuff | | -f,  --features-folder  | features | Name of the folder that contains features files | | -m,  --mocks-folder  | mocks | Name of the folder that contains mocks files | | -e, --features-extension  | feature | Extension chained to the feature file name | | -x, --mocks-extension  | mock | Extension chained to the mock file name | | -b,  --feature-base  | base | Name of the base feature file | | -p, --server-port  | 5000 | Port where the server will be deployed | | -r,  --server-bridge-port  | 5001 | Port where the socket server will be deployed | | -c,  --ci  | false | Continuous Integration mode. No UI and REST based |

Configuration

According to the previous table you can configure Mockium throughout parameters in the command. But the tool offers some alternatives, in order to make the process easier to set up.

The same config options could be setted in two different and optional ways:

• package.json file You can set all the configuration in the package.json file using a mockium custom property.

// package.json

{
    "name": "my-project",
    "version": "1.0",
    ...
    "mockium": {
        "serverFolder": "./mockium-files",
        "mocksFolder": "mocks",
        "featuresFolder": "features",
        "extension": "feature",
        "mocksExtension": "mock",
        "base": "base",
        "serverPort": 9000,
        "socketPort": 5001
    }
}

• .mockiumrc file You can set all the configuration in a custom .mockiumrc file placed in the root of the project.

// .mockiumrc

{
  "serverFolder": "./mockium-files",
  "mocksFolder": "mocks",
  "featuresFolder": "features",
  "extension": "feature",
  "mocksExtension": "mock",
  "base": "base",
  "serverPort": 9000,
  "socketPort": 5001
}

However, although you can set all the configuration in the inside the object, it is not mandatory. All the properties are optional and can be setted independently of each other.

Continuous Integration mode

Indeed Mockium has been created to offer a great experience to developers throughout its marvelous UI feature selector, but the tool comes with a CI mode that runs in a simpler way, with a only process too.
All the functionalities are present in this mode, but it uses a different way to interact with it.

As the process is running without an UI for changing features, it is necessary to make http calls at POST /mockium--change--feature.
This endpoint expects a body object with a feature property with the name of the new feature to be setted.

POST http://localhost:5000/mockium--change--feature

# Payload

{
    "feature": "newWonderfullFeature"
}

Just in case the feature is not present in the body object, or it doesn't match with any of the provided features, base feature will be setted instead.

For running this CI mode you just have to use this command:

mockium -s ./mockium-files-path --ci

Getting started

Mockium needs to be fed with feature files. All the structure and extensions showed in this manual are completly optionals. They all can be overwritten by command params.

The server has two main actors: features and mocks files. They perform the actual framework of this module.

Features

In Mockium, features are a group of mocks. It means that we can define diferent features using diferent mock files and reuse them.

These files has to accomplish the following model:

| Property | Required | Type | Value | | ----------- | -------- | -------- | --------------------------- | | name | * | string | Name of this feature | | description |   | string | Description of this feature | | mocks | * | array | List of mock objects |

e.g.

// mockium-files/features/base.feature.js

const mock1 = require("../mocks/mock1.mock");
const mock2 = require("../mocks/mock2.mock");
...

module.exports = {
    "name": "myFeature",
    "description": "The awesome data that this feature contains",
    "mocks": [
        mock1,
        mock2,
        ...
    ]
}

Mocks

A mock object is presented as a real response to a server request. The mock's model has to respect some defined properties:

| Property | Required | Type | Value | | --------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | | url | * |  string | Server url which will be mocked. Query and url params are supported | | method | * | string | Http verb of the request (GET, POST, PUT ...) | | request | | object | Properties related to the request | | request.headers | | object | Map of request headers (key/value expected) | | request.body | | object | Map of request sent values in a no GET format | | response | * | object | Properties related to the request | | response.status | * | number/string | Response Http code (200, 201, 400, 500 ...) | | response.body | | object/function | Object with the response data of the request. Optionally, It could be a function, which will be called to execute the response |

e.g:

// mockium-files/mocks/mock1.mock.js

module.exports = {
    url: "/some_url/:id/resource?filter=smth",
    method: "GET",
    request: {
        headers: {
            Accept: "application/json"
        }
    },
    response: {
        status: 200,
        body: {
            "someData": {
                ...
            }
        }
    }
}

All the modules can be performed in a CommonJS way as well as in a ESMolues way. It means that the both main systems (require and import) are supported in features and mocks.

Dynamic responses

The mock object can set the body object as a function that takes as unique argument the request object provided. This object is the real Express request object, which works as it is mentioned in its official documentation.

// mockium-files/mocks/mock1.mock.js

module.exports = {
    url: "/some_url/:id/resource?filter=smth",
    method: "GET",
    request: {
        headers: {
            Accept: "application/json"
        }
    },
    response: {
        status: 200,
        body: function(req) {
                // ... some req evaluations
                return {
                "someData": {
                    ...
                }
            }
        }
    }
}

Scaffolding

Mockium gives you whole freedom to organize your features and mocks as you want. No rules are defined at this point.

The library proposes a scaffolding, but you are completly free of choosing whichever you think that fits better for your project:

project
+-- mockium-files
|   +-- features
|   |   +-- base.feature.js
|   |   +-- other.feature.js
|   +-- mocks
|   |   +-- mock1.js
|   |   +-- mock2.js
|   |   +-- mock3.js

# command to launch
# mockium -s ./mockium-files -f features -m mocks

Feature files

As convention, the library will be looking for files with feature as default subextension (e.g. my_atonishing.feature.js). Besides, you can always change this subextension using the optional --features-extension parameter exposing your preference.

mockium --features-extension my-flag
# Our features would be namely xxxx.myflag.js

Mock files

However, you are completely free to organize and name your mock files, since they will be imported into the features.

Feature base

Mockium needs to load a base feature as default. It is mandatory to use a base feature. The reason is because the library have to deploy the regular services in order to cover, at least, the happy path. However, the rest of the features will be loaded on top of the base, overwritten or extending the endpoints registered as intial base feature.

In order to change the name of the base feature file you need to use the --features-base flag as optional command:

mockium --features-base happypath
# The base feature would be named as happypath.feature.js

Project example

Although Mockium is an easy and intuitive tool, some users need to get a start point, in order to test and learn more about it. For this reason, we provide an example project which contains all necessary stuff to start working with Mockium in a real project.

The project has an initial scaffolding with features and mocks ready to be used. In addition, you will find a client based on express that consumes the exposed endpoints in the mock server.