Toxiproxy — Simulate Network Conditions for Resilience Testing

Introduction

Toxiproxy is a framework developed by Shopify for simulating network conditions in testing, CI, and development environments. It sits between your application and its backend dependencies, injecting faults like latency, bandwidth restrictions, and connection resets. This lets you verify that your code handles degraded network conditions gracefully before they happen in production.

What Toxiproxy Does

• Creates TCP proxies between your application and any upstream dependency (databases, APIs, caches)
• Injects configurable toxics including latency, jitter, bandwidth throttling, slow close, and connection reset
• Provides a REST API and CLI for adding, removing, and modifying toxics at runtime
• Supports upstream and downstream toxic directions to simulate problems on either end
• Integrates with test suites through client libraries for Ruby, Go, Python, Java, .NET, and more

Architecture Overview

Toxiproxy runs as a single server process that listens on configured proxy ports and forwards traffic to upstream endpoints. Each proxy maintains a toxic chain — an ordered pipeline of transformations applied to data flowing through the connection. Toxics are applied per-direction (upstream or downstream) and can be stacked. The server exposes a REST API on port 8474 for managing proxies and toxics programmatically. The lightweight design adds minimal overhead when no toxics are active.

Self-Hosting & Configuration

• Download a single binary from GitHub releases or install via Homebrew, apt, or go install
• Start toxiproxy-server on a known port (default 8474 for API, proxies on configured ports)
• Define proxies in a JSON config file and load them at startup with toxiproxy-cli populate
• Point your application connection strings to Toxiproxy listen addresses instead of real endpoints
• Run alongside your CI pipeline to inject faults during integration test suites

Key Features

• Zero-config proxying — when no toxics are applied, traffic passes through with negligible overhead
• Deterministic testing — inject exact latency values and failure modes for reproducible test scenarios
• Client libraries for major languages enable adding and removing toxics within test setup and teardown
• Supports both TCP and Unix socket proxying for local development scenarios
• Lightweight single binary with no external dependencies

Comparison with Similar Tools

• tc (Linux Traffic Control) — Kernel-level network shaping that affects all traffic system-wide rather than per-dependency
• Chaos Mesh — Kubernetes-native chaos engineering platform with broader fault types but requires a K8s cluster
• Pumba — Docker-focused chaos tool for container network emulation, but limited to Docker environments
• Comcast — Simulates bad network conditions at the OS level but lacks per-connection granularity and a management API

FAQ

Q: Does Toxiproxy add latency when no toxics are configured? A: No. Without active toxics, Toxiproxy acts as a pass-through TCP proxy with negligible overhead (sub-millisecond).

Q: Can I use Toxiproxy in production? A: Toxiproxy is designed for testing environments. For production resilience testing, consider a service mesh with fault injection or a chaos engineering platform.

Q: How do I reset all toxics between tests? A: Call the POST /reset endpoint or use toxiproxy-cli reset to remove all toxics from all proxies at once.

Q: Does it support HTTP-specific faults like status code injection? A: No. Toxiproxy operates at the TCP layer. For HTTP-level fault injection, combine it with an HTTP proxy or use a service mesh.

Sources

• https://github.com/Shopify/toxiproxy
• https://shopify.engineering/building-and-testing-resilient-ruby-on-rails-applications