@increff/load-runner-k6/README.md

A powerful CLI wrapper around k6 for load testing with JSON configuration, variable substitution, custom ramping patterns, and comprehensive logging

# Load Runner for k6 🚀

A powerful CLI wrapper around k6 for load testing with JSON configuration, variable substitution, custom ramping patterns, and comprehensive logging.

## ✨ Features

- **🎯 JSON-Based Configuration**: Define your API tests in simple JSON files
- **📈 Custom Ramping Patterns**: Create complex load testing scenarios with custom VU ramping
- **🔄 Variable Substitution**: Dynamic values with built-in and custom variables
- **📊 Comprehensive Logging**: Request/response logging, CSV output, and detailed metrics
- **⚡ Parallel Execution**: Run multiple test scenarios simultaneously
- **🎭 Multiple Test Stages**: Predefined stages (smoke, load, stress, spike) or custom ones
- **🔧 Easy CLI**: Simple commands with interactive options

## 🚀 Quick Start

### Installation

```bash
npm install -g load-runner-k6
```

### Prerequisites

Make sure you have [k6](https://k6.io/docs/getting-started/installation/) installed on your system.

### Basic Usage

```bash
# Run with JSON configuration
load-runner config test-config.json

# Run with custom ramping pattern
load-runner ramp test-config.json custom-ramp.json

# Run multiple scenarios in parallel
load-runner scenarios ./test-scenarios

# Get help
load-runner --help
```

## 📋 Commands

| Command | Description |
|---------|-------------|
| `config <file>` | Run k6 using JSON configuration file |
| `ramp <config> <ramp-config>` | Run with custom ramping pattern |
| `scenarios <folder>` | Run multiple JSON files in parallel |
| `stages` | List available test stages |
| `create-config` | Create sample configuration file |
| `create-ramp` | Create sample custom ramping configuration |
| `interactive` | Interactive configuration mode |

## 🎨 Custom Ramping Patterns

Create sophisticated load testing patterns with custom ramping configurations:

```json
{
  "name": "Spike Testing Pattern",
  "stages": [
    { "duration": "1m", "target": 10 },
    { "duration": "30s", "target": 100 },
    { "duration": "1m", "target": 100 },
    { "duration": "30s", "target": 10 },
    { "duration": "2m", "target": 0 }
  ]
}
```

### Common Patterns

- **Simple Ramp**: Gradual increase/decrease in VUs
- **Spike Testing**: Sudden traffic spikes to test system resilience
- **Endurance Testing**: Sustained load for stability testing
- **Multi-Phase Testing**: Complex scenarios with multiple phases

## 📝 Configuration Examples

### Basic API Test

```json
{
  "url": "https://api.example.com/users",
  "method": "GET",
  "request_headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer ${token}"
  },
  "variables": {
    "token": "your-jwt-token-here"
  },
  "log_failed_responses": true
}
```

### POST Request with Payload

```json
{
  "url": "https://api.example.com/orders",
  "method": "POST",
  "request_headers": {
    "Content-Type": "application/json"
  },
  "payload": {
    "order_id": "${$randomInt}",
    "timestamp": "${$timestamp}",
    "items": ["item1", "item2"]
  },
  "variables": {
    "customer_id": "12345"
  }
}
```

## 🔧 Built-in Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `${$timestamp}` | Unix timestamp | `1703123456` |
| `${$randomString}` | Random string | `abc123def` |
| `${$randomInt}` | Random integer | `1234567` |
| `${$localDateTime}` | Local datetime | `2025-08-27 10:30:45.123000` |
| `${$isoTimestamp}` | ISO timestamp | `2025-08-27T10:30:45.123` |

## 📊 Test Stages

### Predefined Stages

- **Smoke**: Quick validation (1 VU, 1m)
- **Load**: Normal expected load (10 VUs, 5m)
- **Stress**: System limits testing (50 VUs, 10m)
- **Spike**: Sudden traffic spike (100 VUs, 2m)

### Custom Stages

Define your own stages in `k6-config.json`:

```json
{
  "stages": {
    "custom": [
      { "duration": "2m", "target": 10 },
      { "duration": "5m", "target": 10 },
      { "duration": "2m", "target": 0 }
    ]
  }
}
```

## 🚀 Advanced Features

### Parallel Scenario Execution

Run multiple test scenarios simultaneously:

```bash
load-runner scenarios ./test-scenarios --max-parallel 5
```

### CSV Logging

Enable CSV output for detailed analysis:

```json
{
  "log_orders_to_csv": true,
  "log_requests": true,
  "log_failed_responses": true
}
```

### Custom Thresholds

Define performance thresholds:

```json
{
  "thresholds": {
    "http_req_duration": ["p(95)<500"],
    "http_req_failed": ["rate<0.01"]
  }
}
```

## 📚 Documentation

- **[Custom Ramping Guide](CUSTOM_RAMPING_GUIDE.md)** - Complete guide to custom ramping patterns
- **[Examples](./examples/)** - Sample configurations and ramping patterns
- **[Scenarios](./scenarios/)** - Multi-scenario testing examples

## 🛠️ Development

### Prerequisites

- Node.js >= 16.0.0
- k6 installed

### Setup

```bash
git clone https://github.com/increff/load-runner.git
cd load-runner
npm install
```

### Local Development

```bash
# Run locally
node bin/load-runner.js --help

# Create sample files
node bin/load-runner.js create-config
node bin/load-runner.js create-ramp
```

## 🤝 Contributing

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on top of [k6](https://k6.io/) - the modern load testing tool
- Inspired by the need for easier load testing configuration and execution

## 📞 Support

- 📖 [Documentation](https://github.com/increff/load-runner#readme)
- 🐛 [Issues](https://github.com/increff/load-runner/issues)
- 💬 [Discussions](https://github.com/increff/load-runner/discussions)

---

**Made with ❤️ by Increff**