parrot-js v0.2.2

parrot.js

parrot.js captures outbound HTTP and HTTPS traffic, from a node.js application, and redirects it to a server of your choosing. This is useful for performing blackbox testing on an application which would normally require communication with external servers in order to function. The inspiration for parrotjs came from nock.

Usage

To install,

$ npm install parrot-js

At the entrypoint of your application, put this one-liner:

// Only hijack outbound requests in a testing scenario
if (...)
	require("parrot-js").Hijack({ "Host": "localhost", "Port": 1234 });

Any outbound HTTP/HTTPS calls made after this point will not reach their intended destination, but will be redirected instead to http://localhost:1234 with their paths, querystrings and request bodies intact. This, in conjunction with impostor, enables the author of the application to write tests which don't rely on state held across an HTTP API boundary.

The intercepted traffic has an added header, x-parrot-intended-host, indicating the host to which the traffic was originally addressed.

Documentation

parrot.js only has one method:

require("parrot-js").Hijack(Options)

Options is an object with

• Host: required string, the host to which HTTP and HTTPS requests should be redirected.
• Port: required integer, the port to which requests should be redirected.
• Quiet: optional boolean (default false), suppress logging of requests.

Configuration

Beyond specifying the host and port of the interceptor, parrot.js can be configured without code changes via the following optional environment variables:

• PARROT_MODE the behavior for handling requests, either INTERCEPT to intercept and forward to a server under your control (the default), or PASSTHROUGH to allow all requests through to their intended destinations.
• PARROT_HOST_EXCEPTIONS a comma-delimited string, listing hosts that should do the opposite of the chosen mode.

For example,

$ PARROT_HOST_EXCEPTIONS=facebook.com node index.js

will intercept traffic bound for google.com and most other hosts, but it will allow traffic through to facebook.com.

On the other hand,

$ PARROT_MODE=PASSTHROUGH PARROT_HOST_EXCEPTIONS=facebook.com,twitter.com node index.js

will allow traffic through to google.com and most other hosts, but it will intercept traffic bound for facebook.com or twitter.com.

How does it work?

parrot.js works by overriding the request method of the node.js core http and https modules. Any outbound HTTP/HTTPS requests made by your application (including indirectly, through a third party module) eventually use the core modules, so parrot.js captures it all.