connect-mock-api v1.2.0
Connect Mock API
Express / Connect middleware for programmable fake APIs
Installation
npm install connect-mock-api --save
Usage as an express/connect middleware
const express = require('express');
const mockApiMiddleware = require('connect-mock-api').middleware;
const app = express();
const mocks = mockApiMiddleware({
baseUrl: '', //optional
endpoints: [
//... endpoints configuration object here, see below
]
});
app.use(mocks);
app.listen(8000);
Endpoint Configuration
Endpoints are objects with the following properties:
method
(string
): The expected methods of the incoming request (default:GET
),path
(string|regexp|function
): the path to match relative to the root URL. If a function it must return a string or a regular expression (default:null
),delay
(number|function
): force a delay in milliseconds for the response. If a function it must return a number (default:0
),contentType
(string
): Response content type (default:application/json
),template
(*|function
): Response body template. Could be any type of content in relation to theContentType
parameter. If a function it will be executed with aparams
object and theendpoint
itself as arguments. (default:null
)
Note: The params
object contains 3 properties:
$req
: the original express / connect request object$parsedUrl
: The request URL parsed by NodeJS nativeurl.parse
method$routeMatch
: either an object (whenpath
is a string) or an array of matched segments (whenpath
is a regular expression). See below for details.
Path Matching Formats and $routeMatch
Endpoint's path
configuration could be a plain string, a regular expression or a string with Express-like parameters (see path-to-regexp for details).$routeMatch
format will vary based on the provided path
:
- regular expression:
$routeMatch
will be the resulting array of callingRegExp.prototype.exec
on it - string or Express-like route:
$routeMatch
will be and object with named parameters as keys. Note that even numeric parameters will be strings. Examples:
/* Plain string */
{
path: '/api/v1/users'
// /api/v1/users/ -> $routeMatch === {}
}
/* Express-like path */
{
path: '/api/v1/users/:id'
// /api/v1/users/10 -> $routeMatch === {id: '10'}
}
/* RegExp */
{
path: /^\/api\/v1\/users\/(\d+)$/
// /api/v1/users/10 -> $routeMatch === ['/api/v1/users/10', '10']
}
Endpoint response template
Any key in the response template could be either a plan value or a function. If a function, it will be executed at response time
with a params
object and the endpoint
itself as arguments.
Note: The params
object contains two property:
$req
: the original express / connect request object$parsedUrl
: The request URL parsed by NodeJS nativeurl.parse
method$routeMatch
: either a boolean (whenpath
is a string) or an array of matched segments (whenpath
is a regular expression)
Endpoint Base URL
The baseUrl
configuration option sets up a base URL for every relative endpoint path provided. To override the base URL use absolute URLs.
Note: baseUrl
applies just to string paths.
const mocks = mockApiMiddleware({
baseUrl: '/api/v1/', //optional
endpoints: [
{
// this endpoint will respond at /api/v1/users
path: 'users',
template: {
// ...
}
}, {
// this endpoint will respond at /custom/path
path: '/custom/path',
template: {
// ...
}
}
]
});
Examples
1) A basic GET endpoint returning a JSON object
const enpoint = {
path: '/api/v1/user',
template: {
name: 'John',
surname: 'Doe'
}
};
2) A GET endpoint returning a dynamic data provided with Chance
const chance = require('connect-mock-api/lib/utils').chance;
const enpoint = {
path: '/api/v1/user',
template: {
name: () => chance.first(),
surname: () => chance.last()
}
};
3) A GET endpoint matching a regexp and returning a dynamic property based on the match
const chance = require('connect-mock-api/lib/utils').chance;
const enpoint = {
//matches either a male of female user request
path: /\/api\/v1\/user\/(male|female)$/,
template: {
name: (params) => chance.first({
gender: params.$routeMatch[1]
}),
surname: (params) => chance.last({
gender: params.$routeMatch[1]
})
}
};
4) A GET endpoint matching a regexp and returning a dynamic template based on the match
const chance = require('connect-mock-api/lib/utils').chance;
const enpoint = {
path: '/api/v1/:frag',
template: (params) => {
//calling /api/v1/user
//params.$routeMatch === {'frag': 'user'}
if (params.$routeMatch.frag === 'user') {
return {
name: () => chance.first(),
surname: () => chance.last()
};
}
return {
error: 'Not matching anything'
};
}
};
5) A POST endpoint, accepting a body request and returning a success message
Note: to parse the request body you should append body-parser middleware to the express / connect middleware list.
const enpoint = {
path: '/api/v1/send',
method: 'POST',
template: (params) => {
if (!params.$req.body.username || !params.$req.body.password) {
return {
success: false,
msg: 'You must provide a username and a password'
};
}
return {
success: true,
msg: 'Succesfully logged in!'
};
}
};
Contributing
- Fork it or clone the repo
- Install dependencies
npm install
- Run
npm start
to launch a development server - Code your changes and write new tests in the
tests
folder. - Ensure everything is fine by running
npm test
andnpm run eslint
- Push it or submit a pull request :D
Credits
Created by Marco Solazzi