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):
- Default values - Built-in k6 defaults
- Configuration file -
k6.json or specified via --config
- Script options -
export const options = {} in your script
- Environment variables -
K6_* environment variables
- CLI flags - Command-line arguments (highest priority)
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
Test duration (e.g., 30s, 5m, 1h). Total iteration limit across all VUs. Ramping configuration stages.{
"stages": [
{"duration": "10s", "target": 100},
{"duration": "30s", "target": 100},
{"duration": "10s", "target": 0}
]
}
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
Maximum parallel batch requests. Maximum parallel batch requests per host. Maximum HTTP redirects to follow. User-Agent string for requests.{"userAgent": "MyLoadTest/1.0"}
Skip TLS certificate verification.{"insecureSkipTLSVerify": true}
Disable HTTP keep-alive.{"noConnectionReuse": true}
Don’t reuse connections between iterations.{"noVUConnectionReuse": true}
Don’t save HTTP response bodies.{"discardResponseBodies": true}
Thresholds
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
Metrics output destinations.{
"out": [
"json=results.json",
"influxdb=http://localhost:8086/k6",
"cloud"
]
}
Statistics to calculate for trends.{
"summaryTrendStats": ["avg", "min", "med", "max", "p(90)", "p(95)", "p(99)"]
}
Time unit for trend stats: s, ms, us.{"summaryTimeUnit": "ms"}
System tags to include in metrics.{
"systemTags": ["proto", "status", "method", "url"]
}
Test Behavior
Start test in paused state. Skip teardown() function. Keep API server alive after test. Disable usage statistics. Throw warnings as errors. Network Configuration
IP ranges to blacklist.{
"blacklistIPs": ["10.0.0.0/8", "192.168.0.0/16"]
}
Hostname patterns to block.{
"blockHostnames": ["*.internal.example.com", "localhost"]
}
DNS resolver configuration.{
"dns": {
"ttl": "5m",
"select": "random",
"policy": "preferIPv4"
}
}
Cloud Configuration
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:
- Verify the file exists:
ls -la k6.json
- Check JSON syntax:
cat k6.json | jq .
- Use explicit path:
k6 run --config ./k6.json script.js
- 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