Environment variables

Using environment variables in k6 test scripts and configuration

Environment variables

k6 can access environment variables at runtime. You can use environment variables to:

• Configure test behavior without modifying the script
• Pass sensitive data like API keys
• Parameterize tests for different environments
• Override k6 options

Accessing environment variables

Access environment variables in your script using the __ENV object:

import http from 'k6/http';

const BASE_URL = __ENV.BASE_URL || 'https://test-api.k6.io';
const API_KEY = __ENV.API_KEY;

export default function () {
  const headers = {
    'Authorization': `Bearer ${API_KEY}`,
  };
  
  http.get(`${BASE_URL}/public/crocodiles/`, { headers });
}

Setting environment variables

You can set environment variables in multiple ways:

Command line

Pass variables when running k6:

BASE_URL=https://api.example.com API_KEY=secret k6 run script.js

.env file

Create a .env file:

# .env
BASE_URL=https://api.example.com
API_KEY=your-api-key-here

Then load it before running k6:

export $(cat .env | xargs) && k6 run script.js

System environment

Set system-wide environment variables:

export BASE_URL=https://api.example.com
export API_KEY=secret
k6 run script.js

k6 options via environment variables

You can set k6 options using environment variables with the K6_ prefix:

K6_VUS=10 K6_DURATION=30s k6 run script.js

Common k6 environment variables:

K6_VUS · integer

Number of virtual users

K6_DURATION · string

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

K6_ITERATIONS · integer

Total number of iterations

K6_OUT · string

Output destination (e.g., json=results.json, influxdb=http://localhost:8086)

K6_INSECURE_SKIP_TLS_VERIFY · boolean

Skip TLS certificate verification

Common patterns

Environment-specific configuration

import http from 'k6/http';

const ENV = __ENV.ENV || 'dev';

const config = {
  dev: {
    baseUrl: 'https://dev.example.com',
    vus: 5,
  },
  staging: {
    baseUrl: 'https://staging.example.com',
    vus: 20,
  },
  prod: {
    baseUrl: 'https://api.example.com',
    vus: 100,
  },
};

export const options = {
  vus: config[ENV].vus,
  duration: '30s',
};

export default function () {
  http.get(`${config[ENV].baseUrl}/api/status`);
}

Run with:

ENV=staging k6 run script.js

Sensitive data

Never hardcode sensitive data like API keys, passwords, or tokens in your test scripts.

import http from 'k6/http';
import { check } from 'k6';

const API_KEY = __ENV.API_KEY;
const API_SECRET = __ENV.API_SECRET;

if (!API_KEY || !API_SECRET) {
  throw new Error('API_KEY and API_SECRET must be set');
}

export default function () {
  const res = http.post('https://api.example.com/auth', {
    key: API_KEY,
    secret: API_SECRET,
  });
  
  check(res, {
    'authenticated': (r) => r.status === 200,
  });
}

Feature flags

import http from 'k6/http';

const ENABLE_BROWSER_TESTS = __ENV.ENABLE_BROWSER_TESTS === 'true';
const ENABLE_WEBSOCKETS = __ENV.ENABLE_WEBSOCKETS === 'true';

export default function () {
  http.get('https://test.k6.io');
  
  if (ENABLE_WEBSOCKETS) {
    // WebSocket test code
  }
  
  // Additional tests based on flags
}

Best practices

Provide default values

Always provide fallback values for non-critical environment variables:

const BASE_URL = __ENV.BASE_URL || 'https://test-api.k6.io';
const TIMEOUT = parseInt(__ENV.TIMEOUT) || 30;

Validate required variables

Fail early if required variables are missing:

const API_KEY = __ENV.API_KEY;
if (!API_KEY) {
  throw new Error('API_KEY environment variable is required');
}

Type conversion

Environment variables are always strings. Convert them as needed:

const VUS = parseInt(__ENV.VUS) || 10;
const ENABLE_FEATURE = __ENV.ENABLE_FEATURE === 'true';
const RATE = parseFloat(__ENV.RATE) || 0.5;

Document required variables

Add comments or README documentation listing required environment variables:

/**
 * Required environment variables:
 * - API_KEY: Your API authentication key
 * - BASE_URL: Target API base URL
 * 
 * Optional:
 * - TIMEOUT: Request timeout in seconds (default: 30)
 */

CI/CD integration

Environment variables are particularly useful in CI/CD pipelines:

GitHub Actions

name: Load Test
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: grafana/k6-action@v0.3.1
        with:
          filename: script.js
        env:
          BASE_URL: ${{ secrets.BASE_URL }}
          API_KEY: ${{ secrets.API_KEY }}
          K6_VUS: 50
          K6_DURATION: 5m

load_test:
  image: grafana/k6:latest
  script:
    - k6 run script.js
  variables:
    BASE_URL: $BASE_URL
    API_KEY: $API_KEY
    K6_VUS: 50
    K6_DURATION: 5m

Related resources

Options reference

Complete list of k6 options

Automated testing

Integrating k6 with CI/CD