fake-rest-server v0.1.11
#fake-rest-server
Fake-rest-server is a generic and non-intrusive tool used to mock any http server response. It has been designed to address issues when running tests against unstable or slow external servers. It is an extension to yahoo/fake-server.
===========
How it works
The idea is to create a webserver listening in a different port and make your tests bring it up and configure how it should behave against each different request. Server response can be configured by posting the parameters and desired response to the server, or through configuration files inside ./default_routes/
.
For every request, fake-server will try to match against the configured URIs and return the expected response.
Advantages
- No need to instrument your code (as long as the external server endpoint is configurable :P)
- Generic enough to work with blackbox or whitebox tests.
- No database required
Requirement
node >= 0.10.x
npm >= 1.4.x
Installation
fake-rest-server
is available on npm
$ [sudo] npm install fake-rest-server -g
$ fake-rest-server
or
$ git clone git@github.com:crazylab/fake-server.git
$ cd fake-server
$ npm install
$ npm start
The server will start at http://localhost:3012
. To configure the fake-rest-server PORT
and DEFAULT_ROUTES_PATH
, see the Server Configuration section.
Command Line Options
Fake server can be started as a background process using the following command
$ fake-rest-server --start
To stop the server started using the above command run
$ fake-rest-server --stop
Quickstart (two really basic scenarios)
Let's say you want /test
to always return "hello" and /foo
to return a 404.
Add Endpoint
All you have to do is POST
to http://localhost:3012/__add
the following data:
Configure /test
by posting:
{
"route": "/test",
"responseCode": 200,
"responseBody": "hello"
}
one of the many ways to do this is using cURL:
curl http://localhost:3012/__add -X POST -H "Content-Type:application/json" -H "Accept:application/json" -d '{"route":"/test","responseCode":200,"responseBody":"hello"}'
now let's configure our 404
example by sending this to the server:
{
"route": "/foo",
"responseCode": 404,
"responseBody": "Not found"
}
using cURL:
curl http://localhost:3012/__add -X POST -H "Content-Type:application/json" -H "Accept:application/json" -d '{"route":"/foo","responseCode":404,"responseBody":"Not found"}'
now, in your browser you can see the results:
Remove Endpoint
It is always a good practice to remove the the configured endpoint in the "teardown" part of your test.
You can remove the previously added 404
example configuration by sending a DELETE
request to http://localhost:3012/__remove
with the same configuration json:
{
"route": "/foo",
"responseCode": 404,
"responseBody": "Not found"
}
This will remove /foo
endpoint. If there are multiple foo
endpoint configured, it will remove the best matched endpoint only.
What else can fake-server do?
Configuration is done by sending a POST
request to /__add
or by placing a JSON file containing configurations inside a "routes" object (see example below for reference). Here are the supported features for this version:
Routes can be RegEx
This will match http://localhost:3012/news/007
as well as http://localhost:3012/news/1231293871293827
:
{
"route": "/news/[0-9]",
"responseCode": 200,
"responseBody": "whatever you want"
}
Fake-rest-server supports "POST" calls and uses payload for matching. RegExs are supported for payload matching, and paths can be used to specify inner properties of JSON payloads:
{
"route": "/news",
"payload": {
"id": "[\\d+]",
"requests[1].user.login": "jdoe",
"month" : "february"
},
"responseCode": 200,
"responseBody": "yay! it matches"
}
The above configuration will match a POST
request to http://localhost:3012/news
with a similar payload as follows:
{
"id" : 1,
"requests" : [{}, { "user" : { "login" : "jdoe"}}],
"month" : "february"
}
Support for query string matching. All query params are evaluated as a RegEx.
{
"route": "/news",
"queryParams": {
"id": "[\\d+]",
"location": "Hawaii"
},
"responseCode": 200,
"responseBody": "Regex matching rocks"
}
... can also use the request Headers. So you can check if specific cookies are present, for instance
{
"route": "/secure",
"requiredHeaders": {
"X-Auth": "secret"
},
"responseCode": 200,
"responseBody": "header is there"
}
Response can be a file. In this case, fake-server will respond with the output of that file.
The following configuration example will return the output of ./mock_data/sample.json
. The file path will be relative from where the server is running. (notice the parameter is called responseData
instead of responseBody
)
{
"route": "/",
"responseCode": 200,
"responseData": "./mock_data/sample.json"
}
Same endpoint can have different responses.
This will return 200
in the first two requests to /
and 403
on the third request.
{
"route": "/",
"responseCode": 200,
"responseBody": "ok"
}
Note that I will be adding an at
parameter to configure the special behavior to the third request:
{
"route": "/",
"responseCode": 403,
"responseBody": "Thou shall not pass!",
"at": 3
}
Delay response
The following will delay server response by one second:
{
"route": "/slow/.*",
"responseCode": 200,
"responseBody": "OK",
"delay": 1000
}
Resetting server configuration
To avoid the need to restart fake-server in order to clear the configuration, we've implemented a special endpoint called /__flush
. By sending a DELETE
request to http://localhost:3012/__flush
, you will erase all previously configured responses refreshing the default router configuration.
Server Configuration
The server can be configured by putting a fake-rest-server.conf
file in the directory where the server is running. Below is a sample configuration file.
{
"PORT": 3000,
"DEFAULT_ROUTES_PATH": "./default_routes",
"LOG_DIR": "./logs"
}
PORT
specifies the server port, in this case3000
.DEFAULT_ROUTES_PATH
the server will load all the.json
files from this directory to pre-configure itself with the specified routes on server start. Below is a sampledefault_routes.json
file.
{
"routes":[
{
"route": "/test/one",
"responseCode":200,
"responseBody": "it works very very fine"
},
{
"route": "/test/two",
"responseCode":200,
"responseData": "./mock_data/sample.json"
},
{
"route": "/test/three",
"requiredHeaders": {
"Cookie": "username=.*"
},
"responseBody": "headers match :-)"
}
]
}
Notice that it is same as any other configuration that we have previously seen. Just that this one is a array of such configuration.
LOG_DIR
specifies directory path where the server logs will be stored when it is started in background using--start
option.
Limitations
- There are three reserved endpoints:
POST
/__add
,DELETE
/__remove
and/__flush
. These cannot be used by your application. We are considering, any endpoint starting with__
will be reserved and will be used for further extention of this tool. - Does not supports
https
connections, yet.
To-Do
- Add more unit tests and integration test
- Support for all types of request like
PUT
etc. - Expose API to take dump of current configuration for later reloading