Load, Stress, and Benchmark Testing

AI-assisted performance testing uses a coding agent to write k6 load and stress scripts from latency targets a human sets, run them through the k6 MCP server, and rank bottlenecks from the k6 summary and database evidence. The pass or fail verdict comes from k6 thresholds and a baseline comparison in CI, never from the agent’s reading of the results.

This page is for developers and tech leads who own a service’s latency budget. Your checkout API holds 500 requests per second in staging. On launch day traffic triples, the database connection pool runs dry, p95 climbs from 120 ms to 4 s, and nobody can name the commit that removed the headroom. The workflow below finds that limit before your users do.

What you get from AI-assisted load testing

• The k6 MCP server connected to Claude Code, Codex, and Cursor, so the agent validates and runs its own scripts
• Five copy-paste prompts: a threshold-driven load test, a breaking-point stress test, a bottleneck ranking, a front-end check under load, and a baseline-comparison gate
• A CI workflow with two gates: absolute thresholds through the k6 run exit code, and a relative gate that fails a pull request when p95 slides more than 20% against the stored baseline
• A split of responsibilities: people own the thresholds and the baseline, the agent writes scripts and diagnoses, k6 decides pass or fail
• The ways load-test numbers mislead, and how to recover from each one

How do you connect k6 to a coding agent?

k6 is a standalone Go binary that runs JavaScript test scripts. Install it from the k6 installation guide or a package manager (brew install k6). Do not run npm install k6: the k6 package on npm is an unrelated 0.0.0 placeholder.

On top of k6, install Grafana’s official k6 MCP server, grafana/mcp-k6. It gives the agent four tools: validate_script (one VU, one iteration), run_script, list_sections, and get_documentation. The server ships as the mcp-k6 binary, the grafana/mcp-k6 Docker image, or the k6 x mcp subcommand that k6 x agent init wires up, not as an npm package, so treat any npx “k6 MCP” as unofficial. Grafana marks mcp-k6 as experimental (README, checked 2026-09-26; latest release v0.6.1), so pin the version you tested.

The fastest setup is the k6 x agent subcommand, listed in the k6 v2.1.0 release notes as “Bootstrap an AI-assisted k6 testing workflow in any editor”. It requires k6 v2.1.0 or later (current: v2.3.0); on an older k6 you get an unknown-command error, and the mcp-k6 README still describes k6 x mcp as needing a custom xk6 build. Run k6 x to list the built-in subcommands and confirm that agent and mcp are present, then run it in the repository root:

# Preview the files it will write, then write them
k6 x agent init claude-code --dry-run
k6 x agent init claude-code        # other targets: codex-cli, cursor, opencode, vscode-copilot, cline
k6 x agent status                  # show what is installed in this workspace
k6 x agent skills list             # list the skills bundled in the k6 binary

It connects the editor to k6’s built-in k6 x mcp server, so no separate mcp-k6 binary is needed, and installs k6 skills (k6-load-test, k6-smoke-test, k6-trend-analysis, k6-test-maintenance and others). For Claude Code that is .mcp.json, .claude/settings.local.json and .claude/skills/; for Codex, .codex/mcp.json and .codex/skills/; for Cursor, .cursor/mcp.json and .cursor/rules/. Codex (checked against v0.157.1) reads MCP servers from config.toml, not .codex/mcp.json: run codex mcp list, and if k6 is missing, register it with codex mcp add k6 -- k6 x mcp (or -- mcp-k6). To register the standalone server by hand instead, install the binary once (brew tap grafana/grafana && brew install mcp-k6, or docker pull grafana/mcp-k6:latest) and add it per tool:

Claude Code

claude mcp add --scope user --transport stdio k6 -- mcp-k6

# Without a local binary:
claude mcp add --scope user --transport stdio k6 -- docker run --rm -i grafana/mcp-k6

Codex

codex mcp add k6 -- mcp-k6

The command writes this block to ~/.codex/config.toml, which you can also edit directly:

[mcp_servers.k6]
command = "mcp-k6"

Cursor

Add the server to .cursor/mcp.json in the project (the same file k6 x agent init cursor writes):

{
  "mcpServers": {
    "k6": { "command": "mcp-k6" }
  }
}

For front-end performance, add the Chrome DevTools MCP server (chrome-devtools-mcp on npm). It records performance traces (performance_start_trace) and breaks them down into insights such as the LCP breakdown, which makes it a better fit for this job than Playwright MCP. Its lighthouse_audit tool covers accessibility, SEO and best practices but excludes performance, so measure with the trace. It sends usage statistics to Google by default; the --no-usage-statistics flag turns that off.

Claude Code

claude mcp add chrome-devtools --scope user -- npx chrome-devtools-mcp@latest --no-usage-statistics

Codex

codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest --no-usage-statistics

Cursor

Add the server to .cursor/mcp.json in the project:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]
    }
  }
}

Who decides what in the load-testing loop?

The loop is the same in every tool. What matters is who owns each step, because an agent that writes the test, runs it, and judges the result can grade its own homework.

1. You set the targets. p95 and p99 latency, error rate, and the traffic you must survive come from your SLO or the product owner, not from the agent. These numbers become the script’s thresholds.
2. The agent writes the script from those targets, then calls validate_script so a syntax or import error surfaces in one iteration instead of eight minutes into a run.
3. You review the script’s shape, not every line. Check four things: the endpoint and method, the stage durations, the thresholds match what you asked for, and the target host comes from an environment variable.
4. The agent runs it against staging through run_script and reports which thresholds failed.
5. The agent ranks bottlenecks from the k6 summary plus the database and APM evidence from the same time window.
6. CI owns the verdict. k6 exits non-zero when a threshold fails, and a comparison script fails the build when p95 regresses against the baseline. A tech lead approves any change to thresholds or the baseline.

Generate a load test from your latency targets

Start with one endpoint and numbers you supply. A script with your numbers in it can be checked in a minute; “write a load test” produces a plausible script with invented ones.

Copy-paste prompt: a threshold-driven k6 test for one endpoint

Write a k6 script at tests/perf/checkout.js that load-tests
POST /api/checkout on our Node/Express + Postgres backend.

- Stages: ramp 0 -> 200 VUs over 2m, hold 200 VUs for 5m, ramp down over 1m.
- Body: realistic JSON with cartId and paymentMethod, taken from
  tests/perf/data/carts.json via SharedArray. No hardcoded single cart.
- Header: Authorization: Bearer ${__ENV.TOKEN}. Host: ${__ENV.BASE_URL}.
- Thresholds: http_req_duration p(95)<300 and p(99)<800,
  http_req_failed rate<0.01.
- check() that status is 200; sleep(1) think time per iteration.

Validate it with the k6 MCP validate_script tool first. Then run it
against BASE_URL with run_script and report: each threshold pass/fail,
actual p95 and p99, achieved requests per second, and dropped_iterations.
Do not change any threshold to make the run pass.

The result should look like this: concrete stages, your thresholds, and nothing hardcoded that belongs in the environment.

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

const carts = new SharedArray('carts', () => JSON.parse(open('./data/carts.json')));

export const options = {
  stages: [
    { duration: '2m', target: 200 },
    { duration: '5m', target: 200 },
    { duration: '1m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(95)<300', 'p(99)<800'],
    http_req_failed: ['rate<0.01'],
  },
};

export default function () {
  const cart = carts[Math.floor(Math.random() * carts.length)];
  const res = http.post(`${__ENV.BASE_URL}/api/checkout`, JSON.stringify(cart), {
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${__ENV.TOKEN}` },
  });
  check(res, { 'status is 200': (r) => r.status === 200 });
  sleep(1);
}

The invocation differs by tool; the prompt does not.

Claude Code

Start an interactive session with the stored prompt as the first message:

claude "$(cat prompts/perf-checkout.txt)"

Before the agent’s first run_script call, confirm that BASE_URL points at staging. A load test aimed at production by mistake is an outage you caused.

Codex

Run it interactively with the on-request approval policy, under which the model decides when to ask you before running a command:

codex -a on-request "$(cat prompts/perf-checkout.txt)"

Keep long stress runs out of your laptop’s session: start them from a scheduled CI job on a runner that can reach staging instead.

Cursor

Paste the prompt into the Agent chat with the k6 server enabled in .cursor/mcp.json. Keep in-editor runs to short smoke tests; an eight-minute load run ties up the agent while it waits for the result.

Store the prompt in prompts/perf-checkout.txt so the next person generates the same test. For realistic cart and user data, see test data strategies and fixtures.

Find the breaking point with a stress test

A load test asks whether the service holds at expected traffic. A stress test asks at what rate it stops holding, and that number goes into the capacity plan. Define “broken” before the run so the test reports a number, not an impression.

Use an arrival-rate executor here. A VU ramp lets throughput fall as latency rises, so the test quietly sends less traffic exactly when the server struggles.

Copy-paste prompt: a breaking-point stress test

Write a k6 stress test at tests/perf/stress.js that finds the request
rate at which our API breaks.

- Use the ramping-arrival-rate executor: start at 50 iterations/s, add
  50 iterations/s every 2 minutes, up to 1,000 iterations/s.
  Set preAllocatedVUs and maxVUs high enough that dropped_iterations
  stays at 0 until the server, not k6, is the limit.
- Each iteration: GET /api/products, GET /api/products/{random id from
  tests/perf/data/products.json}, POST /api/orders.
- Tag each request with its endpoint name so the summary splits by endpoint.
- Breaking point = the first stage where p95 > 2s OR http_req_failed > 5%.
  Tag requests with the current stage (tagWithCurrentStageIndex from
  k6-utils) and add per-stage thresholds such as
  http_req_duration{stage:3}, so the breaking stage is measured, not
  inferred from the cumulative p95.
  Use thresholds with abortOnFail: true and delayAbortEval: '30s'.

After the run, give me a Markdown table per stage: target rate, achieved
rate, p50/p95/p99 per endpoint, error rate, dropped_iterations. Name the
stage that broke and which endpoint broke first.

If dropped_iterations climbs before latency does, the load generator ran out of VUs or CPU, and the “breaking point” belongs to your laptop. Raise maxVUs or move the run to a larger machine before you trust the number.

Which layer saturated first?

A red threshold tells you the service is slow. It does not tell you whether the cause is a query, the connection pool, application CPU, or a third-party call. That diagnosis is where the agent earns its keep, provided you give it evidence from the same time window and ask it to cite that evidence.

Copy-paste prompt: rank bottlenecks from the evidence

Below are three artifacts from one load test, 14:00-14:08 UTC:
1. The k6 end-of-test summary (JSON).
2. The Postgres slow-query log for that window (log_min_duration_statement=200).
3. Our pool config: pg Pool max=20, Express on 2 Node processes.

Tasks:
- Rank the top 5 contributors to p95 on POST /api/checkout.
- For each, classify it: query, pool exhaustion, application CPU,
  external call, or load generator. Quote the log line or metric
  that supports it. If the evidence does not support a claim, say
  "not supported by the data" instead of guessing.
- Explain why latency degrades non-linearly between the last healthy
  stage and the first failing one.
- Propose the single change with the best latency gain per hour of
  work, with the exact code or CREATE INDEX CONCURRENTLY statement,
  and the k6 run that would prove it worked.

Do not propose schema changes that need downtime.

The last line of the prompt matters: every fix comes with the re-run that proves it. Apply the change, rerun the same script, and compare p95. The measurement, not the agent’s explanation, closes the loop.

To correlate threshold failures with server-side errors and slow transactions, add the Sentry MCP server (remote, OAuth) and ask the agent to line up Sentry’s slowest transactions for the test window against the k6 failures:

Claude Code

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Codex

codex mcp add sentry --url https://mcp.sentry.dev/mcp && codex mcp login sentry

Cursor

Add the remote server to .cursor/mcp.json and complete the OAuth sign-in when prompted:

{
  "mcpServers": {
    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
  }
}

Avoid the npm package named sentry-mcp: it is an unrelated 0.0.1 stub. Sentry’s own stdio package is @sentry/mcp-server, aimed at self-hosted Sentry.

Most load-test cliffs trace back to a query that was fast at seed-data scale. When the ranking points at one, ask the agent to benchmark it with and without the proposed index at production row counts (for example 1M and 10M rows), using EXPLAIN (ANALYZE, BUFFERS) output as the evidence. For production-side tuning after release, continue in production performance optimization.

Check Core Web Vitals while the API is under load

Server p95 can look healthy while the page still feels slow, because the browser waits on work the API never sees. Measure the front end during a load run, not on an idle staging box.

Copy-paste prompt: page performance under API load

Start `k6 run tests/perf/checkout.js` against BASE_URL in the background
from the shell (not run_script, which blocks until the run ends), and wait
for the hold stage (200 VUs). While it runs, use the Chrome DevTools MCP server to:

1. navigate_page to $BASE_URL/dashboard, then record three traces with
   performance_start_trace (reload and autoStop on, the defaults: each
   trace stops itself after about 5 s, so skip performance_stop_trace).
2. Right after each trace, before starting the next one, call
   performance_analyze_insight for the LCPBreakdown insight and any other
   insight that trace flags. It only reads the most recent trace.
3. Report LCP, CLS, and the longest main-thread tasks for each trace,
   the median of the three, and the LCP breakdown of the slowest trace.
4. Compare with one trace taken after the k6 run finishes.

Flag LCP > 2.5s or CLS > 0.1. For each flagged metric, name the request
or script that delayed it and whether it depends on an API the load test hits.

A lab trace does not measure INP, which needs real user interaction. Use field data from your RUM or analytics tool for INP, and use this check for LCP and layout shifts under load. For functional browser tests, see end-to-end test automation.

Gate performance regressions in CI

Two gates catch two different failures, and you need both.

The absolute gate is the script’s thresholds. k6 run exits non-zero when any threshold fails, so the CI step is the run itself. The relative gate catches what thresholds cannot: a change that doubles p95 from 90 ms to 180 ms still passes p(95)<300 while it eats half your headroom. For that you need a stored baseline and a comparison.

Copy-paste prompt: the baseline-comparison gate

Build a performance regression gate for pull requests.

1. tests/perf/smoke.js: 10 VUs for 30s against ${__ENV.BASE_URL}, covering
   GET /api/products, GET /api/products/:id and POST /api/checkout.
   Tag requests with an endpoint tag and add a threshold per tag, such as
   'http_req_duration{endpoint:checkout}': ['p(95)<200'], so the summary
   contains a p95 for each endpoint. http_req_failed rate==0. Add a
   handleSummary() that writes summary.json.
2. scripts/perf-compare.mjs (Node, no dependencies): read perf/baseline.json
   and summary.json, compare p95 of http_req_duration per endpoint tag,
   print a Markdown table, and exit 1 if any endpoint's p95 is more than
   20% above baseline. Treat a missing endpoint in either file as a failure.
3. .github/workflows/perf.yml: on pull_request, start the app with
   docker compose up -d --wait, run the smoke test three times against
   http://localhost:3000, keep the median summary, then run perf-compare.
   permissions: contents: read. actions/checkout with persist-credentials: false.
   No secrets in this job.
4. A separate job on push to main that regenerates perf/baseline.json and
   opens a pull request with it. Give only that job contents: write and
   pull-requests: write. Never overwrite the baseline from a PR run.

Write unit tests for perf-compare.mjs covering: within band, over band,
missing endpoint, malformed JSON.

The workflow the prompt should produce looks like this. It tests the pull request’s own build on the runner, so the result belongs to that change:

.github/workflows/perf.yml

name: perf
on: pull_request
permissions:
  contents: read
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: grafana/setup-k6-action@v1
      - run: docker compose up -d --wait
      - run: k6 run tests/perf/smoke.js
        env:
          BASE_URL: http://localhost:3000
      - run: node scripts/perf-compare.mjs perf/baseline.json summary.json

The workflow above shows one run; the prompt asks for the median of three, which absorbs runner noise. The agent writes the gate, but the gate itself contains no agent. That is what makes the verdict reproducible: the same commit gives the same pass or fail, and nobody has to read the script to trust the red or green check.

Two ownership rules keep the gate honest:

• Put perf/baseline.json and the thresholds blocks under CODEOWNERS for the tech lead. An agent asked to “make CI green” can loosen a threshold or refresh the baseline; a required review turns that into a visible decision. Own scripts/perf-compare.mjs and .github/workflows/perf.yml the same way, and turn on “Require review from Code Owners”: on pull_request the job runs the pull request’s own copy of both, so an unreviewed edit could make the comparison always exit 0. Protecting the oracle covers the pattern in depth.
• Tier the runs by cost. The 30-second smoke test runs on every pull request. The full load test against staging runs nightly on main from a scheduled workflow, with a least-privilege staging token from your secret store. The stress test runs weekly and before launches. For wiring these into the pipeline, see CI/CD pipelines.

When load-test numbers mislead you

The test sends less traffic as the server slows down

With a VU ramp and one-second think time, 200 VUs produce about 200 requests per second only while responses are fast. As latency climbs, each VU waits longer, and throughput drops. Recovery: read the achieved rate in the summary, and switch to constant-arrival-rate or ramping-arrival-rate when you need a fixed request rate.

The load generator saturates before the service

One k6 machine can run out of CPU or VUs long before the service does, and you “discover” a bottleneck in your test rig. Recovery: check dropped_iterations and the generator’s CPU. If either is high, raise maxVUs, use a larger runner, or distribute the load across machines.

p95 looks fine while p99 users time out

A 0.8 s p95 with a 12 s p99 means one request in 100 is failing the user, often one holding a lock or waiting for a pooled connection. Recovery: set a p99 threshold on every critical endpoint and read it in every report.

Staging has the wrong data volume

A query that returns instantly on 10,000 seeded rows can fall back to a sequential scan on 10 million production rows. Recovery: load-test against a production-sized, sanitised dataset, and benchmark suspect queries at production row counts before you accept a result.

The pull request gate tested the wrong build

A PR job that points k6 at shared staging measures whatever is deployed there, not the pull request. Recovery: start the PR’s build on the runner, as the workflow above does, and keep staging runs for the nightly job on main.

The agent made the test pass instead of the service

Asked to fix a failing run, an agent can relax a threshold, shorten the hold stage, or drop the slow endpoint from the script. Recovery: diff tests/perf/ in every pull request that touches it, require CODEOWNERS approval for thresholds and the baseline, and put “do not change any threshold” in every prompt.

The generated traffic pattern is not your traffic

A model asked for “a load test” invents a plausible mix of requests. Recovery: give it the real shape from your analytics, for example “60% of requests are GET /api/products, peak is 14:00 CET, a session makes 12 API calls over eight minutes”.

Identical runs give different numbers

Shared CI runners are noisy. Recovery: run the smoke test three times, gate on the median, and keep the 20% band. If the gate still flaps, widen the band for that endpoint, record why in the pull request, and rerun rather than merging on a red check.

When a result looks impossible, give the agent the full k6 summary and the generator’s resource metrics, and ask it to decide between a real server bottleneck and a test artifact before you escalate.

Where to go next with performance testing

Testing with AI: overview Where performance tests sit among the other verification gates.

API test automation Functional API tests to run before the load test.

Protecting the oracle Keep agents from editing the checks that judge their work.

CI/CD pipelines Wire the performance gates into your delivery pipeline.

Monitoring and observability Check load-test predictions against production.

Error and fault injection Test how the service fails, not only how fast it runs.