@increff/load-runner

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

npm install -g load-runner-k6

Prerequisites

Make sure you have k6 installed on your system.

Basic Usage

# 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:

{
  "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

{
  "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

{
  "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:

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

🚀 Advanced Features

Parallel Scenario Execution

Run multiple test scenarios simultaneously:

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

CSV Logging

Enable CSV output for detailed analysis:

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

Custom Thresholds

Define performance thresholds:

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

📚 Documentation

• Custom Ramping Guide - Complete guide to custom ramping patterns
• Examples - Sample configurations and ramping patterns
• Scenarios - Multi-scenario testing examples

🛠️ Development

Prerequisites

• Node.js >= 16.0.0
• k6 installed

Setup

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

Local Development

# 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 file for details.

🙏 Acknowledgments

• Built on top of k6 - the modern load testing tool
• Inspired by the need for easier load testing configuration and execution

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Made with ❤️ by Increff