gulp-mocker

Gulp Mocker. A mock server can be used with gulp, or run it in command line, or run it programmatically, and more. Enjoy mocking!

Pull requests are welcome :)

License

LGPL-V3

Features

Return mock responses just place files into mock directory

/path/to/api => 'mock/path/to/api|api.json|api.js'

JSONP support

/path/to/api?callback=jsonp => jsonp response with 'mock/path/to/api|api.json|api.js' data

Highly customized response

You can write any kind of response in the js response file.

Fallback to Proxies

// option
{
    fallback: true,
    proxies: [{
        // Proxy option
    }]
}

HTTPS Support

// option
{
    useHTTPS: true,
    httpsOptions: {
        // HTTPS Option
    }
}

Mock File Relocation

// option
{
    mockPathRewrite({ctx, defaultPath) {
        let ret = defaultPath;
        if (defaultPath === '/index.php') {
            const q = ctx.query;
            ret = `/${q.class}/${q.method}`;
        }
        return ret;
    }
}

With Gulp

const gulpMocker = require('gulp-mocker');
gulp.src('whatever')
    .pipe(gulpMocker({
        // Put options here
    }))
    .pipe(// Nothing changed, do whatever you want)

Run it with command line

$ npm install -g gulp-mocker
# Further more, the config file can be ignored!
$ gulp-mock --config mock.config.js

gulp-mock -h for more information

Run it programmatically

const mod = require('gulp-mocker/src/server');
const { webServer, app } = mod.startServer({
    // Options
});

Tested (Not 100% though LOL)

Installation

npm install gulp-mocker

Examples

See "mock" folder

Options

const DEFAULT_OPTS = {
    // {Boolean}: Whether add Allow-Cross-Origin header in response
    allowCrossOrigin: false,
    // {Array<String>|String}: Access-Control-Allow-Headers value
    allowCrossOriginHeaders: ['Origin', 'X-Requested-With', 'Content-Type', 'Accept'],
    // {String}: Access-Control-Allow-Host value
    allowCrossOriginHost: '*',
    // {Array<String>|String}: Access-Control-Allow-Methods
    allowCrossOriginMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
    // {Object}: Config object for koa-bodyparser
    bodyParserConfig: {
        jsonLimit: '100mb',
        formLimit: '100mb',
    },
    // {Object}: Config object for koa-busboy
    busboyConfig: {},
    /*
     *  {Boolean|String}: Whether use fallback. Available values:
     *      false: Not use fallback
     *      true|'proxy': Use fallback if the mock server fail to return response and fallback to proxy
     */
    fallback: false,
    /*
     *  {Array<String|Function>}: What kinds of circumstances are considered as failure.
     *  Available embedded rules:
     *      'emptyBody': If ctx.body is empty
     *      'status404': If the status code is 404
     *      'status500': If the status code is 500
     *  If it's a function, the signature should be like this:
     *      function: boolean ({
     *         // `ctx` of koa.
     *         ctx: Object,
     *      })
     */
    fallbackRules: ['emptyBody', 'status404', 'status500'],
    // {String}: Mock server host name
    host: 'localhost',
    // {Boolean}: Whether use https
    httpsEnabled: false,
    // {Object}: https options for `https.createServer()`
    httpsOptions: {
        key: fs.readFileSync(path.resolve(__dirname, '../ssl/ssl.key')),
        cert: fs.readFileSync(path.resolve(__dirname, '../ssl/ssl.crt')),
    },
    // {String}: Param name of JSONP
    jsonpParamName: 'callback',
    /*
     *  {String}: Logging level. Available values: 'none', 'error', 'warn', 'info'
     *  The levels above are in order. Any levels after the specific level of logging will be ignored.
     */
    logLevel: LEVEL_INFO,
    // {Array<Function>|Function}: Additional koa middlewares
    middlewares: [],
    // {String}: Mock config file name
    mockConfigName: '_.config.js',
    // {Array<String>}: Mock response will try to find files by the following order
    mockExtOrder: ['', '.json', '.js'],
    // {String}: Mock responses files' root path
    mockPath: './mock',
    /*
     *  {Function}: Rewrite the request path to the specified one. By default it won't rewrite.
     *  Note that this option won't affect the url of fallback request
     *  The function has following signature:
     *      function: String ({
     *         // `ctx` of koa.
     *         ctx: Object,
     *         // The request path of default behaviour
     *         defaultPath: String,
     *      })
     */
    mockPathRewrite: null,
    // {Function}: Listener function when the web server starts
    onServerStart: null,
    // {Number}: Port of server
    port: 10086,
    /*
     *  {Array<{
     *      // Matching rule whether to use proxy or not, which can be parsed by path-to-regexp if it's a string. Required.
     *      source: RegExp|String,
     *      // `context` param of http-proxy-middleware. Optional.
     *      context?: String,
     *      // `options` param of http-proxy-middleware. Optional.
     *      options?: Object
     *  }>}: Proxy settings for http-proxy-middleware
     */
    proxies: [],
    /*
     *  {Boolean}: The mock server will scan all mock config files and cache them when the server starts.
     *  It will try to recollect the config files if any of config files changes when it's set to `true`
     */
    watchMockConfig: true,
    /*
     *  {Array<{
     *      // Matching rule whether to rewrite the request, which can be parsed by path-to-regexp if it's a string
     *      // Note that this option will affect the url of fallback request
     *      from: RegExp|String,
     *      // Where the request should be rewritten to:
     *      //      If it's a string, the request path will be replaced by it.
     *      //      If it's a function, the request path will be replaced by the return result of it. The signature should be like this:
     *      //          function: string (result: {
     *      //              // `ctx` of koa.
     *      //              ctx: Object,
     *      //              // `exec` result of RegExp object .
     *      //              exec: Array,
     *      //              // Keys from path-to-regexp. Available when `from` is a string.
     *      //              keys: Array,
     *      //          })
     *      to: String|Function
     *  }>}
     */
    rewrites: [],
};

Mock Config File

// Note: All the options will be merged shallowly
module.exports = {
    /**
     * Wrapper
     * Only works for json response.
     * Default: null
     */
    /**
     * Static Response Wrapper
     * If the value of "wrapper" is a plain object, it will be a "Static Response Wrapper"
     * All responses will wrap the same format of wrapper,
     * and the "Wrapper Content Placeholder" will replace the response content
     */
    // wrapper: {
    //     code: 200,
    //     msg: 'success',
    //     data: '{{!--WrapperContent--}}',
    // },
    /**
     * Dynamic Response Wrapper
     * If the value of "wrapper" is a function, it will be a "Dynamic Response Wrapper"
     * All responses can be handled manually by you. And you should return a JSON object.
     * @param {Object}
     *      ctx {Object}: context of koa
     *      resResult {Object}: mock response content
     *      helpers: {Object}: See "Helpers"
     * @returns {Object|Promise<Object>}: Dynamic wrapper processed response. The Object should have the following structure
     *      body {*}: The value will be set as the koa's body of ctx
     *      contentType? {String}: Optional. The value will be used as content type if it's set.
     *      status? {Number}: Optional. Response status code.
     */
    // wrapper: function({ ctx, resResult }) {
    //     // Do whatever you want
    //     return {
    //         body: ctx.body,
    //     };
    // },

    /**
     * Wrapper Content Placeholder
     * Default: {{!--WrapperContent--}}
     *
     * This string will be replaced by the response data in the wrapper.
     * Only works for Static Response Wrapper
     */
    wrapperContentPlaceHolder: '{{!--WrapperContent--}}',

    /**
     * Mock Type
     * Default: 'normal'
     *
     * Available values:
     * normal: It will try to find certain kinds of extensions of file by the request path. See the config's "mockExtOrder" property.
     * mockjs: Responses will be treated as the parameters of MockJS after the process of "normal"
     */
    mockType: 'normal',

    /**
     * Delay
     * Default: 0
     *
     * Response delay emulation in millisecond.
     */
    delay: 0,

    /**
     * Pass through Proxy
     * Default: false
     *
     * Any request will pass through the proxy directly. Only available when the fallback is proxy and the proxy is available.
     */
    passThroughProxy: false,

    /**
     * Additional http headers for responses.
     * eg. {'Etag': '1234'}
     * Default: Empty object
     */
    headers: {},
};

Dynamic response

/**
* @returns {Object|Promise<Object>}: A response generated by js should return the following structure:
*      body {*}: The value will be set as the koa's body of ctx
*      contentType? {String}: Optional. The value will be used as content type if it's set.
*      headers? {Object}: Optional. Additional http headers for responses. eg. {'Etag': '1234'}
*                         In addition, headers in dynamic response will override headers in mock config file
*                         if they have same keys.
*      passThroughProxy? {Boolean}: Optional. Request will pass through the proxy directly.
*                                   Only available when the fallback is proxy and the proxy is available.
*      status? {Number}: Optional. Response status code.
*/

Helpers

/**
 * Helpers
 * It's a group of tools that help you to make dynamic responses. It has the following properties:
 *
 *    // `mime` from npm: https://www.npmjs.com/package/mime
 *    mime,
 *
 *    // `mockjs` from npm: https://www.npmjs.com/package/mockjs
 *    Mock,
 *
 *    // Generate a stream of image
 *    // @param opts: {
 *    //          // Size of image by pixel. Format: `${width}x${height}`
 *    //          size: string,
 *    //          // Background color of image
 *    //          background: string,
 *    //          // Foreground color of text
 *    //          foreground: string,
 *    //          // Format of image. Available values: png, jpg, gif
 *    //          format: string,
 *    //          // Foreground text content
 *    //          text: string,
 *    //      }
 *    // @returns {Promise.<stream>} The stream of image
 *    genImageStream: function,
 *
 *    // Generate a image response
 *    // @param opts {Object}: The same as genImageStream
 *    // @returns {Promise.<Object>} The response for dynamic response
 *    genImageResponse: function,
 *
 *    // Merge query, post body, parameters from request
 *    // @param ctx: `ctx` of koa
 *    // @returns {Object}
 *    mergeParams: function,
 */

TODO list

• More test cases.
• Generate image response by myself instead of depending other online services.
• More other features.