k6 scripts on MaxoPerf

k6 is a JavaScript-native load-testing engine with a clean ES-module API and excellent developer ergonomics. MaxoPerf runs k6 scripts directly — upload your .js file, mark it as the entrypoint, and MaxoPerf auto-detects k6, validates the script, and dispatches it to the runner fleet.

Before you start

• You need a k6 script (.js or .ts) that exports a default function.
• Read Upload test files — the Files tab workflow is the same for k6 as for other engines.
• Read By engine — decision guide if you are deciding between k6 and JMeter.

A minimal k6 script

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

export const options = {
  vus: 50,
  duration: '2m',
  thresholds: {
    http_req_duration: ['p(95)<500'],   // 95th percentile under 500ms
    http_req_failed: ['rate<0.01'],     // error rate under 1%
  },
};

export default function () {
  const res = http.get('https://api.example.com/products');

  check(res, {
    'status is 200': (r) => r.status === 200,
    'body contains products': (r) => r.json('items') !== undefined,
  });

  sleep(1);   // think time between iterations
}

MaxoPerf detects k6 from the import … from 'k6/http' statement and the exported default function. The script’s own options object (VUs, duration, thresholds) is merged with MaxoPerf’s run overlay at run time — MaxoPerf’s reporting configuration wins on any conflicting keys.

Upload and run a k6 script

1. Write or export your k6 script as index.js (or any .js / .ts filename).
2. Open the test in MaxoPerf console → Files tab.
3. Upload the script. MaxoPerf auto-detects k6 from the file content and marks it as Entrypoint with the k6 engine badge.
4. Upload any helper modules your script imports (e.g. lib/helpers.js) and any JSON/CSV fixture files — mark them as Test asset.
5. Save. MaxoPerf validates the script parses successfully and shows a green badge.
6. Click Run.

Using Taurus YAML to wrap a k6 script

You can wrap a k6 script in a Taurus YAML to control VUs, ramp-up, and hold-for from one place — useful when you want to run the same k6 scenario at different load levels without editing the script:

execution:
  - executor: k6
    concurrency: 200          # overrides options.vus in the script
    ramp-up: 1m
    hold-for: 15m
    scenario: api-load

scenarios:
  api-load:
    script: index.js          # uploaded as a Test asset

In this layout, the .yml is the entrypoint and index.js is a test asset. The YAML’s concurrency / ramp-up / hold-for override the script’s options.vus / options.duration.

Multi-file k6 projects

k6 supports ES module imports. If your script imports local modules, upload them alongside the entrypoint:

// index.js (entrypoint)
import { authenticate } from './lib/auth.js';
import { loadUsers } from './data/users.js';

export default function () {
  const token = authenticate();
  // …
}

Upload:

• index.js → Entrypoint
• lib/auth.js → Test asset
• data/users.js → Test asset

MaxoPerf resolves module paths relative to the bundle root, so your import paths work unchanged.

Reading k6 results in MaxoPerf

k6 metrics map to MaxoPerf’s standard result view:

k6 metric	MaxoPerf display
http_req_duration	Latency chart (p50, p95, p99)
http_reqs	Throughput (RPS)
http_req_failed	Error rate
vus	Active VU count over time

Threshold violations from your k6 options.thresholds appear in the run detail failure reasons panel. You can also configure failure criteria directly in MaxoPerf — both are supported.

Do / don’t

Do:

• Export a default function — MaxoPerf uses this as the VU entry point.
• Use k6’s check() API to assert response correctness; results appear in the MaxoPerf error breakdown.
• Use sleep() between iterations to model realistic think time and avoid a pure closed-loop model.
• Keep the entrypoint script’s options.vus and options.duration as defaults that make sense for a solo run — MaxoPerf overrides them with the test’s configured load profile.

Don’t:

• Use Node.js built-ins (require, fs, path) — k6 is not Node.js. It has its own runtime with a subset of browser and Node APIs.
• Import npm packages that are not k6-compatible — only packages that work in the k6 JavaScript runtime can be uploaded as test assets.
• Leave options.thresholds empty — MaxoPerf will still collect metrics, but you lose the automatic pass/fail gate that k6 thresholds provide.

Where to go next

• Taurus executor catalog — the k6 executor entry.
• Taurus fundamentals — wrap your script in a YAML for multi-scenario control.
• Cookbook: staged ramp profile — advanced VU ramping with k6 stages.
• Cookbook: failure criteria / pass-fail gates — set thresholds in MaxoPerf and fail runs automatically.
• Upload test files — Files tab how-to.