ToxiProxy allows you to create a controllable proxy between your app and a remote service when you want to test network reliability and related effects.

It can be downloaded in command line executable form that, when run, will start up a web service on port 8474. You can configure it using a REST client (eg Postman or cURL).

Say you want to configure a proxy for a remote service running on somewhere.else.com:2000. You can proxy it to localhost:3000 by POSTing this:

{
"listen":"localhost:3000",
"upstream":"somewhere.else.com:2000"
}

You can then GET, and update via a POST, this proxy at http://localhost:8474/proxies/badendpoint

By default the proxy will be enabled. You can change this, or anything else about it, by POSTing to that URL:

{
"listen":"localhost:3000",
"upstream":"somewhere.else.com:2000",
"enabled": false
}

In this example above the proxy has been disabled - which can be used to simply test network disconnections.

Once you have a proxy you can add "toxics" to it, which simulate a variety of faults. The currently configured toxics for your proxy can be seen by making a GET request to:

http://localhost:8474/proxies/yourproxyname/toxics

To add a toxic simply post a toxic definition to the same endpoint. This example sets a timeout of 0 to the upstream proxy, which means hang forever when making the request:

{
"type": "timeout",
"stream": "upstream",
"attributes": {
"timeout": 0
}
}

Take a look at the toxics section of the main docs to see what can be set - these include latency, jitter, bandwidth limits or custom ones.

All of this can be performed programmatically too if you want to incorporate this into your testing framework.