groundhog
A tool to record and playback API responses to allow for predictable automated testing.
'groundhog --record' creates a proxy which records any requests that pass through it, so that they can be played back at a later date.
Installation
npm install -g groundhog
Usage
Usage: groundhog [--record [name]]
Attempts to load configuration options from a ".groundhog.json" if it exists in the current working directory.
--record record the current session
if a name is provided then the recording file is given that name, otherwise it is
named with the current timestamp
CLI Config Options
--hostname host to which to proxy requests
--config load the options from a config file specified (default ./.groundhog.json)
--playback playback the recordings from a specific recording file (default: last recording created)
--dir directory in which to read/write playback files
--port port to listen on (default: 3001)
--protocol protocol to run (default: http)
--strict only serve recordings in playback mode
Config
Example
dir
Sets the directory in which recording files are written
hostname
Hostname of the internal service
protocol (optional)
Protocol of the external service - http|https
- default http
port (optional)
Port groundhog will proxy on - default 3001
strict (optional)
Enabling strict mode will return a 500 response in playback mode if a recording does not exist - default false
Multiple Proxies
If you want to proxy more than one service then you can define your proxies as an array. The properties for each host are as above.
Sample
cd samplenpm install
You are running a simple transparent proxy from your server to a backend that is defined in config.js or by environment variable.
# what am i running?cat app.js
Our .groundhog.json
is where we define where we want to store the tests,
and proxies we want to use.
In this case we are saving the recordings to ./test/recordings
and proxying
anything that goes against port 3003
to the yld.io
website
cat .groundhog.json
"dir": "./test/recordings""proxies":"hostname": "yld.io""port": 3003"protocol": "http"
We can now use environment variables to change our website to connect to our
proxy, diverting the traffic that normally would go directly against the backend
(see test/run
):
_PROXYTO=http://localhost:3003 _APPPORT=1337 node app.js
Our test is simple, it runs a request and checks for errors. It uses the same config file so as long as your environments variables are set right this will consistently
# what am i testing?cat test/index.js
If you run the test with our script you will get a lot of warnings, we know
you are trying to run mocked tests and we couldn't find any mocks. Setting
"strict": true
in your .groundhog.json
file will make this throw.
This is useful since these interactions are sometimes meaningful, and if a previous request was not executed (eg. login) the subsequent requests might not work properly.
# run tests./test/run
If you record the results, and run again, it should be out of warnings. Everything was returned from mocks.
# record test results./test/run --recordls test/recordings# run tests using recordings./test/run
Of course, don't forget to run the real tests. If they break and mocks don't, you might have a problem.