impostor

impostor is a standalone node.js HTTP server which is programmable at runtime. The URLs to serve, and the data to be served, are configurable on-the-fly. This is particularly useful for black-box testing of your application, in conjunction with a library like parrot.js which can redirect all of your application's outbound HTTP/S traffic to an impostor server. Test scenario #1 may need GET /data to respond with a 403 while test scenario #2 expects actual data from the same request. impostor makes this possible without any reliance on external state (e.g. in third party services).

How to use it

impostor is run by invoking

$ npm install impostor
$ ./node_modules/.bin/impostor.js 1234

where 1234 is the port the impostor server should listen on. The module can also be installed globally with npm install -g.

Afterwards, it is controlled by sending HTTP requests to the running server (localhost:1234 in the example above). There are only two commands:

1. POST /__clean__

With no payload, returns impostor to a clean slate (erases all routes).

Optionally, specify both of the following in order to erase response(s) for a specific route:

• Method string (HTTP verb), e.g. GET. This is case-insensitive.
• Path string, e.g. /path/to/resource. This does not include querystring.

2. POST /__set__

The __set__ command is used to create a route for impostor to serve. This command expects a JSON payload, an object with the following properties:

• Method required string (HTTP verb), e.g. GET. This is case-insensitive.
• Path required string, e.g. /path/to/resource. This does not include querystring.
• Parameter optional string, name of querystring/body parameter on which to filter requests.
• Value optional. If Parameter is specified, the request parameter is matched against Value.
• Header optional string, name of header on which to filter requests.
• HeaderValue optional. If Header is specified, the request is only matched if the relevant header contains (case-insensitive) HeaderValue as a substring.
• BodyRegExp optional string. If provided, a request will only match if its body matches new RegExp(BodyRegExp).
• Response required object
  • Status optional integer (default 200).
  • Text optional string, a plaintext response body to send back.
  • BodyBase64 optional string, a base64-encoded string response to send back.
    • One of Text or BodyBase64 should be specified. BodyBase64 takes precedence if both exist.
  • Headers optional object.

After this call is made, a route is created which will respond, as instructed, to the described request. For instance, if Method = GET, Path = /a/b/c and Response.Text = welcome, then a subsequent GET /a/b/c directed at the impostor server will return the text welcome.

Once a route has been created with /__set__, it remains there until /__clean__ is called (or the impostor server is killed). In particular, it does not go away after serving one request.

If the impostor server receives a request to which it hasn't been programmed to respond, it will serve a status code 404 with Content-Type: application/json and body {}.

Parameter matching

In the case that an intercepted request's body is successfully parsed into a javascript object, you can walk the object's hierarchy by passing a .-delimited (period-delimited) path for the Parameter option. In other words, if your intercepted request's body looks like

{
	"abc":
	{
		"def":
		{
			"ghi": 123
		}
	},
	"jkl": 456
}

then a Parameter option of abc.def.ghi will match a value of 123. There is currently no support for traversing arrays.

Request parsing

If an intercepted request has a content-type header of application/x-www-form-urlencoded, then it will be parsed using the native node.js querystring::parse. For a request with any other content-type value, an attempt will be made to parse the body as JSON.

Examples

Setup for a typical black-box test scenario would involve invoking /__clean__ and then hitting /__set__ once for each external resource required for the test to execute.

# Set up the impostor server on port 1234
$ ./impostor.js 1234

In another terminal:

# Haven't set up a matcher, so this gets the fallback 404 response.
$ curl http://localhost:1234/test
{}

# Set up /test to respond with "welcome!"
$ curl http://localhost:1234/__set__ \
	--header "Content-Type: application/json" \
	--data '{"Method":"GET","Path":"/test","Response":{"Text":"welcome!"}}'

# Try again
$ curl http://localhost:1234/test
welcome!

# Clean up
$ curl http://localhost:1234/__clean__ --request POST
$ curl http://localhost:1234/test
{}

Differentiate between querystring parameters:

# /user?id=1 should return { "name": "alice" }
$ curl http://localhost:1234/__set__ \
	--header "Content-Type: application/json" \
	--data '{"Method":"GET","Path":"/user","Parameter":"id","Value":1,"Response":{"Text":"{\"name\":\"alice\"}","Headers":{"Content-Type":"application/json"}}}'

# /user?id=2 should return { "name": "bob" }
$ curl http://localhost:1234/__set__ \
	--header "Content-Type: application/json" \
	--data '{"Method":"GET","Path":"/user","Parameter":"id","Value":2,"Response":{"Text":"{\"name\":\"bob\"}","Headers":{"Content-Type":"application/json"}}}'


$ curl http://localhost:1234/user?id=1
{"name":"alice"}

$ curl http://localhost:1234/user?id=2
{"name":"bob"}

Differentiate between body parameters in the same way:

# POST /user { "username": "alice" } should return { "id": 101 }
$ curl http://localhost:1234/__set__ \
	--header "Content-Type: application/json" \
	--data '{"Method":"POST","Path":"/user","Parameter":"username","Value":"alice","Response":{"Text":"{\"id\":101}","Headers":{"Content-Type":"application/json"}}}'

# POST /user { "username": "bob" } should return { "id": 102 }
$ curl http://localhost:1234/__set__ \
	--header "Content-Type: application/json" \
	--data '{"Method":"POST","Path":"/user","Parameter":"username","Value":"bob","Response":{"Text":"{\"id\":102}","Headers":{"Content-Type":"application/json"}}}'

$ curl http://localhost:1234/user --request POST --data '{"username":"alice"}' --header "Content-Type: application/json"
{"id":101}

$ curl http://localhost:1234/user --request POST --data '{"username":"bob"}' --header "Content-Type: application/json"
{"id":102}

$ curl http://localhost:1234/user --request POST --data '{"username":"abcd"}' --header "Content-Type: application/json"
{}

Querystring parameters and body parameters are both filtered in the same way (demonstrated above). If there are identically named parameters in the querystring and body, the querystring value will take precedence.