Chaos Injector

Inject chaos into your Express.js APIs to test resilience and fault tolerance.

Overview

Chaos Injector is a lightweight Node.js library designed to simulate real-world failure scenarios in your Express applications. By injecting delays, errors, timeouts, and empty responses, it helps you test the resilience and reliability of your APIs under unpredictable conditions.

Features

• 🧪 Inject HTTP errors dynamically
• 🐢 Simulate random response delays
• ⏳ Simulate timeouts
• 🛑 Inject empty or missing responses
• ⚙️ Highly configurable (or use ready-made chaos profiles)
• 🛠️ Minimal setup — simple middleware integration

Installation

npm install chaos-injector

Usage

const express = require('express');
const { withChaos } = require('chaos-injector');

const app = express();

// Apply chaos injection to a route
app.get('/', withChaos('flakyNetwork'), (req, res) => {
  res.send('Hello, Chaos!');
});

app.listen(3000, () => console.log('Server running on port 3000'));

API

withChaos(profileName?, userConfig?)

| Parameter | Type | Description | |---------------|--------|--------------------------------------------------| | profileName | string | (Optional) Name of a predefined chaos profile | | userConfig | object | (Optional) Custom configuration that overrides the profile |

Returns an Express middleware function that injects chaos according to the configuration.

Configuration Options

| Option | Type | Description | |-------------------|---------------------|--------------------------------------------------------------| | failureRate | number (0-1) | Probability of injecting a failure (default: 0.0) | | delayRange | [min, max] array | Delay response randomly between min and max (ms) | | errorTypes | string[] | Array of HTTP error status codes to simulate | | emptyType | string | Type of empty response: 'empty', 'empty_object', 'empty_array', or 'no_data' | | simulateTimeout | boolean | If true, simulates a timeout without sending a response |

Chaos Profiles

Predefined profiles for quick setup:

| Profile | Behavior | |----------------------|-----------------------------------------------------------| | flakyNetwork | Random delays (300-1500ms) + occasional 503, 504 errors | | overloadedServer | Heavy delays (1200-4000ms) + frequent server errors | | gremlinAttack | High error rate across various HTTP error codes | | intermittentEmpty| Frequent empty successful responses | | timeoutScenario | Very high chance of timeout without a response | | latencySpike | Extreme delays (2000-8000ms) without errors | | errorStorm | Frequent server-side errors | | emptyTrap | Intermittent empty object responses |

Example: Using a Predefined Profile

app.get('/chaos', withChaos('gremlinAttack'), (req, res) => {
  res.send('Chaos injected!');
});

Example: Using Custom Configuration

app.get('/test', withChaos({
  delayRange: [100, 300],
  failureRate: 0.2,
  errorTypes: ['500', '400']
}), (req, res) => {
  res.send('This might be slow or fail sometimes.');
});

Error Handling

• If a configured chaos event triggers, the middleware automatically sends a corresponding HTTP error or empty response.
• If invalid config options are provided, the middleware calls next() with an Error.

Limitations

• No dynamic adjustment of failure rate over time (planned for future releases).
• No input validation on user config (planned for future enhancement).

Contributing

Contributions are welcome! 🚀 Please feel free to:

• Submit bug reports
• Suggest new chaos profiles
• Improve documentation
• Add test coverage

To contribute, fork the repository, make your changes, and submit a pull request.

License

This project is licensed under the MIT License.

✨ Why Chaos Injector?

"Everything fails, all the time." — Werner Vogels, CTO, Amazon.

Test your services like they live in the real, messy, unpredictable internet. 🌎

Author

Created with ❤️ by Gopal Vallu.