k6 scripts on MaxoPerf

k6 is a JavaScript load-testing engine with an ES-module API. MaxoPerf runs k6 scripts directly. Upload your .js file and mark it as the entrypoint. MaxoPerf detects k6, validates the script, and sends it to the runner fleet.

Upload and run your own scripts.

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. At run time, MaxoPerf merges the script’s options object (VUs, duration, thresholds) with its run overlay. MaxoPerf’s reporting configuration wins on any conflicting key.

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 checks that the script parses 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 set VUs, ramp-up, and hold-for in one place. Use this 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 next to 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 work.

Do / don’t

Do:

• Export a default function. MaxoPerf uses it 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. You can only upload packages that work in the k6 JavaScript runtime as test assets.
• Leave options.thresholds empty. MaxoPerf still collects metrics, but you lose the automatic pass/fail gate that k6 thresholds give you.

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.