Skip to content

Configure k6

Adapter status: ✅ Complete (performance). k6 is a valid value for stack.test_framework: lippia-neo-bootstrap-stack detects and configures it, and the performance skills generate, run and report the load tests. It is not a functional-suite framework: it does not use lippia-neo-generate-test-suite, lippia-neo-run-and-heal or lippia-neo-bootstrap-ci (see section 9).

Value in qa-stack.yaml test_framework: k6
Language javascript (forced)
App type api (forced)
What it uses k6 + an API collection (Postman or Bruno) + CSV files with test data
Load profiles smoke, load, stress, spike
Configuration performance block of qa-stack.yaml
Scripts folder performance.scripts_dir (default performance/)
Results folder performance.results_dir (default results/)

The skills that use it are described in Performance skills. They run without asking questions: everything they need comes from the input or from qa-stack.yaml.


1. What you need installed

Tool Version What for How to check it
k6 0.49 or higher Run the load scripts k6 version
Node.js A current version Run NEO's generator and runner (.js scripts) node --version

NEO does not install k6. If the runner can't find it, it stops with status blocked and tells you it must be installed separately. It looks for it in the PATH and, on Windows, in C:\Program Files\k6\k6.exe.

You also need these project inputs:

Input What for Where it goes
API collection (Postman .json or Bruno folder) Endpoints, login and flows come from it performance.collection.path (or auto-detected)
Collection environment (optional) Non-sensitive variable values performance.collection.environment_path (or auto-detected next to the collection)
CSV with users/credentials and test data The scripts read them at run time performance.data_dir (default data/)
Secrets (tokens, keys) Passed at run time Only in paths.env_file (default .env.tests) or process environment variables

2. Example qa-stack.yaml

stack:
  test_framework: k6
  language: javascript
  app_type: api
  pipeline_provider: gitlab

environment:
  base_url: https://api-staging.myapp.com

performance:
  collection:
    path: doc/                  # collection file or folder · null = auto-detect
    format: auto                # auto | postman | bruno
    environment_path: null      # null = auto-detect next to the collection
  data_dir: data/               # CSV with credentials/test data
  scripts_dir: performance/     # where scripts are generated
  results_dir: results/         # where runs are stored
  profiles: [smoke, load, stress, spike]
  time_scale: 1                 # duration multiplier (quick run: 0.05)
  cooldown_s: null              # pause between profiles · null = 30 s x time_scale (min. 1 s)
  mutations:
    include: writes             # none | writes | all
    probe_iterations: 3         # 0 to 5
  on_missing: block             # block | warn

paths:
  env_file: .env.tests
  reports_dir: test-results/reports/

Every performance key has a default: anything missing uses the value shown above. The block stores only paths and non-sensitive parameters, never credentials.

Other optional keys in the block, all null by default: defaults.login_weight, defaults.on_exhaust (skip_writes | recycle | abort | synthesize), defaults.think_seconds and defaults.mix.

With k6, lippia-neo-bootstrap-stack only asks for the framework and CI (if it can't detect them), base_url and the performance block. It does not ask about authentication, operating system, version, user stories, bugs or test management tool, and it does not create .mcp.json.


3. How it gets configured (lippia-neo-bootstrap-stack)

Ask the assistant:

Set up the project for QA with lippia-neo-bootstrap-stack

The skill detects k6 if the repo has scripts that import 'k6', k6 in package.json or performance/*.js, and forces app_type: api and language: javascript. It also looks for collections (*.postman_collection.json or Bruno folders with bruno.json / *.bru) under doc/, docs/, collections/, postman/, api/ or the root, and offers them to you. It asks one at a time:

Question Key Options
API collection performance.collection.path The detected candidates, another path, or null (auto-detect on use)
Data folder performance.data_dir data/ (default) or another
Scripts folder performance.scripts_dir performance/ (default) or another
Profiles performance.profiles All 4 (default) or a subset
Duration performance.time_scale 1 (default, real duration), 0.05 (short run, only to check that everything works) or another number
Methods that modify data performance.mutations.include none (reads only), writes (default: POST/PUT/PATCH) or all (includes DELETE)
Write pre-test performance.mutations.probe_iterations 3 repetitions (default), 1 to 5, or 0 to skip

results_dir, cooldown_s, defaults.* and on_missing are written with their defaults without asking; you can edit them by hand. paths.env_file stays as .env.tests (the file is not created) and is added to .gitignore, together with .claude and performance.results_dir.


4. Credentials and data

  • Secrets are never written into any script or into qa-stack.yaml. The scripts read them from the environment (__ENV).
  • Test usernames and passwords go in CSV files inside performance.data_dir. NEO only reads the header, the separator and the row count; it never copies or shows the values.
  • Other secrets (token, API key, etc.) go in paths.env_file (default .env.tests, NAME=value format, kept out of git) or as process environment variables. In CI they come from the pipeline environment.
  • The value of a basic authentication variable is passed as a raw user:password (the script encodes it). If you pass it already as Basic <base64>, it gets encoded twice and every request returns 4xx.
# .env.tests (kept out of git)
API_KEY=<TOKEN>

Supported authentication modes: bearer, cookie, api_key_header, api_key_query, basic and none. The login request comes from the collection.


5. What NEO generates

lippia-neo-read-api-collection reads the collection, tests the login (a single attempt) and the read requests, and proposes the flows. Then lippia-neo-generate-k6-script turns them into scripts. The code is written by a deterministic renderer: the same input always produces the same output, and generated files are not edited by hand (you regenerate).

performance/                   ← performance.scripts_dir
├── lib/
│   ├── config.js              # profiles, load model, thresholds
│   ├── checks.js              # expected statuses and per-status metrics
│   ├── auth.js                # authentication (if there are session flows or a measured login)
│   └── data.js                # CSV reading and pools (if there is a CSV or login)
├── scenarios/
│   └── <scenario>.js          # one file per flow
├── smoke.js  load.js  stress.js  spike.js    # one script per profile
├── render-input.json
├── generation-report.json     # warnings, excluded items, decisions, declared load, commands
└── README.md                  # how to validate and run, variables, limits

Default profiles

Profile Default load Model
smoke 1 virtual user for 30 s, one scenario at a time Sequential
load Ramps to 10 in 1 min, holds 5 min, ramps down to 0 in 1 min Closed (vus)
stress Steps of 10, 20, 30 and 40 (2 min each), then down to 0 Open (arrival_rate)
spike 2 → 50 in 15 s, holds 1 min, back to 2, then down to 0 Open (arrival_rate)

Each stage value is the total across all scenarios, split according to the mix (mix, even by default). time_scale multiplies every duration (minimum 1 s per stage) and does not change the scripts, only the run.

What is included in the load and what is left out

  • Writes (POST/PUT/PATCH) are included according to mutations.include; DELETE only with all. A POST that is a read-only query (for example, a search) is treated as a read.
  • Left out (with the reason in generation-report.json and in the warnings): destructive requests, requests to another host, requests that failed in the pre-test, requests that depend on captured values that no chain provides, or writes without a body.
  • When the CSV rows run out on requests that write, the default (skip_writes) skips those writes; recycle reuses rows, abort stops the run.
  • A session that cannot be established never turns green: if the preparation login fails, the run is aborted.

Write pre-test

If mutations.include is not none and probe_iterations is greater than 0, lippia-neo-read-api-collection repeats each write (up to 5 times, with its body) to detect single-use data. That test creates real data in the environment. Against a non-local host it only runs with performance.confirm_remote: true. It does not test the login, nor requests that depend on captured values, and it only sends JSON bodies.


6. How lippia-neo-run-performance-test runs it

The runner (scripts/run-profile.js) runs the profiles one at a time, in sequence, never in parallel, with a pause between them (cooldown_s; if null, 30 s x time_scale, minimum 1 s). Before launching anything it validates that the scripts' required variables exist. If one is missing, it refuses the run (refused, code 2) without launching k6.

Each run is stored in <results_dir>/<profile>-<UTC yyyymmdd-HHmmss>/:

results/
├── runs.json
└── load-20260105-143000/
    ├── summary.json
    ├── load-load-check.json     # summary with declared vs. achieved load, statuses and latencies
    ├── console.utf8.txt         # k6 output, with sensitive values masked
    ├── dashboard.html           # not generated on very short runs
    └── run-meta.json

The k6 exit code is classified as: 0 ok, 99 thresholds crossed, 108 aborted, anything else error. A 99 or a 108 is run data: it gets reported, not retried.

Runner options (taken from the input or from qa-stack.yaml; the input wins):

Option Default What for
profiles performance.profiles Which profiles to run
base_url environment.base_url URL of the environment under test
time_scale performance.time_scale or 1 Duration scale
cooldown_s performance.cooldown_s Pause between profiles
script_dir / results_dir performance.scripts_dir / performance.results_dir Scripts and results folders
reset_command none Command that resets the system state; runs before each profile (if it fails, the run stops)
max_duration no cap Per-profile cap (e.g. 30m); if exceeded, it is cut off and recorded as error
confirm_remote false Explicit authorization to run stress or spike against a non-local host

Careful with stress and spike. Against a host that is not local (localhost, 127.0.0.1, ::1) they only run if the caller passes confirm_remote: true. Without it, the runner returns needs_input and launches nothing.

To write the final report with the runs (performance-report-<project>-<UTC>.md in paths.reports_dir) there is lippia-neo-write-performance-report; see Performance skills.


7. Quick checklist

k6 version                    # 0.49 or higher
node --version
ls doc/                       # the collection (or the performance.collection.path value)
ls data/*.csv                 # user / data CSV files
ls .env.tests                 # secrets, if the scripts ask for them
grep -n "performance:" qa-stack.yaml

If everything responds, ask the assistant to read the collection, generate the scripts and run the profiles.


8. Common problems (and what to do)

What you see Why it may happen What to do
Status blocked because of k6 k6 is not installed or its version is older than 0.49 Install or upgrade k6 outside NEO
Status refused (code 2), profiles not_run A required script variable is missing Define it in paths.env_file or in the process environment; the message names which ones are missing
Status needs_input with confirm_remote in missing stress or spike was requested against a remote host without authorization Pass confirm_remote: true only when appropriate
Status needs_input with flows in missing There is no collection read report and no input flows Run lippia-neo-read-api-collection first
blocked because of Node node --version fails Install Node.js
Every request returns 4xx with basic auth The value was passed already base64-encoded Pass raw user:password
Exit 99 on a profile A threshold was crossed It is a test result: check load-check.json or the report
Warning about concurrent k6 processes Other k6 processes are running on the machine Stop them; they invalidate the measurement
The generator returns conflict A file in scripts_dir exists and was not generated by NEO Move or rename that file
Warning that maxVUs is insufficient Too few users in the CSV for the profile's peak Add users, lower the peak, accept the drops or set max_vus

9. Current limitations

What What happens with k6 Alternative
CI jobs (lippia-neo-bootstrap-ci) It does not generate a performance job: it stops with framework_not_supported_by_this_skill Build the job by hand and run the lippia-neo-run-performance-test runner; in CI the secrets come from the environment
Functional-suite skills (lippia-neo-generate-test-suite, lippia-neo-run-and-heal) They abort with framework_not_supported_by_this_skill Use the performance skills
Write test It creates real data in the environment and only sends JSON bodies; it does not test requests that depend on captured values mutations.include: none to work with reads only, or probe_iterations: 0
Remote environments stress and spike require confirm_remote Run against a local environment or authorize it explicitly
qa-stack.yaml parser Minimal reader: no anchors, multiline values or lists of maps Write the performance block with simple maps and lists
Generated scripts They are not edited by hand Change the input or qa-stack.yaml and regenerate