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:
|
0 1 2 3 |
sudo apt update sudo apt install docker.io docker-compose -y |
Verify the installation:
|
0 1 2 3 |
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:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
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:
|
0 1 2 3 4 5 6 7 8 |
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:
|
0 1 2 |
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
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
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", 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:
|
0 1 2 3 4 5 6 7 8 9 10 11 |
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:
|
0 1 2 |
docker-compose up |
Step 6, Understanding the K6 Test Summary
After running the test, you will see a summary like this:
|
0 1 2 3 4 5 6 7 |
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:
|
0 1 2 |
let res = http.get(`${BASE_URL}/api/data`, { headers }); |
PUT Request:
|
0 1 2 |
let res = http.put(`${BASE_URL}/api/data/123`, JSON.stringify({ message: "Updated message" }), { headers }); |
DELETE Request:
|
0 1 2 |
let res = http.del(`${BASE_URL}/api/data/123`, null, { headers }); |
To save results in JSON format, modify docker-compose.yml:
|
0 1 2 |
command: ["run", "/script-payload.js", "--summary-export=summary.json"] |
After execution, copy the results from the container:
|
0 1 2 |
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.