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

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

# Custom Ramping Configuration Guide

This guide explains how to use the new custom ramping functionality in Load Runner, which allows you to define your own load testing patterns instead of using predefined stages.

## Overview

The custom ramping functionality gives you complete control over how your load test progresses over time. You can create complex patterns like:
- Gradual ramp-up with multiple phases
- Spike testing with sudden traffic increases
- Endurance testing with sustained loads
- Complex multi-phase testing scenarios

## Basic Usage

Use the `ramp` command to run tests with custom ramping:

```bash
load-runner ramp <config-file> <ramp-config-file>
```

### Example:
```bash
load-runner ramp test-config.json custom-ramp.json
```

## Ramping Configuration File Format

The ramping configuration file should be a JSON file with the following structure:

```json
{
  "name": "Your Ramping Pattern Name",
  "description": "Description of what this pattern tests",
  "stages": [
    {
      "duration": "30s",
      "target": 5,
      "description": "Ramp up to 5 VUs over 30 seconds"
    },
    {
      "duration": "1m",
      "target": 5,
      "description": "Maintain 5 VUs for 1 minute"
    },
    {
      "duration": "30s",
      "target": 20,
      "description": "Ramp up to 20 VUs over 30 seconds"
    },
    {
      "duration": "2m",
      "target": 20,
      "description": "Maintain 20 VUs for 2 minutes"
    },
    {
      "duration": "1m",
      "target": 0,
      "description": "Ramp down to 0 VUs over 1 minute"
    }
  ]
}
```

## Stage Properties

Each stage in the `stages` array must have:

- **`duration`**: Time duration (e.g., "30s", "1m", "2h")
- **`target`**: Target number of virtual users (VUs)

Optional properties:
- **`description`**: Human-readable description of the stage

## Duration Format

Durations use k6's time format:
- **`s`**: seconds (e.g., "30s" = 30 seconds)
- **`m`**: minutes (e.g., "2m" = 2 minutes)
- **`h`**: hours (e.g., "1h" = 1 hour)

## Common Ramping Patterns

### 1. Simple Ramp Up/Down
```json
{
  "stages": [
    { "duration": "1m", "target": 10 },
    { "duration": "5m", "target": 10 },
    { "duration": "1m", "target": 0 }
  ]
}
```

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

### 3. Endurance Testing
```json
{
  "stages": [
    { "duration": "2m", "target": 20 },
    { "duration": "1h", "target": 20 },
    { "duration": "2m", "target": 0 }
  ]
}
```

### 4. Multi-Phase Testing
```json
{
  "stages": [
    { "duration": "1m", "target": 5 },
    { "duration": "5m", "target": 5 },
    { "duration": "1m", "target": 25 },
    { "duration": "5m", "target": 25 },
    { "duration": "1m", "target": 50 },
    { "duration": "10m", "target": 50 },
    { "duration": "2m", "target": 0 }
  ]
}
```

## Creating Sample Configurations

Use the `create-ramp` command to generate a sample ramping configuration:

```bash
load-runner create-ramp
```

This creates `custom-ramp-config.json` with a sample pattern that you can modify.

## Examples Included

The `examples/` folder contains several sample ramping configurations:

- **`simple-ramping.json`**: Basic ramp up/down pattern
- **`custom-ramping.json`**: Standard multi-phase pattern
- **`advanced-ramping.json`**: Complex pattern with spike testing

## Best Practices

1. **Start Small**: Begin with simple patterns and gradually increase complexity
2. **Plan Your Stages**: Think about what you want to test at each phase
3. **Monitor Resources**: Ensure your system can handle the target VU counts
4. **Use Descriptions**: Add descriptions to make your configurations self-documenting
5. **Test Incrementally**: Test each stage individually before combining them

## Validation

The system automatically validates your ramping configuration:
- Ensures all required fields are present
- Validates JSON syntax
- Checks that stages array is properly formatted

## Integration with Existing Features

Custom ramping works with all existing Load Runner features:
- Variable substitution in payloads
- CSV logging
- Request/response logging
- Multiple output formats
- Thresholds and metrics

## Troubleshooting

### Common Issues:

1. **"Ramping configuration must contain a 'stages' array"**
   - Ensure your JSON has a `stages` key with an array value

2. **"Stage X must have 'duration' and 'target' fields"**
   - Check that each stage has both `duration` and `target` properties

3. **Invalid duration format**
   - Use k6's time format: "30s", "1m", "2h"

4. **File not found**
   - Check the file path and ensure the file exists

## Advanced Usage

### Combining with Scenarios

You can use custom ramping with the scenarios command for parallel testing:

```bash
# Create a scenarios folder with your config files
# Then run with custom ramping (you'll need to modify the scenarios command to support custom ramping)
```

### Dynamic Ramping

For more advanced use cases, you can:
- Generate ramping configurations programmatically
- Use different ramping patterns for different test scenarios
- Create ramping configurations based on system metrics

## Support

For issues or questions about custom ramping:
1. Check the validation messages for syntax errors
2. Verify your JSON format is correct
3. Test with simple patterns first
4. Refer to the k6 documentation for advanced stage configurations

## Examples in Action

Here's how to run a test with custom ramping:

```bash
# 1. Create a test configuration file (test-config.json)
# 2. Create a ramping configuration file (custom-ramp.json)
# 3. Run the test:
load-runner ramp test-config.json custom-ramp.json

# 4. Monitor the output to see your custom ramping in action
```

The system will display your custom ramping pattern before starting the test, so you can verify it's correct.