Configuration File

k6 JSON configuration file format

Configuration File

k6 supports configuration via a JSON file, allowing you to define test options without cluttering your test scripts.

Overview

By default, k6 looks for a configuration file named k6.json in the current directory. You can specify a different file using the --config flag or K6_CONFIG environment variable.

# Use default k6.json
k6 run script.js

# Use custom config file
k6 run --config /path/to/config.json script.js

# Via environment variable
K6_CONFIG=/path/to/config.json k6 run script.js

Configuration Precedence

Configuration is loaded in this order (later overrides earlier):

1. Default values - Built-in k6 defaults
2. Configuration file - k6.json or specified via --config
3. Script options - export const options = {} in your script
4. Environment variables - K6_* environment variables
5. CLI flags - Command-line arguments (highest priority)

File Format

The configuration file is JSON with the following structure:

{
  "vus": 10,
  "duration": "30s",
  "iterations": 1000,
  "stages": [
    { "duration": "10s", "target": 50 },
    { "duration": "30s", "target": 50 },
    { "duration": "10s", "target": 0 }
  ],
  "thresholds": {
    "http_req_duration": ["p(95)<500"],
    "http_req_failed": ["rate<0.01"]
  },
  "out": ["json=results.json"],
  "linger": false,
  "noUsageReport": true
}

Configuration Options

Execution Options

vus · int · default: "1"

Number of virtual users.

{"vus": 10}

duration · string

Test duration (e.g., 30s, 5m, 1h).

{"duration": "5m"}

iterations · int

Total iteration limit across all VUs.

{"iterations": 1000}

stages · array

Ramping configuration stages.

{
  "stages": [
    {"duration": "10s", "target": 100},
    {"duration": "30s", "target": 100},
    {"duration": "10s", "target": 0}
  ]
}

scenarios · object

Advanced scenario configuration.

{
  "scenarios": {
    "constant_load": {
      "executor": "constant-vus",
      "vus": 50,
      "duration": "5m"
    },
    "ramping_load": {
      "executor": "ramping-vus",
      "startVUs": 0,
      "stages": [
        {"duration": "2m", "target": 100}
      ]
    }
  }
}

HTTP Options

batch · int · default: "20"

Maximum parallel batch requests.

{"batch": 50}

batchPerHost · int · default: "6"

Maximum parallel batch requests per host.

{"batchPerHost": 10}

maxRedirects · int · default: "10"

Maximum HTTP redirects to follow.

{"maxRedirects": 5}

userAgent · string

User-Agent string for requests.

{"userAgent": "MyLoadTest/1.0"}

insecureSkipTLSVerify · boolean

Skip TLS certificate verification.

{"insecureSkipTLSVerify": true}

noConnectionReuse · boolean

Disable HTTP keep-alive.

{"noConnectionReuse": true}

noVUConnectionReuse · boolean

Don’t reuse connections between iterations.

{"noVUConnectionReuse": true}

discardResponseBodies · boolean

Don’t save HTTP response bodies.

{"discardResponseBodies": true}

Thresholds

thresholds · object

Pass/fail criteria for metrics.

{
  "thresholds": {
    "http_req_duration": [
      "p(95)<500",
      "p(99)<1000"
    ],
    "http_req_failed": ["rate<0.01"],
    "checks": ["rate>0.95"]
  }
}

Output Configuration

out · array

Metrics output destinations.

{
  "out": [
    "json=results.json",
    "influxdb=http://localhost:8086/k6",
    "cloud"
  ]
}

summaryTrendStats · array

Statistics to calculate for trends.

{
  "summaryTrendStats": ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"]
}

summaryTimeUnit · string

Time unit for trend stats: s, ms, us.

{"summaryTimeUnit": "ms"}

systemTags · array

System tags to include in metrics.

{
  "systemTags": ["proto", "status", "method", "url"]
}

Test Behavior

paused · boolean

Start test in paused state.

{"paused": true}

noSetup · boolean

Skip setup() function.

{"noSetup": true}

noTeardown · boolean

Skip teardown() function.

{"noTeardown": true}

linger · boolean

Keep API server alive after test.

{"linger": true}

noUsageReport · boolean

Disable usage statistics.

{"noUsageReport": true}

throw · boolean

Throw warnings as errors.

{"throw": true}

Network Configuration

blacklistIPs · array

IP ranges to blacklist.

{
  "blacklistIPs": ["10.0.0.0/8", "192.168.0.0/16"]
}

blockHostnames · array

Hostname patterns to block.

{
  "blockHostnames": ["*.internal.example.com", "localhost"]
}

dns · object

DNS resolver configuration.

{
  "dns": {
    "ttl": "5m",
    "select": "random",
    "policy": "preferIPv4"
  }
}

Cloud Configuration

cloud · object

Grafana Cloud k6 options.

{
  "cloud": {
    "projectID": 12345,
    "name": "My Load Test",
    "distribution": {
      "amazon:us:ashburn": {
        "loadZone": "amazon:us:ashburn",
        "percent": 50
      },
      "amazon:eu:dublin": {
        "loadZone": "amazon:eu:dublin",
        "percent": 50
      }
    }
  }
}

Complete Example

Here’s a comprehensive configuration file example:

{
  "scenarios": {
    "load_test": {
      "executor": "ramping-vus",
      "startVUs": 0,
      "stages": [
        { "duration": "2m", "target": 50 },
        { "duration": "5m", "target": 50 },
        { "duration": "2m", "target": 100 },
        { "duration": "5m", "target": 100 },
        { "duration": "2m", "target": 0 }
      ]
    }
  },
  "thresholds": {
    "http_req_duration": ["p(95)<500", "p(99)<1000"],
    "http_req_failed": ["rate<0.01"],
    "checks": ["rate>0.95"]
  },
  "out": [
    "json=results.json",
    "influxdb=http://localhost:8086/k6"
  ],
  "summaryTrendStats": ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"],
  "systemTags": ["proto", "status", "method", "url", "name", "group"],
  "insecureSkipTLSVerify": false,
  "noConnectionReuse": false,
  "userAgent": "MyLoadTest/1.0",
  "batch": 20,
  "batchPerHost": 6,
  "maxRedirects": 10,
  "noUsageReport": true,
  "discardResponseBodies": false
}

Best Practices

Separate Configs for Environments

Create environment-specific configs:

# Development
k6 run --config k6.dev.json script.js

# Staging
k6 run --config k6.staging.json script.js

# Production
k6 run --config k6.prod.json script.js

Use JSON Schema

Validate your config with a JSON schema editor for better error detection.

Version Control

Commit config files to version control:

git add k6*.json
git commit -m "Add k6 configurations"

Document Custom Settings

Add comments in accompanying README:

## k6 Configuration

- `k6.smoke.json` - Quick smoke test (1 VU, 1 min)
- `k6.load.json` - Standard load test (100 VUs, 10 min)
- `k6.stress.json` - Stress test (500 VUs, 30 min)

Avoid Secrets

Never commit secrets to config files. Use environment variables instead.

// Bad - token in config
{
  "cloud": {
    "token": "secret-token"
  }
}

// Good - use environment variable
{
  "cloud": {
    "projectID": 12345
  }
}

Schema Validation

While k6 doesn’t provide an official JSON schema, the configuration structure mirrors the lib.Options Go struct. Invalid options will cause k6 to exit with an error.

Troubleshooting

Config Not Loading

If your config isn’t being applied:

1. Verify the file exists: ls -la k6.json
2. Check JSON syntax: cat k6.json | jq .
3. Use explicit path: k6 run --config ./k6.json script.js
4. Enable verbose logging: k6 run --verbose --config k6.json script.js

Option Priority

Remember CLI flags override config:

# Config says 10 VUs, CLI says 50 - result is 50 VUs
k6 run --vus 50 --config k6.json script.js

Invalid Options

k6 validates options on startup. Check error messages:

ERROR: invalid option: thresholds must be a map of strings to arrays

See Also

• CLI Options Reference
• Environment Variables
• k6 run