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 |
NEOdoes not install k6. If the runner can't find it, it stops with statusblockedand tells you it must be installed separately. It looks for it in thePATHand, on Windows, inC:\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-stackonly asks for the framework and CI (if it can't detect them),base_urland theperformanceblock. 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.NEOonly 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=valueformat, kept out of git) or as process environment variables. In CI they come from the pipeline environment. - The value of a
basicauthentication variable is passed as a rawuser:password(the script encodes it). If you pass it already asBasic <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 withall. 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.jsonand 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;recyclereuses rows,abortstops 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
stressandspike. Against a host that is not local (localhost,127.0.0.1,::1) they only run if the caller passesconfirm_remote: true. Without it, the runner returnsneeds_inputand 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 |