Complete Guide — Setup & Commands

What is k6?

Grafana k6 is an open-source load testing tool for API, microservices, and browser performance. Scripts are written in JavaScript (ES modules), executed by the k6 runtime with a Go-based engine that generates real HTTP traffic at scale.

Why use k6 in testflow-k6?

The testflow-k6 suite complements functional automation in testflow-cypress, testflow-playwright, and testflow-pytest. It validates Service Level Objectives (SLOs) for the TestFlow sandbox on port 5050 under smoke, load, stress, spike, and soak patterns.

• Same endpoints — /health, /api/auth/login, /api/users, static /web/*.html
• Aligned SLO budgets — per-endpoint p95 thresholds mirror functional test timeouts
• CI smoke gate — every push runs a lightweight profile against Docker TestFlow
• GitHub Pages report — 7-scenario HTML dashboard updated on every push to main
• Shared credentials — demo@automation.io / DEMO_PASSWORD env var

Prerequisites

Before cloning the repository, ensure your machine meets these requirements.

Project setup

git clone https://github.com/lflucasferreira/testflow-k6.git
cd testflow-k6
npm install
cp .env.example .env   # optional — BASE_URL, DEMO_PASSWORD, InfluxDB tokens

Environment setup by platform

Install Node.js 20+, Git, and Docker (for TestFlow on port 5050). Project steps (npm install, k6 runs) are identical on every OS.

# Homebrew — https://brew.sh
brew install node@20 git
brew link --overwrite node@20
brew install --cask docker

node --version   # v20+
git --version

winget install OpenJS.NodeJS.LTS
winget install Git.Git
winget install Docker.DockerDesktop

node --version

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git docker.io
sudo usermod -aG docker $USER

node --version

Start TestFlow — same on every platform

docker run --rm -p 5050:5050 qaschool/testflow:latest
# or
npm run docker:up

k6 installation

Native k6 is faster for local development and required for browser scenarios (test:browser:login). If k6 is missing, npm scripts fall back to the grafana/k6 Docker image via scripts/run-k6.sh.

brew install k6
k6 version

curl -fsSL https://dl.k6.io/key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/k6-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" \
  | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install -y k6
k6 version

winget install k6 --source winget
k6 version

Verify installation

Project structure

testflow-k6/
├── config/              # environments.js, profiles.js, thresholds.js
├── lib/                 # auth.js, http.js, endpoints.js, summary.js
├── scenarios/
│   ├── smoke/           # CI gate — api-health.js
│   ├── load/            # api-auth, api-users, mixed-traffic
│   ├── stress/          # api-breakpoint.js
│   ├── spike/           # api-spike.js
│   ├── soak/            # api-endurance.js
│   └── browser/         # login-page.js (k6 browser)
├── journeys/            # login-flow.js, authenticated-user.js
├── docs/                # GitHub Pages hub, slides, this guide
├── monitoring/          # Grafana + InfluxDB provisioning
│   ├── grafana/         # datasource + k6 dashboard JSON
│   └── influxdb/        # YAML template + dashboard JSON
├── scripts/             # run-k6.sh, generate-report.mjs, grafana-up.sh
├── results/             # summary JSON, HTML report, REPORT.md
├── docker/              # k6-influx.Dockerfile (xk6-output-influxdb)
├── docker-compose.yml
└── .github/workflows/
    └── k6.yml           # smoke gate, manual load, GitHub Pages

First scenario — smoke api-health.js

The smoke gate is the fastest way to validate that TestFlow responds under minimal load. Run it with npm run test:smoke.

1. Start TestFlow

   docker run --rm -p 5050:5050 qaschool/testflow:latest

2. Run the smoke scenario

   npm run test:smoke

3. Inspect the script — file: scenarios/smoke/api-health.js

import { sleep } from 'k6';
import { getProfile } from '../../config/profiles.js';
import { getThresholds } from '../../config/thresholds.js';
import { TAGS } from '../../config/environments.js';
import { login } from '../../lib/auth.js';
import { getHealth, getUsers } from '../../lib/http.js';
import { handleSummary } from '../../lib/summary.js';

export { handleSummary };

const profile = getProfile('smoke');

export const options = {
  scenarios: {
    smoke_api: {
      executor: 'ramping-vus',
      ...profile,
      tags: { test_type: TAGS.smoke, suite: 'api-health' },
    },
  },
  thresholds: getThresholds('smoke'),
};

export default function smokeApiHealth() {
  getHealth();
  sleep(0.5);
  getUsers();
  sleep(0.5);
  login();
  sleep(1);
}

Each iteration exercises three critical endpoints:

• GET /health — availability probe
• GET /api/users — read-heavy list with JSON validation
• POST /api/auth/login — authentication and token extraction

Walkthrough: docs/en/scenarios/smoke/api-health.md

Load profiles

Profiles in config/profiles.js define stages for the ramping-vus executor. Select a profile with K6_PROFILE or pass a name to getProfile().

// config/profiles.js — excerpt
export const profiles = {
  smoke: {
    stages: [
      { duration: '10s', target: 2 },
      { duration: '20s', target: 2 },
      { duration: '5s', target: 0 },
    ],
    gracefulRampDown: '5s',
  },
  load: {
    stages: [
      { duration: '1m', target: 10 },
      { duration: '3m', target: 25 },
      { duration: '2m', target: 25 },
      { duration: '1m', target: 0 },
    ],
    gracefulRampDown: '30s',
  },
  // stress, spike, soak, breakpoint, ci …
};

export function getProfile(name) {
  const key = name || __ENV.K6_PROFILE || 'smoke';
  if (__ENV.CI === 'true' && key === 'smoke') return profiles.ci;
  return profiles[key] || profiles.smoke;
}

Thresholds & checks

k6 uses two complementary mechanisms. A run fails if either breaches limits. See threshold-strategy.md for the full SLO matrix.

Per-endpoint tags

Tag every HTTP call with endpoint so filtered thresholds apply:

http.get(url, {
  tags: { endpoint: 'health', name: 'GET /health' },
});

// config/thresholds.js
export const smokeThresholds = {
  http_req_failed: ['rate<0.005'],
  http_req_duration: ['p(95)<1500', 'avg<800'],
  'http_req_duration{endpoint:health}': ['p(95)<500'],
  'http_req_duration{endpoint:users}': ['p(95)<1500'],
  'http_req_duration{endpoint:auth_login}': ['p(95)<2000'],
  checks: ['rate>0.99'],
};

Checks in lib/http.js

HTTP helpers

Centralized helpers in lib/http.js and lib/auth.js keep scenarios thin and ensure consistent checks across every test type.

getHealth()

export function getHealth(params = {}) {
  const res = http.get(`${BASE_URL}${endpoints.health}`, {
    tags: { endpoint: 'health', name: 'GET /health' },
    ...params,
  });
  check(res, {
    'health status 200': (r) => r.status === 200,
    'health responds quickly': (r) => r.timings.duration < 1000,
  });
  return res;
}

getUsers(token?)

export function getUsers(token = null, params = {}) {
  const headers = token ? authHeaders(token) : { 'Content-Type': 'application/json' };
  const res = http.get(`${BASE_URL}${endpoints.users.list}`, {
    headers,
    tags: { endpoint: 'users', name: 'GET /api/users' },
    ...params,
  });
  check(res, {
    'users status 200': (r) => r.status === 200,
    'users has array': (r) => Array.isArray(r.json('users')) && r.json('users').length > 0,
    'users responds within 2s': (r) => r.timings.duration < 2000,
  });
  return res;
}

login()

export function login(params = {}) {
  const res = http.post(`${BASE_URL}${endpoints.auth.login}`, payload, {
    headers: { 'Content-Type': 'application/json' },
    tags: { endpoint: 'auth_login', name: 'POST /api/auth/login' },
    ...params,
  });
  check(res, {
    'login status 200': (r) => r.status === 200,
    'login has token': (r) => typeof r.json('token') === 'string',
  });
  return res.json('token');
}

getStaticPage(path)

export function getStaticPage(path, params = {}) {
  const res = http.get(`${BASE_URL}${path}`, {
    tags: { endpoint: 'static', name: `GET ${path}` },
    ...params,
  });
  check(res, {
    'static page status 200': (r) => r.status === 200,
    'static page has html': (r) => (r.headers['Content-Type'] || '').includes('text/html'),
  });
  return res;
}

Additional utilities: weightedPick(), thinkTime(), getErrorSimulation().

Test types

Each test type maps to a folder, load profile, and threshold set.

Custom metrics

Import Trend, Rate, and Counter from k6/metrics to track scenario-specific behaviour beyond built-in HTTP metrics.

import { Trend, Rate, Counter } from 'k6/metrics';

const loginDuration = new Trend('login_duration', true);
const loginErrors = new Rate('login_errors');
const degradedResponses = new Counter('degraded_responses');

// Record values during the test
loginDuration.add(res.timings.duration);
loginErrors.add(!ok);
degradedResponses.add(1);

// Add thresholds in options
export const options = {
  thresholds: {
    ...getThresholds('load'),
    login_duration: ['p(95)<2000'],
    login_errors: ['rate<0.01'],
  },
};

group() for journeys

Use k6 group() to label steps in multi-step flows. Groups appear separately in the end-of-test summary and HTML report, making it easy to pinpoint slow steps.

import { sleep, group } from 'k6';
import { Trend } from 'k6/metrics';

const loginFlowDuration = new Trend('login_flow_duration', true);

export default function loginFlow() {
  const start = Date.now();

  group('01_load_login_page', () => {
    getStaticPage(endpoints.web.login);
    sleep(0.5);
  });

  group('02_api_login', () => {
    const res = http.post(`${BASE_URL}${endpoints.auth.login}`, payload, { /* … */ });
    check(res, { 'login succeeds': (r) => r.status === 200 });
    sleep(0.3);
  });

  group('03_post_login_navigation', () => {
    getStaticPage(endpoints.web.dashboard);
    sleep(0.5);
  });

  loginFlowDuration.add(Date.now() - start);
}

Journey scripts: journeys/login-flow.js (3 groups) and journeys/authenticated-user.js (4 groups: login → users → dashboard → team).

setup() phase

The setup() function runs once before VUs start. Use it for expensive one-time work — e.g. obtaining a shared auth token — and pass the result to the default function.

// lib/auth.js
export function setupAuth() {
  const token = login();
  return { token };
}

// scenarios/load/api-users.js
export function setup() {
  return setupAuth();
}

export default function usersLoad(data) {
  const res = getUsers(data.token);
  usersListDuration.add(res.timings.duration);
  sleep(0.5 + Math.random());
}

Reports

testflow-k6 produces multiple report formats for local debugging and CI publishing.

npm run test:report

Runs 7 scenarios with K6_PROFILE=smoke (~4 min total):

1. smoke · 2. load-auth · 3. load-users · 4. mixed-traffic
2. login-flow · 6. authenticated-user · 7. spike

Generates:

• results/REPORT.md — Markdown summary
• results/report/index.html — HTML dashboard with PASS/FAIL, charts, checks, thresholds
• results/summary-latest.json — machine-readable summary
• results/runs/<run-id>-*.json — raw k6 exports

npm run test:report
npm run report:open    # open results/report/index.html locally

Live report: lflucasferreira.github.io/testflow-k6/report/

handleSummary

// lib/summary.js — exported from every scenario
export function handleSummary(data) {
  return {
    stdout: 'k6 summary text…',
    'results/summary-latest.json': JSON.stringify(data, null, 2),
    [`results/summary-${scenario}-${profile}-${timestamp}.json`]: JSON.stringify(data, null, 2),
  };
}

k6 Web Dashboard (live + HTML export)

npm run test:smoke:ui          # K6_DASHBOARD=true — live at http://localhost:5665
npm run test:load:mixed:ui
K6_DASHBOARD=true K6_SCENARIO=spike npm run test:spike

GitHub Pages

On every push to main, the publish-pages job in .github/workflows/k6.yml builds the docs hub, runs the report suite, and deploys to GitHub Pages.

Grafana + InfluxDB

Stream live k6 metrics to InfluxDB and visualize in Grafana — locally or in the cloud.

Local stack

npm run grafana:up              # TestFlow + InfluxDB + Grafana (Docker)
npm run test:smoke:grafana      # smoke with live metrics
npm run test:load:mixed:grafana # load with dashboard
npm run grafana:down

Cloud (InfluxDB Cloud + Grafana Cloud)

cp .env.influx.cloud.example .env.influx.cloud   # add tokens
npm run test:smoke:influx:cloud
npm run test:load:mixed:influx:cloud

Full guide: grafana-cloud-setup.md · influxdb-cloud-dashboard.md · embed via docs/grafana/

CI — GitHub Actions

Workflow: .github/workflows/k6.yml

# k6.yml — smoke job (excerpt)
services:
  testflow:
    image: qaschool/testflow:latest
    ports: ['5050:5050']
env:
  CI: "true"
  BASE_URL: http://localhost:5050
  K6_PROFILE: smoke
  DEMO_PASSWORD: ${{ secrets.DEMO_PASSWORD }}
run: k6 run --summary-export=results/summary.json scenarios/smoke/api-health.js

Badge: k6 CI workflow

npm scripts reference

Training documentation

Block-by-block walkthroughs for every scenario script — ideal for students learning k6 and SLO-driven testing.

Scenario walkthroughs

Best practices

• Reuse lib helpers — never duplicate HTTP calls or checks in scenario files
• Tag every request — set endpoint for per-route SLO thresholds
• Pick the right profile — smoke for gates, load for sustained traffic, spike for bursts
• Separate checks from thresholds — checks assert correctness; thresholds gate SLOs
• Export handleSummary — every scenario should export handleSummary from lib/summary.js
• Use group() in journeys — step-level timing makes reports actionable
• setup() for expensive auth — when the test focus is read/write, not login throughput
• Custom metrics with thresholds — add Trend/Rate thresholds only when built-in metrics are insufficient
• Register new scenarios — update scripts/scenario-catalog.mjs and add EN/PT walkthroughs
• Align with functional suites — SLO budgets mirror Cypress/Playwright timeouts
• CI stays fast — smoke profile only in PR gate; run load/stress manually or via workflow_dispatch
• Read threshold-strategy.md before loosening limits
• Browser tests need native k6 — Docker fallback does not support --browser
• Think time between requests — use sleep() and thinkTime() for realistic pacing

Next steps