K6 Load Testing Guide

1. Overview

This guide explains how to run a JavaScript-based k6 load test locally and in Jenkins for your service. It includes the required Jenkins configuration, naming conventions, and common troubleshooting tips.

2. Prerequisites

  • k6 installed locally (optional for local runs).

  • Your test script must be named exactly k6_load_test.js (required by the pipeline).

3. Jenkins Setup

3.1. Base Build Image (initial step)

In your Jenkinsfile, ensure the build image is set before running the load test stage:

buildServiceProject(
mavenImage: ‘ckm/map-maven-base-image:2.0.5-JDK21-d274ba84653bb8d6a249ab7f7dd22af4c55f700e’
)

Update jenkins.yaml by adding these two lines:

staging: # staging/sqa build environment overrides
  runK6: true

This enables the jenkins RUN_K6 parameter for SQA only.

3.2. File Naming Requirement

The pipeline expects the load test file to be present at the workspace root and named k6_load_test.js.

If the file is missing, the job will fail with an error similar to:

ERROR: Required file ‘k6_load_test.js’ not found. Cannot run load test.

3.3. Running the Load Test in Jenkins

To run a load test via Jenkins:

  1. Commit k6_load_test.js to your repo.

  2. In Jenkins, start your pipeline and enable/checkbox the parameter RUN_K6.

  3. The pipeline will:

    1. Validate that k6 is available (k6 --version).

    2. Verify k6_load_test.js exists.

    3. Execute k6 run k6_load_test.js.

A basic shell stage might look like:

4. Local Execution (Optional)

You can run the same script locally to iterate faster:

Verify k6 is installed

k6 version

Run the test

k6 run k6_load_test.js

5. Example k6_load_test.js

Below is a simple example you can adapt. Start simple, then parameterize (RPS, VUs, duration) as needed.

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

export const options = {
    vus: 5,
    duration: '30s',
    thresholds: {
        http_req_duration: ['p(95)<500'],    // 95% under 500ms
        http_req_failed: ['rate<0.01']      // <1% failures
    }
};
const ENDPOINT = '<INSERT_ENDPOINT>'
export default function () {
    const res = http.get(ENDPOINT);
    check(res, {
        'status is 200': (r) => r.status === 200
    });
    sleep(1);
}

6. Interpreting Results

k6 prints live and final metrics to stdout, including:

  • Checks – success/failure counts of assertions.

  • http_req_duration – response time distribution (avg, p90, p95, p99).

  • http_req_failed – error rate.

Add thresholds in options to enforce SLO-like limits. If a threshold fails, k6 exits non‑zero, causing Jenkins to fail the stage (desired for CI gates).

7. References

Useful links: