ChaosProxy

The localhost saboteur. Test your UI's resilience by breaking your API on purpose.

🚩 The Problem

Local development environments are too perfect. On localhost, requests are instantaneous and servers never fail. But in the real world, networks are flaky, APIs time out, and dependencies crash.

If you only test against a "perfect" backend, you're ignoring the most critical parts of your User Experience: Loading states, Error boundaries, and Network retry logic.

ChaosProxy solves this by sitting between your frontend and your backend, intentionally injecting chaos into your requests so you can build a truly resilient application.

🚀 Installation

Install ChaosProxy globally via npm:

npm install -g @akshatv21/chaosproxy

⚡ Quick Start

The fastest way to start is by using CLI flags. Proxy your traffic to a backend running on port 8080, listen on port 3000, and add a static 500ms delay to every request:

chaos start -t http://localhost:8080 -p 3000 -d 500

What happens next? ChaosProxy will spin up a reverse proxy. Any request sent to http://localhost:3000 will be forwarded to your backend after a 500ms pause. You'll see a beautiful, color-coded log in your terminal for every intercepted request.

🛠️ Advanced Configuration

While flags are great for quick tests, the real power of ChaosProxy lies in the chaos.json configuration file. This allows you to define global rules and specific overrides for different API endpoints.

Example chaos.json

{
  "server": {
    "port": 3000,
    "target": "http://localhost:8080"
  },
  "global": {
    "delay": "100-500",
    "failure": {
      "rate": 0.05,
      "codes": [500]
    }
  },
  "routes": [
    {
      "path": "/api/health",
      "delay": 0,
      "failure": { "rate": 0 }
    },
    {
      "path": "/api/checkout",
      "method": "POST",
      "delay": 2000,
      "failure": {
        "rate": 0.5,
        "codes": [500, 503]
      }
    },
    {
      "path": "/api/users/:id",
      "delay": "200-1000"
    }
  ]
}

Configuration Schema

| Property | Path | Type | Description | | :------- | :-------------------------------- | :------------------- | :------------------------------------------------------------- | | port | server.port | number | The local port ChaosProxy listens on. (Default: 3000) | | target | server.target | string | The destination backend URL. (Required) | | delay | global.delay / routes[].delay | number | string | A static value (e.g., 500) or a range (e.g., "150-500"). | | rate | global.failure.rate | number | Probability of failure (0.0 to 1.0). 0.1 = 10% chance. | | codes | global.failure.codes | number[] | List of HTTP status codes to randomly return on failure. | | path | routes[].path | string | Endpoint pattern. Supports dynamic segments (e.g., :id). | | method | routes[].method | string | HTTP method (GET, POST, etc). If omitted, matches all methods. |

[!TIP] Precedence Rule: Route-specific configurations always override global configurations. If a route is matched but doesn't define a specific property (like failure), it will fall back to the global setting.

📖 CLI Reference

| Flag | Alias | Description | Example | | :--------- | :---- | :---------------------------------- | :------------------------- | | --target | -t | The backend URL to proxy to. | -t http://localhost:8080 | | --port | -p | The local port to listen on. | -p 3000 | | --delay | -d | Inline delay (static or range). | -d 100-500 | | --config | -c | Path to a chaos.json config file. | -c ./chaos.json |

🛠️ Local Development

Want to contribute to the chaos? We'd love the help!

1. Clone and Install

   git clone https://github.com/anomalyco/chaos-proxy.git
   cd chaos-proxy
   npm install

2. Build and Link To test your changes locally as a global command:

   npm run build
   npm link

3. Run directly

   npx ts-node src/main.ts start -t http://localhost:8080