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, eitherINTERCEPT
to intercept and forward to a server under your control (the default), orPASSTHROUGH
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.