Introduction

K6 is a powerful self-hosted load testing tool that can be run in Docker and configured to simulate API requests, including authentication, POST requests, and JSON payloads.

This guide provides a step-by-step tutorial on setting up K6 using Docker Compose and gradually moving from a simple request to a more complex Postman-like simulation.

Step 1, Install Docker and Docker Compose

Before running K6 in Docker, ensure that Docker and Docker Compose are installed on your system. If not, install them using:

sudo apt update
sudo apt install docker.io docker-compose -y

Verify the installation:

docker --version
docker-compose --version

Step 2, Create a Simple K6 Test Script

To start with a basic example, create a new file named script.js with the following content:

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

export let options = {
  vus: 5,  // Number of virtual users
  duration: '30s',  // Test duration
};

export default function () {
  let res = http.get('https://test-api.example.com');
  
  check(res, {
    'is status 200': (r) => r.status === 200,
  });
  
  sleep(1); // Simulate wait time
}

This script sends a simple GET request to https://test-api.example.com and validates the response status.

Step 3, Create the Docker Compose File

Create a docker-compose.yml file to configure the K6 test execution:

version: '3.8'
services:
  k6:
    image: grafana/k6
    volumes:
      - ./script.js:/script.js
    command: ["run", "/script.js"]

Step 4, Run the Simple K6 Load Test

To start the K6 test, run:

docker-compose up

This will execute the basic GET request test inside a Docker container.

Step 5, Expanding to a More Complex API Test (Simulating Postman)

Next, create a new test script called script-payload.js that simulates Postman requests with Bearer Token authentication, POST requests, and JSON payloads.

Example: script-payload.js

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

// Environment variables
const BASE_URL = __ENV.BASE_URL || 'https://test-api.example.com';
const BEARER_TOKEN = __ENV.BEARER_TOKEN || 'your-default-token';

export let options = {
  vus: 5,  // Number of virtual users
  duration: '30s',  // Test duration
};

// Define POST request payload
const payload = JSON.stringify({
  name: "John Doe",
  email: "[email protected]",
  message: "Hello from K6!"
});

// Define headers
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${BEARER_TOKEN}`,
};

export default function () {
  let res = http.post(`${BASE_URL}/api/data`, payload, { headers });

  // Validate response
  check(res, {
    'is status 200': (r) => r.status === 200,
    'response contains success': (r) => r.body.includes("success"),
  });

  sleep(1); // Simulate wait time
}

Modify docker-compose.yml to use script-payload.js:

version: '3.8'
services:
  k6:
    image: grafana/k6
    volumes:
      - ./script-payload.js:/script-payload.js
    environment:
      BASE_URL: "https://test-api.example.com"
      BEARER_TOKEN: "your-secure-token-here"
    command: ["run", "/script-payload.js"]

Run the more advanced test with:

docker-compose up

Step 6, Understanding the K6 Test Summary

After running the test, you will see a summary like this:

     data_received........: 15 MB  500 kB/s
     data_sent............: 2 MB   66.7 kB/s
     http_req_duration....: avg=250ms min=100ms med=200ms max=800ms p(90)=600ms p(95)=700ms
     http_req_failed......: 0.00%  ✓ 0  ✗ 1000
     iterations...........: 1000  33.3/s
     checks...............: 1000  100.00% ✓ 1000  ✗ 0

Step 7: Running Different HTTP Methods (GET, PUT, DELETE)

Modify script-payload.js for different request types:

GET Request:

let res = http.get(`${BASE_URL}/api/data`, { headers });

PUT Request:

let res = http.put(`${BASE_URL}/api/data/123`, JSON.stringify({ message: "Updated message" }), { headers });

DELETE Request:

let res = http.del(`${BASE_URL}/api/data/123`, null, { headers });

To save results in JSON format, modify docker-compose.yml:

command: ["run", "/script-payload.js", "--summary-export=summary.json"]

After execution, copy the results from the container:

docker cp $(docker ps -q -f name=k6)://summary.json ./summary.json

Conclusion

With this setup, K6 can fully simulate Postman requests within Docker Compose, starting from a simple GET request and progressing to authenticated API testing with payloads.

This structured approach ensures a smooth learning curve for automated API performance testing.