Package Exports

@increff/load-runner
@increff/load-runner/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@increff/load-runner) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Made with ❤️ by Increff