api-throttle-tester/README.md

A production-ready CLI tool for stress-testing API endpoints to understand rate limits, throttling behavior, and latency characteristics

# api-throttle-tester

A production-ready CLI tool for stress-testing API endpoints to understand rate limits, throttling behavior, and latency characteristics under load.

## Features

- 🚀 **Concurrent Load Testing**: Test API endpoints with configurable concurrency levels
- 📊 **Comprehensive Metrics**: Track success rates, throttling, errors, and latency distributions
- 🎯 **Rate Limit Detection**: Automatically identify and report HTTP 429 (or custom) throttling responses
- 📈 **Detailed Reporting**: Human-readable tables or JSON output for CI/CD integration
- ⚙️ **Configurable**: Support for config files, custom headers, request bodies, and more
- 🧪 **Well-Tested**: Comprehensive test suite with unit and integration tests

## Installation

### Global Installation (Recommended)

```bash
npm install -g api-throttle-tester
```

After installation, use it from anywhere:

```bash
api-throttle-tester https://api.example.com/endpoint
```

### Use Without Installation

```bash
npx api-throttle-tester <url> [options]
```

## Quick Start

### 1. Install the tool

```bash
npm install -g api-throttle-tester
```

### 2. Run your first test

```bash
# Test a public API (safe example)
api-throttle-tester https://jsonplaceholder.typicode.com/posts/1 -t 10 -c 2
```

**You'll see output like:**
```
============================================================
API Throttle Test Results
============================================================

Summary:
  Successful (2xx): 10
  Throttled: 0
  Errors: 0
  Network Errors: 0

Latency:
  Average: 245.30ms
  Min: 120.00ms
  Max: 450.00ms
...
```

### 3. Test your own API

```bash
api-throttle-tester https://api.yourcompany.com/endpoint \
  -H "Authorization: Bearer your-token" \
  -t 100 -c 10
```

### 4. Get JSON output for automation

```bash
api-throttle-tester https://api.example.com/endpoint \
  --json \
  --report-file results.json \
  -t 200 -c 20
```

## Common Use Cases

### Basic Example

Test an API endpoint with default settings (100 requests, 10 concurrent workers):

```bash
api-throttle-tester https://api.example.com/endpoint
```

### With Authentication

```bash
api-throttle-tester https://api.example.com/endpoint \
  -H "Authorization: Bearer your-token-here" \
  -H "X-API-Key: your-api-key"
```

### POST Request with Body

```bash
api-throttle-tester https://api.example.com/users \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token" \
  -b '{"name":"John Doe","email":"john@example.com"}'
```

### Custom Concurrency and Total Requests

```bash
api-throttle-tester https://api.example.com/endpoint \
  -t 1000 \
  -c 50 \
  -d 100
```

This sends 1000 total requests with 50 concurrent workers and a 100ms delay between requests per worker.

### JSON Output and Report File

```bash
api-throttle-tester https://api.example.com/endpoint \
  --json \
  --report-file report.json
```

### Custom Throttle Status Code

Some APIs use different status codes for throttling (e.g., 503):

```bash
api-throttle-tester https://api.example.com/endpoint \
  --status-as-throttle 503
```

## Command-Line Options

### Required

- `<url>` - API endpoint URL to test (can also be provided via `--config`)

### Optional

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--method` | `-X` | HTTP method (GET, POST, PUT, DELETE, etc.) | `GET` |
| `--total` | `-t` | Total number of requests to send | `100` |
| `--concurrency` | `-c` | Number of concurrent workers | `10` |
| `--delay` | `-d` | Delay between requests per worker (ms) | `0` |
| `--header` | `-H` | HTTP header (can be used multiple times) | - |
| `--body` | `-b` | Request body (JSON string for POST/PUT/PATCH) | - |
| `--timeout` | - | Per-request timeout (ms) | `5000` |
| `--json` | - | Output results as JSON | `false` |
| `--report-file` | - | Path to write JSON report file | - |
| `--status-as-throttle` | - | Status code to count as throttled | `429` |
| `--tag` | - | Optional label/tag for the test run | - |
| `--config` | - | Path to config file (JSON) | - |
| `--version` | - | Show version number | - |
| `--help` | `-h` | Show help message | - |

## Config File Support

You can use a JSON config file to store default settings:

**api-throttle.config.json:**

```json
{
  "url": "https://api.example.com/endpoint",
  "method": "GET",
  "total": 500,
  "concurrency": 25,
  "delay": 50,
  "timeout": 10000,
  "headers": {
    "Authorization": "Bearer your-token",
    "X-API-Key": "your-key"
  },
  "throttleStatus": 429,
  "tag": "production-test"
}
```

Then run:

```bash
api-throttle-tester --config api-throttle.config.json
```

CLI flags will override config file values.

## Output Format

### Human-Readable Table (Default)

```
============================================================
API Throttle Test Results
============================================================

Configuration:
  URL: https://api.example.com/endpoint
  Method: GET
  Total Requests: 100
  Concurrency: 10
  Delay: 0ms
  Timeout: 5000ms
  Throttle Status: 429

Summary:
  Successful (2xx): 82
  Throttled: 12
  Errors: 6
  Network Errors: 0
  Total: 100

Latency:
  Average: 135.42ms
  Min: 40.00ms
  Max: 800.00ms

Status Code Breakdown:
  200: 82
  429: 12
  500: 6

Latency Distribution:
  < 100ms:    15
  100-250ms:  40
  250-500ms:  25
  500-1000ms: 18
  > 1000ms:   2

============================================================
```

### JSON Output

When using `--json`, the output is a structured JSON object:

```json
{
  "url": "https://api.example.com/endpoint",
  "method": "GET",
  "tag": "optional-tag",
  "config": {
    "totalRequests": 100,
    "concurrency": 10,
    "delayMs": 0,
    "timeoutMs": 5000,
    "throttleStatus": 429
  },
  "summary": {
    "success": 82,
    "throttled": 12,
    "errors": 6,
    "networkErrors": 0,
    "avgResponseMs": 135.42,
    "minResponseMs": 40,
    "maxResponseMs": 800
  },
  "statusCounts": {
    "200": 82,
    "429": 12,
    "500": 6
  },
  "latencyBuckets": {
    "<100": 15,
    "100-250": 40,
    "250-500": 25,
    "500-1000": 18,
    ">1000": 2
  }
}
```

## Examples

### Example 1: Basic Load Test

```bash
api-throttle-tester https://jsonplaceholder.typicode.com/posts/1
```

### Example 2: Testing Rate Limits

```bash
api-throttle-tester https://api.example.com/endpoint \
  -t 200 \
  -c 20 \
  --tag "rate-limit-test"
```

### Example 3: POST Request with Authentication

```bash
api-throttle-tester https://api.example.com/users \
  -X POST \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -b '{"name":"Test User","email":"test@example.com"}'
```

### Example 4: CI/CD Integration

```bash
api-throttle-tester https://api.example.com/health \
  --json \
  --report-file test-results.json \
  -t 1000 \
  -c 50
```

Then parse the JSON in your CI pipeline to check thresholds.

### Example 5: Custom Throttle Detection

```bash
api-throttle-tester https://api.example.com/endpoint \
  --status-as-throttle 503 \
  -t 500
```

## Development

### Prerequisites

- Node.js 18+
- npm (or pnpm/yarn)

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/api-throttle-tester.git
cd api-throttle-tester

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linter
npm run lint
```

### Project Structure

```
api-throttle-tester/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── cli.ts            # Command parsing
│   ├── runner/
│   │   └── loadTester.ts # Core load testing engine
│   ├── types/
│   │   └── index.ts      # TypeScript types
│   └── utils/
│       ├── config.ts     # Config file handling
│       ├── logger.ts     # Logging utilities
│       ├── metrics.ts    # Metrics calculation
│       └── output.ts     # Output formatting
├── tests/
│   ├── runner/
│   └── utils/
├── package.json
├── tsconfig.json
└── README.md
```

## Testing

The project includes comprehensive tests:

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage
```

## Responsible Usage

⚠️ **Important**: This tool is designed for testing **your own APIs** or APIs you have explicit permission to test.

- **Do NOT** use this tool to DDoS or attack third-party services
- **Do NOT** test APIs without proper authorization
- Always respect rate limits and terms of service
- Start with low concurrency and gradually increase
- Use appropriate delays to avoid overwhelming servers
- Be mindful of the impact on production systems

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, feature requests, or questions, please open an issue on [GitHub](https://github.com/yourusername/api-throttle-tester/issues).