vegaload

module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: Apache-2.0

README

VegaLoad

VegaLoad is a thin, open-source load testing tool: a single static binary with a scriptable core engine, protocol drivers (HTTP/1.1, HTTP/2, gRPC, WebSocket, MQTT, Kafka, PostgreSQL, and raw TCP and UDP), and a self-contained HTML report — no server, no account, no telemetry.

It's also agent-native: vegaload init registers VegaLoad as an MCP server for Claude Code, Cursor, or any other MCP-capable agent host, so an agent can run tests, read results, and explain failures through the same CLI commands a human would type. It is never agent-mandatory — every feature works from a plain terminal with nothing else installed. See AGENTS.md for the design principle behind that split.

Status

Phase 0 (core engine, CLI, protocols, scripting) and Phase 1 (the HTML/JSON report) are done. Phase 2 (the MCP server, skill bundles, and a versioned eval suite for the MCP tools) is also done — this README's walkthrough covers all three. Since then, v0.3.0 and v0.4.0 added thresholds, checks, vegaload validate, a baseline gate (run -baseline), JUnit output and a CI job summary, and data files and env vars (-data, -env, -secret-env). The main branch, which becomes v0.5.0, adds MCP over HTTP and SSE (mcp serve -http), a second eval suite (mcp eval -suite v2), Windows support, a Helm chart that runs a test as a Kubernetes Job with no CRD, and a container image published to ghcr.io/vegaload/vegaload. In a script, a response's Set-Cookie header is every cookie that response set, separated by newlines. A script that used to read only the first cookie now sees the rest as well. A Harness RT bridge (--move-to-harness) is intentionally out of scope for now.

Install

With Homebrew (macOS and Linux), after the first tagged GitHub release:

brew install vegaload/tap/vegaload
vegaload version

brew tap vegaload/tap followed by brew install vegaload does the same thing. Upgrade with brew upgrade vegaload. Until a tag exists, build from source below.

Or build from source (Go 1.22+):

git clone https://github.com/vegaload/vegaload
cd vegaload
go build -o vegaload ./cmd/vegaload
./vegaload version

go install github.com/vegaload/vegaload/cmd/vegaload@latest also works once the repository is public. Release archives for Linux, macOS and Windows are attached to each GitHub release.

On Windows 10 or later, download the zip for your CPU from the release page, unpack it, and run vegaload.exe. Put its folder on your PATH to run vegaload from anywhere. run, validate, doctor, init and mcp serve all work. Python scenarios need Python 3 from python.org (VegaLoad finds python3, python or the py launcher). Scoop and winget packages are set up in RELEASING.md and come after the first Windows release. A scratch-based Docker image is published to ghcr.io/vegaload/vegaload with each release from v0.5.0 on (linux/amd64 and linux/arm64):

docker run --rm ghcr.io/vegaload/vegaload:0.5.0 version

You can also build it yourself from the included Dockerfile (docker build .). The image carries nothing but the binary and CA certificates, so Python-scripted scenarios (which shell out to a local python3) need a different base image — see the Dockerfile's comment.

Getting started

For short recipes by task (ramp, CI gate, baseline, steps, data, and more), see the cookbook.

Everything below uses examples/sample-app, a small widgets service with injected latency and a ~3% failure rate on creates, served over HTTP/1.1, HTTP/2, WebSocket, and gRPC, built specifically so this walkthrough has something real to point vegaload at. Start it in its own terminal first:

cd examples/sample-app
go run .

Leave it running, and do the rest from a second terminal at the repository root.

1. Run a load test, no scenario file needed

Protocol-direct mode drives a target straight from CLI flags — useful for a quick check, or for an agent that just got a URL and doesn't need to write a script first:

./vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 -vus 10 -duration 30s

This runs 10 virtual users against the sample app for 30 seconds, prints a summary, and writes (and opens) a self-contained HTML report — one file, with the full latency distribution and a requests/errors-over-time chart, nothing else to host.

Test a raw TCP or UDP service

For a service that speaks its own protocol, use the tcp or udp driver. Each iteration opens a connection, sends the body, optionally checks the reply, and closes. Driver settings go in repeatable -opt key=value flags.

# Does the service answer PING with PONG? Read until the reply contains PONG.
./vegaload run -target tcp://127.0.0.1:6379 -protocol tcp \
  -body 'PING\r\n' -opt expect=PONG -vus 10 -duration 20s

# Read exactly 8 bytes back, or read until a delimiter, or only connect.
./vegaload run -target tcp://127.0.0.1:7000 -protocol tcp -body 'hello\n' -opt read=8
./vegaload run -target tcp://127.0.0.1:25 -protocol tcp -opt until='\r\n' -opt expect=220
./vegaload run -target tcp://127.0.0.1:7000 -protocol tcp

# Send one UDP datagram. Add -opt reply=true or -opt expect=... to wait for an answer.
./vegaload run -target udp://127.0.0.1:514 -protocol udp -body '<13>test message\n'

The tcp options are read, until, expect, max, tls and escape. The udp options are reply, expect and escape. In -body, expect and until, the text may use \n, \r, \t, \0, \\ and \xNN. Pass -opt escape=false to send backslashes as they are. Use -opt tls=true for a TLS service, with -insecure if its certificate is not trusted. tls=true takes the four options under "TLS with your own CA". UDP has no TLS, so those options are an error. A misspelled option is an error, not ignored. The same host allowlist and caps apply as for HTTP targets. Each iteration opens a new connection, so a very high rate on one machine can run out of local ports. Keep the rate moderate, or spread the load over more machines.

Test an MQTT broker

The mqtt driver does one job per iteration: connect, do the job, close. The job is set with -opt mode=.... The body is the message payload.

# Publish a message and wait for the broker's ack (the default mode).
./vegaload run -target mqtt://127.0.0.1:1883 -protocol mqtt -body 'hello' \
  -opt topic=load/test -opt qos=1 -vus 20 -duration 30s

# Publish, and wait until the same message comes back. This measures
# delivery through the broker. {id} is a unique client id for each iteration.
./vegaload run -target mqtt://127.0.0.1:1883 -protocol mqtt -body 'ping {id}' \
  -opt mode=roundtrip -opt topic='load/{id}' -opt qos=1

# Subscribe and wait for 5 messages that contain "ok".
./vegaload run -target mqtt://127.0.0.1:1883 -protocol mqtt \
  -opt mode=subscribe -opt topic='sensors/#' -opt count=5 -opt expect=ok

The options are mode (publish, subscribe, roundtrip), topic, qos, retain, username, password_env, client_id, count, expect and keepalive. Put the password in an environment variable and pass its name with -opt password_env=NAME (it needs username), so it is not on the command line. In roundtrip mode the body must contain {id}, so each user can tell its own message from the messages of other users. Use mqtts:// for TLS, with -insecure if the certificate is not trusted. mqtts:// takes the four options under "TLS with your own CA". Every iteration uses a new client id, because a broker closes an older connection that has the same id. The same host allowlist and caps apply as for HTTP targets.

Test a Kafka cluster

The kafka driver uses a pure Go client, so there is nothing to install. The target is kafka://host:9092, or kafkas://host:9093 for TLS. kafkas:// takes the four options under "TLS with your own CA". The job of each iteration is set with -opt mode=...:

# Produce: send records and wait for the broker's ack (the default mode).
./vegaload run -target kafka://127.0.0.1:9092 -protocol kafka -body '{"order":1}' \
  -opt topic=orders -opt key='user-{id}' -opt acks=all -vus 20 -duration 30s

# Roundtrip: produce, then read exactly those records back.
./vegaload run -target kafka://127.0.0.1:9092 -protocol kafka -body 'ping {id}' \
  -opt mode=roundtrip -opt topic=orders -vus 10 -duration 30s

# Consume: read 5 records from the start of the topic and check their text.
./vegaload run -target kafka://127.0.0.1:9092 -protocol kafka \
  -opt mode=consume -opt topic=orders -opt count=5 -opt expect=order

# Admin: create and delete a topic, over and over. {id} makes each name new.
./vegaload run -target kafka://127.0.0.1:9092 -protocol kafka \
  -opt mode=admin -opt action=topic_lifecycle -opt topic='load-{id}' -opt partitions=3

The options are mode (produce, consume, roundtrip, admin), topic, key, acks (all, leader, none), compression (none, gzip, snappy, lz4, zstd), count, expect, from (start, end), action (list_topics, create_topic, delete_topic, topic_lifecycle, list_groups, describe_cluster), partitions, replication, sasl (plain, scram-sha-256, scram-sha-512), username, password_env and client_id. Put the SASL password in an environment variable and pass its name with -opt password_env=NAME, so it is not on the command line. An option that the chosen mode does not use is an error.

Some points to know:

  • Produce, roundtrip and admin share one client between all users, like a real producer. Consume, and the reading half of roundtrip, open a new connection for each iteration, so that time is part of the result.
  • Roundtrip reads back the exact partition and offset it wrote. It does not use consumer groups, so it does not measure group rebalancing. Consumer groups are not part of this driver yet.
  • The first broker is the target you give. The client then connects to the broker addresses that the cluster announces. The host allowlist checks only the first address, so make sure the announced brokers are ones you may test.
  • The topic must exist, unless the broker creates topics on its own. Use the admin create_topic action first.
Test a PostgreSQL database

The postgres driver runs one SQL text for each iteration, read from -body, and reads every row it returns. It uses a pure Go client, so there is nothing to install. It is read-only by default: every transaction is read-only, so a load test cannot change data by mistake. Add -opt allow_writes=true to let the SQL write. The target is postgres://host[:port][/database] (or postgresql://), with port 5432 by default. The URL may end with ?sslmode=... and ?application_name=..., as in psql. Any other setting after the ? is refused, and a password there is refused too. It also works with servers that speak the PostgreSQL protocol, such as CockroachDB, YugabyteDB and Aurora.

# One query, 20 users, for 30 seconds. The password is in $DB_PASSWORD.
./vegaload run -target postgres://127.0.0.1:5432/app -protocol postgres \
  -body 'select id, total from orders where customer_id = 42' \
  -opt username=app -opt password_env=DB_PASSWORD -opt pool=20 -opt min_rows=1 \
  -vus 20 -duration 30s

# A parameterised, prepared statement: $1 and $2 come from -opt args.
./vegaload run -target postgres://127.0.0.1:5432/app -protocol postgres \
  -body 'select * from orders where customer_id = $1 and status = $2' \
  -opt 'args=[42, "paid"]' -opt query_mode=extended -opt username=app

# A transaction that writes. Several statements in one text work in the
# default mode, and writes need allow_writes.
./vegaload run -target postgres://127.0.0.1:5432/app -protocol postgres \
  -body 'begin; update accounts set n = n + 1 where id = 1; select n from accounts where id = 1; commit' \
  -opt username=app -opt allow_writes=true -opt expect=1

The options are username, password_env, database, sslmode (disable, prefer, require, verify-full), application_name, pool, allow_writes, query_mode, args, min_rows, expect and max_rows. ca_file, cert_file, key_file and tls_server_name are in TLS with your own CA. ca_file needs sslmode=verify-full.

  • The connections are kept in a pool that all users share, like an application's pool. pool is the most connections to open (default 10). Waiting for a free connection counts as part of the measured time, so set pool to at least the number of users if you want to measure the server and not the queue.
  • Put the password in an environment variable and pass its name with -opt password_env=NAME (it needs a user), so it is not on the command line. A password in the URL is refused. The standard PGPASSWORD variable and a ~/.pgpass file work too, as they do for psql.
  • query_mode=simple (the default) sends the SQL as one text, so it can hold several statements, such as a transaction. query_mode=extended prepares the statement once for each connection and reuses it, as most applications do. It runs one statement. With args in simple mode, VegaLoad puts the values into the text as quoted values (a value is never read as SQL), so several statements and args work together: begin; update t set a = $2 where id = $1; select a from t where id = $1; commit. The result is the last statement that returned rows. Each $n must have a value, and each value must be used.
  • Read-only is the default. VegaLoad asks the server to make every transaction read-only, so an insert, update, delete or DDL statement fails with SQLSTATE 25006, and the error says how to allow it. allow_writes=true lets the SQL write. This is a safety net, not a lock: the SQL can still ask for a read-write transaction itself (begin read write), or turn the setting off and write in the same text (set default_transaction_read_only = off; ...). Each call puts the setting back before its SQL runs, so one call cannot leave writes on for the next. Use a read-only database role when you need a real lock.
  • An iteration passes when the SQL ran without a server error and the result has at least min_rows rows. With expect, some value in the result must also contain the text (only the first max_rows rows are checked). A server error fails the iteration, and its message and SQLSTATE code are in the report.
  • If a transaction fails halfway, the connection is closed and replaced, never reused. A timeout does the same.
  • The host allowlist and caps apply as for HTTP targets. Load tests change data and use real server resources, so run them against a test database.
Test a MySQL or MariaDB database

The mysql driver runs one SQL text for each iteration, read from -body, and reads every row it returns. It uses a pure Go client, so there is nothing to install. It is read-only by default: every new connection runs SET SESSION TRANSACTION READ ONLY, so a load test cannot change data by mistake. Add -opt allow_writes=true to let the SQL write. The target is mysql://host[:port][/database] (or mariadb://), with port 3306 by default. -protocol stays mysql. The URL may end with ?tls=.... Any other setting after the ? is refused, and a password there is refused too. It also works with servers that speak this protocol, such as MariaDB, TiDB, Aurora MySQL and Percona Server.

# One query, 20 users, for 30 seconds. The password is in $DB_PASSWORD.
./vegaload run -target mysql://127.0.0.1:3306/app -protocol mysql \
  -body 'select id, total from orders where customer_id = 42' \
  -opt username=app -opt password_env=DB_PASSWORD -opt pool=20 -opt min_rows=1 \
  -vus 20 -duration 30s

# A parameterised statement: ? comes from -opt args.
./vegaload run -target mysql://127.0.0.1:3306/app -protocol mysql \
  -body 'select * from orders where customer_id = ? and status = ?' \
  -opt 'args=[42, "paid"]' -opt username=app

# A transaction that writes. Several statements in one text work in the
# default mode, and writes need allow_writes.
./vegaload run -target mysql://127.0.0.1:3306/app -protocol mysql \
  -body 'begin; update accounts set n = n + 1 where id = 1; select n from accounts where id = 1; commit' \
  -opt username=app -opt allow_writes=true -opt expect=1

The options are username, password_env, database, tls (preferred, false, true, skip-verify), pool, allow_writes, query_mode, args, min_rows, expect and max_rows. ca_file, cert_file, key_file and tls_server_name are in TLS with your own CA. With tls=preferred and no ca_file, the certificate is not checked. With ca_file, it is checked, and a server that does not offer TLS still uses plain text.

  • The connections are kept in a pool that all users share, like an application's pool. pool is the most connections to open (default 10). Waiting for a free connection counts as part of the measured time, so set pool to at least the number of users if you want to measure the server and not the queue.
  • Put the password in an environment variable and pass its name with -opt password_env=NAME (it needs a user), so it is not on the command line. A password in the URL is refused.
  • tls=preferred (the default) uses TLS when the server offers it, and plain text when it does not. true checks the certificate and the host name. With -insecure, true does not check the certificate. false stays on plain text. skip-verify uses TLS and does not check the certificate. MySQL 8's default login works with tls=false: the client asks the server for its public key. The password itself is only sent inside TLS when tls=true or tls=skip-verify.
  • query_mode=simple (the default) sends the SQL as one text, so it can hold several statements, such as a transaction. query_mode=prepared prepares the statement once and reuses it, as most applications do. It runs one statement, and it does not keep a connection for the call. set, use, lock, xa, unlock, begin and start are refused in that mode. With args in simple mode, VegaLoad puts the values into the text as quoted values (a value is never read as SQL), so several statements and args work together: begin; update t set a = ? where id = ?; select a from t where id = ?; commit. The result is the last statement that returned rows. Each ? must have a value, and each value must be used. A text of several statements reports rowsAffected as 0: that count is not available then. A single insert or update does report rowsAffected, and a single insert reports lastInsertId.
  • Read-only is the default. An insert, update, delete or DDL statement fails, and the error says how to allow it. allow_writes=true lets the SQL write. This is a safety net, not a lock: the SQL can still ask for a read-write transaction itself (START TRANSACTION READ WRITE). set session transaction read write; insert ... in one text works too. The next call is blocked, because SET discards the connection. Use a read-only database role when you need a real lock.
  • An iteration passes when the SQL ran without a server error and the result has at least min_rows rows. With expect, some value in the result must also contain the text (only the first max_rows rows are checked). A server error fails the iteration, and its message, error number and SQLSTATE are in the report.
  • If a statement fails, the connection is closed and replaced, never reused. A timeout does the same. LOAD DATA LOCAL INFILE stays off.
  • The host allowlist and caps apply as for HTTP targets. Load tests change data and use real server resources, so run them against a test database.
Test a Redis or Valkey server

The redis driver runs one command for each iteration, read from -body, or several commands, one per line. Two or more lines are a pipeline. They are not atomic. -opt transaction=true runs them inside MULTI/EXEC, even when there is only one. It uses a pure Go client, so there is nothing to install. It is read-only by default. Redis has no session read-only switch, so VegaLoad checks every command before it sends anything. If one command in a pipeline is refused, nothing is sent. Add -opt allow_writes=true to allow writes. Admin commands such as FLUSHALL also need -opt allow_admin=true, and allow_admin without allow_writes is an error. A read-only user on the server is still the real lock.

The target is redis://host[:port][/database] or rediss:// for TLS, with port 6379 by default. -protocol stays redis. The URL takes no query string, and a password in the URL is refused. It is tested with Redis 6 and 7 and with Valkey 7 and 8. KeyDB, Dragonfly and Garnet often work too.

# One read, 20 users, for 30 seconds. The password is in $REDIS_PASSWORD.
./vegaload run -target redis://127.0.0.1:6379 -protocol redis \
  -body 'GET user:42' \
  -opt password_env=REDIS_PASSWORD -opt pool=20 \
  -vus 20 -duration 30s

# A placeholder is one whole argument, even when the value has spaces.
./vegaload run -target redis://127.0.0.1:6379 -protocol redis \
  -body 'GET ?' -opt 'args=["user:42"]'

# A pipeline that writes. Both lines need allow_writes.
./vegaload run -target redis://127.0.0.1:6379 -protocol redis \
  -body $'INCR hits:42\nEXPIRE hits:42 60' \
  -opt allow_writes=true

The options are username, password_env, database, tls (false, true, skip-verify), pool, protocol (2 or 3), allow_writes, allow_admin, transaction, args, min_rows, expect and max_rows. ca_file, cert_file, key_file and tls_server_name are in TLS with your own CA.

  • The connections are kept in a pool that all users share. pool is the most connections to open (default 10). Waiting for a free connection counts as part of the measured time.
  • Put the password in an environment variable and pass its name with -opt password_env=NAME. A password does not need a user: the default user is fine. An ACL user can be username or the user in the URL.
  • database is a number from 0 to 255. It can also be the path of the URL, as redis://host:6379/2. Give it in one place.
  • tls=false is the default for redis://. rediss:// means TLS. true checks the certificate and the host name. With -insecure, true does not check the certificate. skip-verify uses TLS and does not check the certificate. tls=false with rediss:// is an error.
  • protocol=2 (the default) speaks RESP2. protocol=3 speaks RESP3.
  • A command is written the way redis-cli writes it. Spaces and tabs split arguments. "double quotes" and 'single quotes' keep spaces. Inside double quotes, \n, \r, \t, \b, \a, \\, \" and \xHH are escapes. Inside single quotes, only \' is an escape. A line that is blank or starts with # is skipped. A quoted string cannot cross a line.
  • An argument that is exactly ?, and is not quoted, is replaced by the next value from args. The value is one argument. It is never pasted into the command text, so a value that contains spaces, quotes or newlines cannot change the command. "?" is a literal question mark. The command name cannot be a ?, and neither can a subcommand such as the word after CONFIG. Every ? needs a value, and every value must be used. A boolean or null is refused: pass a string or a number.
  • One line is one round trip. Two or more lines are a pipeline. A pipeline is limited to 10000 commands. transaction=true wraps them in MULTI/EXEC.
  • These commands are always allowed: GET, MGET, STRLEN, GETRANGE, EXISTS, TYPE, TTL, PTTL, EXPIRETIME, PEXPIRETIME, RANDOMKEY, DBSIZE, SCAN, KEYS, DUMP, LCS, GETBIT, BITCOUNT, BITPOS, BITFIELD_RO, SORT_RO, HGET, HMGET, HGETALL, HEXISTS, HLEN, HKEYS, HVALS, HSTRLEN, HRANDFIELD, HSCAN, LINDEX, LLEN, LRANGE, LPOS, SISMEMBER, SMISMEMBER, SCARD, SMEMBERS, SRANDMEMBER, SSCAN, SINTER, SUNION, SDIFF, SINTERCARD, ZSCORE, ZMSCORE, ZCARD, ZCOUNT, ZLEXCOUNT, ZRANGE, ZRANGEBYSCORE, ZRANGEBYLEX, ZREVRANGE, ZREVRANGEBYSCORE, ZREVRANGEBYLEX, ZRANK, ZREVRANK, ZSCAN, ZRANDMEMBER, ZDIFF, ZINTER, ZUNION, ZINTERCARD, GEOPOS, GEODIST, GEOHASH, GEOSEARCH, GEORADIUS_RO, GEORADIUSBYMEMBER_RO, PFCOUNT, XLEN, XRANGE, XREVRANGE, XREAD, EVAL_RO, EVALSHA_RO, FCALL_RO, PING, ECHO, TIME, INFO, ROLE, LOLWUT. These subcommands are reads too: OBJECT ENCODING|FREQ|IDLETIME|REFCOUNT, MEMORY USAGE, COMMAND with no subcommand, COMMAND COUNT|INFO|DOCS|LIST|GETKEYS, SLOWLOG GET|LEN, PUBSUB CHANNELS|NUMSUB|NUMPAT|SHARDCHANNELS|SHARDNUMSUB, XINFO STREAM|GROUPS|CONSUMERS, ACL WHOAMI.
  • Anything else is a write and needs allow_writes=true. That includes SET, DEL, EXPIRE, INCR, GETEX, GETDEL, TOUCH, PUBLISH, XADD, XREADGROUP, XACK, EVAL, EVALSHA, FCALL, WAIT and blocking commands such as BLPOP. A command this list does not name is a write as well.
  • These need allow_writes and allow_admin: FLUSHALL, FLUSHDB, SWAPDB, SHUTDOWN, DEBUG, SAVE, BGSAVE, BGREWRITEAOF, REPLICAOF, SLAVEOF, FAILOVER, CLUSTER, MIGRATE, MODULE, ACL (every subcommand except WHOAMI), CONFIG GET|SET|REWRITE|RESETSTAT, SCRIPT FLUSH|KILL, FUNCTION FLUSH|DELETE|RESTORE|KILL.
  • These are refused even with both flags, because they change the connection or they are not available: SELECT (use database), AUTH (use password_env), HELLO (use protocol), MULTI, EXEC and DISCARD (use transaction=true), WATCH, UNWATCH, SUBSCRIBE and the other subscribe commands, MONITOR, QUIT, CLIENT, RESET, READONLY, READWRITE, SYNC, PSYNC, REPLCONF.
  • The reply of a script has value (the last command), values (one entry per command, in order) and rowCount (how many elements the last reply has). A missing key is a successful null, and its rowCount is 0. min_rows counts every element. expect looks only at the elements a script keeps, which is max_rows of them (default 1000). A server error keeps its code word, such as WRONGTYPE or NOPERM. In a pipeline the error names the command by its first word only.
  • One endpoint only. There is no Cluster and no Sentinel. A MOVED or ASK reply is a failed call. SUBSCRIBE is not available yet. WATCH is not available: use a Lua script with allow_writes, or a transaction. A whole reply is read into memory, so KEYS * or a huge LRANGE can use a lot of it. SCAN is the safe way to walk keys. Binary values are not exact in a script: a byte that is not valid text is replaced. A blocking command such as BLPOP needs allow_writes, and the call timeout has to be longer than the block time.
  • The host allowlist and caps apply as for HTTP targets.
Test a RabbitMQ server

The rabbitmq driver speaks AMQP 0-9-1. It publishes and consumes with exchanges, queues, routing keys, acknowledgements and prefetch. A publish with confirms reports how long the broker took to confirm. A roundtrip reports how long the message took to come back, and that time includes declaring the temporary queue. It uses a pure Go client, so there is nothing to install. It is tested with RabbitMQ 3.13 and 4.x. LavinMQ and similar brokers may work. Only RabbitMQ is tested.

The target is amqp://host[:port][/vhost] or amqps:// for TLS. The default ports are 5672 and 5671. -protocol stays rabbitmq. There is no rabbitmq:// scheme. The URL takes no query string, and a password in the URL is refused. The path is the vhost: empty or / means /, /orders means orders, and /%2F means a vhost whose name is /.

# Publish one message and wait for the broker to confirm it.
./vegaload run -target amqp://127.0.0.1:5672 -protocol rabbitmq \
  -opt mode=publish -opt exchange=amq.topic -opt routing_key=vegaload.test \
  -body 'hello' \
  -opt password_env=RABBITMQ_PASSWORD \
  -vus 10 -duration 30s

# Send a message and read that same message back. No queue to set up.
./vegaload run -target amqp://127.0.0.1:5672 -protocol rabbitmq \
  -opt mode=roundtrip -opt exchange=amq.topic -opt routing_key=vegaload.test \
  -body 'hello'

The job options are mode (publish, consume, roundtrip, admin), exchange, routing_key, queue, bind_key, count, confirm, mandatory, persistent, content_type, priority, expiration, headers, ack, prefetch, expect, action, durable, auto_delete, queue_type and exchange_type.

The connection options are username, password_env, vhost, tls (false, true, skip-verify), connection (shared or per_call), channels, heartbeat, connection_name, allow_writes and allow_admin. ca_file, cert_file, key_file and tls_server_name are in TLS with your own CA.

  • Publishing is always allowed. consume with ack=requeue (the default) is always allowed, and it puts the messages back. That is a peek: the broker sets the redelivered flag, the order can change, and a quorum queue counts the delivery. ack=ack removes the messages and needs allow_writes=true. A roundtrip is always allowed, because it uses only a queue it created. queue_info is always allowed. queue_declare, exchange_declare and queue_lifecycle need allow_writes=true. queue_delete, exchange_delete and queue_purge need both allow_writes=true and allow_admin=true. A RabbitMQ user with limited permissions is the real lock.
  • One connection is shared by every user (connection=shared, the default). channels is how many calls may use it at once (default 10, from 1 to 1000). Each call uses one channel and does not take a second while it holds that one. Publish keeps a healthy confirm-mode channel and uses it again. Consume, roundtrip and admin open a channel and close it. connection=per_call dials for that call and closes it after. A dead connection is dialled again by the next call. A call never retries itself.
  • Put the password in an environment variable and pass its name with -opt password_env=NAME. The default user is guest with password guest when you set neither. Any other username needs password_env. The user can also be the user in the URL. Give it in one place. RabbitMQ waits about 3 seconds before it refuses a login, so a call timeout shorter than that reports timed out instead of refused the login.
  • vhost defaults to /. It can also be the path of the URL. Give it in one place.
  • tls=false is the default for amqp://. amqps:// means TLS. true checks the certificate and the host name. With -insecure, true does not check the certificate. skip-verify uses TLS and does not check the certificate. tls=false with amqps:// is an error. TLS is 1.2 or newer.
  • heartbeat defaults to 10s. The range is 1s to 5m, or 0. 0 asks the broker to turn heartbeats off. This client library still accepts the broker's own interval when the broker proposes one, which RabbitMQ does (about 60s), so heartbeats stay on against a real broker.
  • connection_name defaults to vegaload. The broker shows it on the connection.
  • {id} in the body, routing key, bind key or queue name is one value for the whole call. {n} is 1, 2, and so on, once per message. In a queue name or bind key, {n} is 1. Header values are not changed. Every message id is <id>-<n>.
  • count defaults to 1, from 1 to 10000. A publish of more than one message sends them together, and the call time is the whole batch. confirm=true (the default) waits until the broker has confirmed every message. confirm=false returns when the last write is done. mandatory defaults to true when confirms are on, and false when they are off. A message that no queue receives fails the call. The error names the exchange and the routing key. mandatory=true needs confirm=true. A roundtrip always uses mandatory=true.
  • persistent=true asks the broker to write the message to disk (delivery mode 2). The default is 1. expiration is how long the message may live, as a duration such as 5s, sent as milliseconds. priority is 1 to 255. headers is a JSON object of string, number and boolean values.
  • consume needs queue. It checks the queue with a passive declare on its own short-lived channel first, so a missing queue is NOT_FOUND and the connection stays usable. That check is one extra round trip. It then reads count messages. Fewer than count fails when the call times out. expect must match every body. prefetch defaults to count, and at most 1000. It must be at least count, or the broker will not deliver the rest before the final acknowledgement and the call waits until it times out. 0 is refused. ack=requeue puts every message back. ack=ack removes them, and only when every message was read and every expect passed. A timeout or a failed check puts nothing back by hand: closing the channel requeues them.
  • roundtrip declares a temporary exclusive queue, binds it when the exchange is named, publishes, and waits until each of this call's messages comes back. It matches them by message id and ignores any other message. The default exchange needs no binding: the routing key is the temporary queue's name, and routing_key is refused. A named exchange must already exist (amq.topic, amq.direct, amq.fanout, or one you declared). bind_key defaults to routing_key. The temporary queue is deleted when the call ends, including when it fails.
  • admin runs one action. queue_info reports queue=NAME messages=N consumers=N. queue_declare uses durable (default true), auto_delete (default false) and queue_type (classic, quorum, stream, or unset). Declaring stream is allowed. Consuming from a stream queue is not tested. exchange_declare uses exchange_type (direct by default, or fanout or topic). headers is refused. A name that starts with amq. is the broker's. queue_lifecycle needs {id} in the queue name, so it never deletes a queue that was already there. It declares the queue and deletes it.
  • The body may be empty. The most it may be is 16777216 bytes.
  • A call that takes too long says timed out after <duration>. If the broker has blocked the connection, the error says so and includes the broker's reason. A refused login names the user and never the password.
  • One endpoint only. There is no AMQP 1.0 and no RabbitMQ Streams (port 5552). There is no management HTTP API, no shovel, no federation, no basic.get, and no dead-letter or delayed-message setup. An unroutable message fails the call unless you set mandatory=false.
  • The host allowlist and caps apply as for HTTP targets.
Test an FTP server
FTP_PASSWORD=secret ./vegaload run -vus 4 -duration 10s -protocol ftp \
  -target ftp://localhost -opt mode=roundtrip -opt path=/upload/vl-{id}.bin \
  -opt size=1MiB -opt allow_writes=true -opt username=vegaload \
  -opt password_env=FTP_PASSWORD -secret-env FTP_PASSWORD

-target is ftp://host (port 21, or 990 with -opt tls=implicit) or ftps://host (implicit TLS, port 990). A port in the URL always wins. vegaload doctor takes no -opt, so it reads only the URL: it checks port 21 for ftp://host. To check port 990, give it ftps://host or ftp://host:990. Put the password in an environment variable. Do not put it in the URL. With no username and no password_env, the client logs in as anonymous with the password vegaload@. A username other than anonymous needs password_env. tls=explicit on ftp:// is AUTH TLS. tls=none is not allowed with ftps://. -insecure skips certificate checks for a test server.

-opt keys:

Key Default Meaning
mode download connect, download, upload, list, stat, delete, roundtrip
path The file or directory. {id} is replaced in the path and in a body.
size Upload this many bytes (1KiB, 1MiB, up to 4GiB) instead of a body. size=0 is an empty file.
fill random random, zero or text, used with size.
expect_size Download must be exactly this many bytes.
expect_sha256 Download must hash to this SHA-256 (64 hex characters).
expect Text the download must contain, searched in the first 1MiB, or a name the listing must contain.
limit 1000 How many listing entries the reply keeps (1 to 100000).
hidden false For list only: send LIST -a. MLSD already returns names that start with ..
username anonymous Login name.
password_env Environment variable that holds the password.
tls from the URL none, explicit or implicit. With implicit and no port in the URL, the port is 990.
tls_verify true Check the server certificate. -insecure turns this off.
tls_max 1.2 Highest TLS version, 1.2 or 1.3. It is 1.2 because vsftpd 3.0.5 fails large uploads over TLS 1.3 (426 Failure reading network stream). Use 1.3 for a server that needs it.
ca_file, cert_file, key_file, tls_server_name See TLS with your own CA.
sessions 10 How many control connections this run may hold. Match it to -vus. Extra users wait.
connection shared per_call dials a new session and drops it. It still takes one of the sessions slots, so the number in flight stays bounded.
data_host control control dials the data connection to the host you named. announced uses the PASV address, which must be an IP.
epsv auto off uses PASV only.
allow_writes false Required for upload, roundtrip and delete.
allow_admin false Also required for delete, and for an upload whose path has no {id}. Needs allow_writes as well.
  • Transfers are passive and binary. There is no active mode, no ASCII mode, no resume and no recursion. One server per run.
  • connect logs in and does nothing else. download reads one file. upload writes one file. list lists one directory. stat asks for the size. delete removes one file. roundtrip uploads, downloads, checks the bytes and deletes that file. It needs {id} in the path, so it never removes a file that was already there.
  • sessions is how many control connections the run may hold at once. Set it to the same number as -vus, or extra users wait for a free session. A session that the server closes is not reused. The next call dials again. There is no hidden retry.
  • {id} in a path or a body becomes a new value on every call. It is not written into the bytes that size generates.
  • An upload without size and without a body is an error. A failed upload can leave a partial file. roundtrip still tries to delete its file. If that delete fails, the call can still pass and the text names the file that is left.
  • The account is the real lock. allow_writes and allow_admin only stop VegaLoad from sending the command. Give the account a scratch directory.
  • A listing skips lines the client cannot parse. limit trims what the reply returns. The client still reads the whole listing first, so a huge directory uses memory for every name. Many servers expand a wildcard in a list path. hidden changes LIST only.
  • data_host=control ignores the address in the PASV reply and dials the host from -target. Use that when the server is behind NAT and announces an address the client cannot reach. data_host=announced dials the announced IP. A firewall must allow the passive port range.
  • The timeout covers the whole call, including the transfer. A call that takes too long says timed out after <duration>. Throughput in the report is the bytes of the call divided by the time the call took.
  • A script's ftp reply has entries (each name, type, size and time), size, total, timing (connectMs, loginMs, transferMs, uploadMs, downloadMs, deleteMs) and text. time is UTC, such as 2020-01-02T15:04:05Z, or "" when the server gave none. Give the password as password: env.FTP_PASSWORD.
  • The host allowlist and caps apply as for HTTP targets.
TLS with your own CA

These four options are the same for Redis, RabbitMQ, FTP, MySQL, PostgreSQL, HTTPS (http1 and http2), WebSocket (wss), gRPC (grpcs), MQTT (mqtts), Kafka (kafkas) and TCP with tls=true. Pass them with -opt, or in a scenario options object. They are not separate flags. Plain http, ws, grpc, mqtt, kafka and UDP reject them, because TLS is off.

Key Meaning
ca_file A PEM file with one or more CA certificates. These are the only CAs that are trusted. The system roots are not used. To trust the system roots as well, put them in this file too.
cert_file A PEM client certificate. Put intermediates after it.
key_file The PEM private key for cert_file.
tls_server_name The name to send as SNI and to check on the certificate. Use it when you connect by IP, or by a name that is not on the certificate.

cert_file and key_file go together. One without the other is an error. With both, the client certificate is sent when the server asks for it.

ca_file cannot be combined with -insecure, tls=skip-verify, or tls_verify=false. Those modes do not check the certificate. cert_file and key_file are allowed with them. PostgreSQL sslmode=prefer and sslmode=require also skip the check, so ca_file with either of them is an error: it needs sslmode=verify-full.

If TLS is off, any of the four is an error. The files are read when the client is built, not on every call.

An encrypted private key is refused. PKCS#12 and JKS are not read. CRLs and OCSP are not checked. A certificate is not pinned by fingerprint. FTP still defaults to TLS 1.2 (tls_max).

# A private CA, connecting by IP. The certificate is for redis.internal.example.
./vegaload run -target rediss://10.0.0.5:6379 -protocol redis \
  -body PING \
  -opt ca_file=./certs/ca.pem \
  -opt tls_server_name=redis.internal.example

# Mutual TLS. The server asks for the client certificate.
./vegaload run -target amqps://10.0.0.8:5671 -protocol rabbitmq \
  -opt mode=publish -opt mandatory=false \
  -body hello \
  -opt ca_file=./certs/ca.pem \
  -opt cert_file=./certs/client.pem \
  -opt key_file=./certs/client.key \
  -opt tls_server_name=rabbit.internal.example

A scenario passes the same keys, for example ca_file: "certs/ca.pem".

2. Or write a scenario file
./vegaload new my-scenario

scaffolds my-scenario.vl.js (JavaScript by default; -python for a .py scenario shelling out to a local python3). A scenario's http and ws globals make real HTTP and WebSocket calls, carrying a value from one into the next — a script can create something over HTTP, then open a WebSocket and read frames until it's done, the way examples/scenarios/http-ws-chain.vl.js does against the sample app (its Python twin, http_ws_chain.py, does the same thing):

./vegaload run -vus 5 -duration 10s examples/scenarios/http-ws-chain.vl.js

(flags before the scenario file — vegaload's flag parser stops at the first non-flag argument; run vegaload run -h for the full flag list.) A host outside localhost needs -allow-target or -yes — the same FR-CLI-06 allowlist protocol-direct mode's -target uses, just enforced per call since a script's own targets aren't known until it runs. A scenario with no network calls at all is still useful for pure per-iteration logic against VegaLoad's VU pool and executor shapes (fixed-VU, ramp, step, constant-arrival-rate) — examples/scenarios/smoke.vl.js is a minimal one:

./vegaload run -vus 5 -duration 5s examples/scenarios/smoke.vl.js

To load test an actual HTTP target without writing a script at all, use protocol-direct mode (step 1) instead — or generate a runbook of protocol-direct commands from an OpenAPI spec:

./vegaload new -from-openapi examples/sample-app/openapi.json sample-app

writes two files. sample-app.vl.js is a runnable scenario that calls every operation of the spec once per iteration, each as a named step (add -python for a Python scenario; flags go before the name). It sends the example bodies and required query parameters from the spec, reads a credential from env (give it with -secret-env), and uses the id that a create returns in the calls under it. A spec describes each endpoint on its own, so the order (creates, reads, updates, deletes) is a guess: the file says so, and marks the ids and other values it could not fill. Check it with vegaload validate and edit it to fit your real flow. sample-app.vegaload-plan.md is a runbook with one ready-to-run vegaload run command per endpoint, for loading one endpoint at a time.

Call TCP, UDP, MQTT, Kafka, gRPC, PostgreSQL, MySQL, Redis, RabbitMQ and FTP from a scenario

A JavaScript scenario can also use the tcp, udp, mqtt, kafka, grpc, postgres, mysql, redis, rabbitmq and ftp globals. Each function is one call that does one job and returns what it read:

export default function () {
  const r = tcp.send("tcp://localhost:6379", { body: "PING\r\n", until: "\r\n" });
  check(r, { "got PONG": (x) => x.ok && x.body === "+PONG\r\n" });

  mqtt.publish("mqtt://localhost", { topic: "sensors/1", body: "21.5", qos: 1 });
  const m = mqtt.subscribe("mqtt://localhost", { topic: "sensors/#", count: 2, timeout: "5s" });
  console.log(m.messages.map((x) => x.topic + "=" + x.body).join(", "));
}
  • tcp.send(url, options) and udp.send(url, options): the options are the same as the -opt keys in the TCP and UDP sections above (until, read, expect, tls, reply, and so on), plus body. The reply is r.body. A script's text is sent as written: backslash escapes are off unless you pass escape: true.
  • mqtt.publish, mqtt.subscribe and mqtt.roundtrip take topic, body and the other MQTT -opt keys (not mode: the function sets it). The messages that were read are in r.messages, each with topic and body. Give a password as password: env.MQTT_PASSWORD and run with -secret-env MQTT_PASSWORD, so it is removed from every output.
  • kafka.produce, kafka.consume, kafka.roundtrip and kafka.admin take the Kafka -opt keys (topic, key, count, expect, from, action, sasl, username, acks, and so on; not mode) plus value (the record value, body means the same). The records are in r.records, each with topic, partition, offset, key and value. For produce, the partition and offset say where the broker stored the record. An admin answer is in r.text. A Kafka client is made on the first call and kept for the rest of that virtual user's run, so produce does not connect again for every call. consume and roundtrip read with their own connection, as in the load-test mode. A SASL password is password: env.NAME. The safety allowlist checks the first broker you name, not the other brokers the cluster announces. The kept client stops at the longest timeout it was built with (the first call's timeout, and at least one minute), so a single Kafka call cannot run longer than that.
  • grpc.call(url, options) makes one unary gRPC call. The options are method (required, such as "/package.Service/Method"), body (an object, or JSON text; leave it out for an empty message) and headers (an object, sent as gRPC metadata). The reply has status (the gRPC code, 0 when it worked), statusName (such as "NotFound"), body (the reply as JSON text) and json (the same, already parsed). The script needs no .proto file: the first call to a method asks the server for its message types (server reflection), and the answer is kept. A JSON body needs the server to offer reflection. Sent to a server without it, the call throws. Call such a server with encoding: "base64": body and the reply are then the encoded message in base64. A server's error status is a reply with ok false, not an exception. Only unary methods work for now. url is host:port, grpc://host:port or grpcs://host:port for TLS. grpcs:// takes the four options under "TLS with your own CA". One connection is made on the first call and kept for the rest of that virtual user's run.
  • postgres.query(url, options) runs one SQL text, given as body, and takes the other PostgreSQL -opt keys (username, database, sslmode, args, min_rows, expect, max_rows, query_mode, allow_writes, pool). args is a list: args: [42, "paid"]. The reply has rows (a list of objects, one per row, keyed by column name, up to max_rows), columns (the names, in order), rowCount (all the rows, also those past max_rows), rowsAffected and commandTag (such as "SELECT 2"). Numbers, text, booleans and NULL (null) keep their type, and JSON columns are parsed. Times are text in UTC (RFC 3339), and numeric, uuid and byte columns are text, so no precision is lost. If two columns have the same name, the last one wins: give them different names with as. Give the password as password: env.DB_PASSWORD and run with -secret-env DB_PASSWORD. A pool with one connection is made on the first call and kept for the rest of that virtual user's run, so each call does not connect again. A server error (a bad SQL, a failed constraint) is a reply with ok false and the SQLSTATE code in error, not an exception. Scripts are read-only like the command line: a script that writes passes allow_writes: true.
  • mysql.query(url, options) runs one SQL text, given as body, and takes the other MySQL -opt keys (username, database, tls, args, min_rows, expect, max_rows, query_mode, allow_writes, pool). Placeholders are ?, and args is a list: args: [42, "paid"]. The reply has rows, columns, rowCount and rowsAffected, the same as PostgreSQL, plus lastInsertId for a single insert. It has no commandTag. A text of several statements reports rowsAffected as 0. Give the password as password: env.DB_PASSWORD and run with -secret-env DB_PASSWORD. A pool with one connection is made on the first call and kept for the rest of that virtual user's run. A server error is a reply with ok false, and the error number and SQLSTATE are in error. Scripts are read-only like the command line: a script that writes passes allow_writes: true. url may be mysql:// or mariadb://.
  • redis.command(url, options) runs one Redis command, given as body, or several, one per line. It takes the other Redis -opt keys (username, database, tls, pool, protocol, allow_writes, allow_admin, transaction, args, min_rows, expect, max_rows). args is a list: args: ["user:42", "ann"]. A ? is one whole argument. The reply has value (the last command), values (one entry per command) and rowCount. In Python, r.values is that list (and r["values"] is the same). It has no rows, columns, rowsAffected, commandTag or lastInsertId. Give the password as password: env.REDIS_PASSWORD and run with -secret-env REDIS_PASSWORD. A client with one connection is made on the first call and kept for the rest of that virtual user's run. A server error, and a command the read-only check refuses, is a reply with ok false, not an exception. A script that writes passes allow_writes: true in the connection options. Admin commands also pass allow_admin: true. url may be redis:// or rediss://.
  • rabbitmq.publish, rabbitmq.consume, rabbitmq.roundtrip and rabbitmq.admin take the RabbitMQ -opt keys (not mode: the function sets it) plus body. The messages that were read are in r.messages, each with exchange, routingKey, body, messageId and redelivered. An admin answer is in r.text. Give the password as password: env.RABBITMQ_PASSWORD and run with -secret-env RABBITMQ_PASSWORD. A connection is made on the first call and kept for the rest of that virtual user's run. A server error, and a call the safety check refuses, is a reply with ok false, not an exception. A script that removes messages passes allow_writes: true. Admin actions that delete or purge also pass allow_admin: true. url may be amqp:// or amqps://.
  • ftp.connect, ftp.download, ftp.upload, ftp.list, ftp.stat, ftp.delete and ftp.roundtrip take the FTP -opt keys (not mode: the function sets it) plus body. The names that were read are in r.entries, each with name, type, size and time. r.size is the file size, r.total is how many names the listing had, r.timing is the parts of the call in milliseconds, and r.text is the short answer. Give the password as password: env.FTP_PASSWORD and run with -secret-env FTP_PASSWORD. A session pool is made on the first call and kept for the rest of that virtual user's run. A server error, and a call the safety check refuses, is a reply with ok false, not an exception. A script that writes passes allow_writes: true in the connection options. A delete, or an upload to a fixed path, also passes allow_admin: true. url may be ftp:// or ftps://.
  • Every function also accepts insecure (skip TLS checks) and timeout (milliseconds, or text such as "2s").
  • Every call returns {ok, error, bytesSent, bytesReceived, body, messages}. Kafka calls also return records and text, gRPC calls return status, statusName and json, PostgreSQL calls return rows, columns, rowCount, rowsAffected and commandTag, MySQL calls return rows, columns, rowCount, rowsAffected and lastInsertId, Redis calls return value, values and rowCount, and RabbitMQ calls return messages (each {exchange, routingKey, body, messageId, redelivered}) and text, and FTP calls return entries (each {name, type, size, time}), size, total, timing and text. A network failure does not throw: ok is false and error says why. A call that is set up wrongly (an unknown option, a missing topic) does throw.
  • The safety allowlist is checked for the host of every call, like http.
  • Each call opens its own connection and closes it, like the load-test mode. For mqtt.subscribe, the message must arrive during the call, so run it when something else publishes.

Python scenarios have the same globals, with the same options and the same reply. The options are keyword arguments, the reply works as r.ok and as r["ok"], and a word that Python reserves gets a trailing underscore (from_="end"):

def iteration():
    r = tcp.send("tcp://localhost:6379", body="PING\r\n", until="\r\n")
    check(r, {"got PONG": lambda x: x.ok and x.body == "+PONG\r\n"})
    k = kafka.produce("kafka://localhost", topic="orders", key="k1", value="v")
    print(k.records[0].partition, k.records[0].offset)
    g = grpc.call("localhost:50051", method="/pkg.Greeter/SayHello", body={"name": "x"})
    check(g, {"greeted": lambda x: x.ok and x.json.message == "Hello x"})

grpc.call sends and reads JSON, which needs server reflection on the server. Without it, the call throws. For such a server use encoding="base64", and send the encoded message in base64.

A call set up wrongly raises VegaloadError.

examples/scenarios/mqtt-tcp.vl.js (and its Python twin, mqtt_tcp.py) is a small example, and examples/scenarios/kafka-orders.vl.js shows Kafka, and examples/scenarios/mixed-protocols.vl.js (Python: mixed_protocols.py) mixes HTTP, gRPC and WebSocket in one flow, and examples/scenarios/postgres-orders.vl.js (Python: postgres_orders.py) writes and reads rows in PostgreSQL, and examples/scenarios/mysql-orders.vl.js (Python: mysql_orders.py) reads and writes a MySQL row. examples/scenarios/redis-cache.vl.js (Python: redis_cache.py) reads a cache key, fills it on a miss, and updates a counter.

Start from a browser recording

Record a real session in your browser (the network tab can save it as a HAR file), then turn it into a scenario:

./vegaload import har recording.har -o checkout.vl.js
./vegaload validate -secret-env VL_COOKIE checkout.vl.js

The importer makes a first draft, and you edit it. It keeps the real calls, in the order they were recorded, one http call each, with a check on the status the browser got. It leaves out images, fonts, style sheets and scripts, requests to other sites (analytics, ads, CDNs), CORS preflight requests, and requests that failed. "Other sites" means sites other than the one of the first page you opened in the recording. Use -include-static, -include-third-party or -host to change that, and -max N to stop after N requests.

The importer keeps the secrets it can recognise out of the file as env.VL_NAME. You pass each one by name with -secret-env. That covers a password, an API key, a session id, and any header, query parameter or body field whose name looks secret. A Cookie or Authorization header is a secret when an earlier response on the same host did not set that cookie or return that bearer token. A CSRF token or a view state is not a secret: the notes below say when the scenario reads it from a response. A value with an ordinary name stays as it was recorded, including a token in a path such as /reset/<token>, a query parameter named code, or a field named key. Read the file before you share it, and do not commit the HAR file. The importer also drops headers a client sets by itself (User-Agent, Content-Length, Referer, Origin, Sec-* and similar).

Some things are left for you, and the file marks them with TODO lines:

  • A value that looks like it changes on every run (a UUID, a long number, a token), when the nearest earlier response on the same host does not hold it in a named place. When it does, the scenario reads it from that response: a JSON field, then a response header, then a Set-Cookie, then an input found by name or id. Two places of the same kind, including two JSON fields, stay in the file with a TODO, and an older response is not used. A password or an API key stays in the environment even if a response echoes it. A CSRF token or a view state is carried when the page returned it, and stays in the file with a TODO when it did not.
  • A multipart body. It is left out.
  • Waits between requests. A scenario has no sleep and no cookie jar. A cookie an earlier response set is carried. Any other cookie is a secret. In a script, Set-Cookie is every cookie the response set, separated by newlines, so a date in Expires stays intact.

The hosts in the file are real. A host that is not localhost needs -allow-target on the run, and the file's first lines say which.

Check a scenario before a real run
./vegaload validate examples/scenarios/crud-flow.vl.js

validate runs the scenario once, with one user and one iteration, and says whether it works. It catches a script that will not load (a syntax error, a missing file, no iteration() in Python) and an iteration that fails (a wrong URL, a thrown error, a host that is not allowed). It makes real network calls, under the same host rules as run, so a host that is not localhost needs -allow-target or -yes. Any check() results are listed, and a failed check does not make the scenario invalid. Add -output json for a machine-readable result.

Exit code Meaning
0 The scenario loaded and its iteration ran
1 The scenario is not valid
2 Bad usage

From an agent, the validate_scenario tool does the same and returns valid, and for an invalid scenario the stage (load or iteration) and error.

Feed a scenario data and settings

A scenario can read rows from a file and settings from the environment, so each virtual user can act on different data.

API_KEY=demo-key ./vegaload run -vus 5 -duration 30s \
  -data users.csv -env REGION -secret-env API_KEY scenario.vl.js
  • -data FILE is a CSV file (the first line names the columns) or a JSON file (an array of objects). The script reads it as data.NAME, where NAME is the file name without its extension: users.csv is data.users. Give another name with -data name=path. The flag can be repeated. data.users.next() takes the next row in file order, shared by all users, and starts again after the last row. data.users.random() takes any row. data.users.length is the number of rows. CSV values are strings. JSON values keep their types. In Python, use len(data.users).
  • -env NAME lets the script read the environment variable NAME as env.NAME. A script can only read the variables you name. It cannot see the rest of your environment. A variable that is not set is a usage error (exit 2), before any load is sent.
  • -secret-env NAME is the same, and the value is a secret. It is taken out of the summary, the JSON output, the HTML report, the audit log and console.log output. Use it for tokens and passwords.
const row = data.users.next();
http.post(url, { body: JSON.stringify({ user: row.name }),
                 headers: { Authorization: "Bearer " + env.API_TOKEN } });
row = data.users.next()
http.post(url, body=json.dumps({"user": row["name"]}),
          headers={"Authorization": "Bearer " + env.API_TOKEN})

Secrets are removed by matching the value in text VegaLoad writes: check names, error messages, the audit log and console output. A script that changes a secret first, for example by encoding it, can still show the changed text. Python scenarios are ordinary Python programs, so they can also read the whole process environment through os.environ; only the env object is limited to the names you give. validate takes the same flags as run. From an agent, run_test and validate_scenario take data_files, env and secret_env. See examples/scenarios/data-env.vl.js.

3. Explain a run's results

Keep a run's JSON summary alongside its HTML report with -out:

./vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -vus 10 -duration 30s -out baseline.json
./vegaload diagnose baseline.json

diagnose reports the failure rate, flags a latency long tail (p99 more than 5x p50), and says whether failures were concentrated in one period or spread out — plus suggested pass/fail thresholds (a p95 ceiling, an error rate ceiling) derived from that same run, for writing into a CI gate. Add a bring-your-own-LLM connector for a plain-English narrative on top of the rule-based findings:

export VEGALOAD_LLM_PROVIDER=openai       # or anthropic, ollama
export VEGALOAD_LLM_API_KEY=sk-...
./vegaload diagnose baseline.json

Nothing about a run or its results leaves your machine unless you configure this yourself (-no-llm skips narration even if it's configured).

4. Compare a later run against the baseline

After another run with -out candidate.json:

./vegaload compare baseline.json candidate.json

Prints deltas (error rate, latency percentiles, totals, overall RPS) and exits non-zero if error rate or p95 latency got worse. If the scenario makes check() calls, it also lists each check's pass rate in both runs, and a check whose pass rate fell counts as a regression too. A check that only one run made is shown as new or removed, and does not fail the comparison. The check_rate row is the plain average of the shared checks. It is for reading and never fails the comparison on its own. Optional slack:

./vegaload compare -error-rate-delta 0.01 -p95-ratio 1.2 -check-rate-delta 0.02 \
  baseline.json candidate.json

Checked-in fixtures under examples/scenarios/compare/ show an ok and a regressed pair, with and without checks, without needing a live target.

Or do it in one command, with the baseline as a file you keep:

./vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -vus 10 -duration 30s -baseline baseline.json -max-regression 10

The run exits 3 if p95 latency, or the error rate, is worse than the baseline by more than 10 percent. It uses the same comparison as vegaload compare. The error rate may rise by that percent of the baseline's error rate, so a baseline with no errors allows none. Use a -threshold "error_rate < 1%" for an absolute limit. The -baseline gate does not look at checks; use -threshold "check_rate >= 99%" for those. Without -max-regression, any increase fails. VegaLoad keeps no baseline store. The baseline is a file you supply, from -out. The summary, JSON, HTML report and audit log show the verdict. From an agent, run_test takes baseline_path and max_regression.

Gate a run on pass/fail thresholds

Add -threshold to make a run pass or fail on its own numbers, for example in CI:

./vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -vus 10 -duration 30s \
  -threshold "p95 < 300ms" \
  -threshold "api stays up: error_rate < 1%"

Each threshold is an optional name:, a metric, an operator (<, <=, >, >=) and a value. The metrics are p50, p90, p95, p99, mean, min, max (durations such as 300ms), error_rate (a fraction like 0.01 or a percentage like 1%), rps, failed, total and check_rate (the share of check() calls that passed; see below). A threshold can target one named step: p95{step="login"} < 300ms (see Steps below; check_rate cannot). Every threshold is judged once, on the finished run. A run that completed no requests fails all of them.

The text summary, the JSON output, the HTML report and the audit log all show each threshold's verdict. The exit code tells a script what happened:

Exit code Meaning
0 The run finished and every threshold passed (or none set)
1 The run itself failed
2 Bad usage, such as a threshold that cannot be parsed
3 The run finished but broke at least one threshold
Stop early on a breach

Add -abort-on-breach and the run stops as soon as a threshold is broken beyond recovery. It exits 3, like any breach, and saves the time and load of a run that has already failed. The summary, JSON, HTML report and GitHub job summary say that the run was aborted, at what time, and by which threshold.

vegaload run -vus 50 -duration 10m -abort-on-breach \
  -threshold "failed < 20" -threshold "p95 < 300ms" -threshold "error_rate < 1%" scenario.vl.js

Two kinds of threshold are judged while the run goes on:

  • A threshold that cannot recover, such as failed < 20, max < 2s or total < 5000, stops the run at once.
  • A statistic that moves up and down, such as p95, error_rate, mean or check_rate (also for one step), stops the run only if it stays broken for three seconds in a row. It is not judged during a warm-up (5 seconds, or a quarter of the run if that is shorter; change it with -abort-grace; -abort-grace 0 turns it off), and not until it has at least 20 samples.

A threshold that needs the whole run, such as rps >= 100 or total >= 1000, is judged at the end, on what ran before the stop. The run tells you which ones before it starts. -abort-on-breach needs at least one threshold. From an agent, run_test takes abort_on_breach and abort_grace.

Checks

In a scenario script, check(value, {name: test}) counts named assertions without failing the iteration. Each test is a function or a boolean; a test that throws counts as failed. check returns true only if all tests passed.

check(res, { "status is 200": (r) => r.status === 200 });

In Python the tests are callables or bools, and a test that raises counts as failed. The summary, JSON, and HTML report list each check's passes and fails. Gate on them with -threshold "check_rate >= 99%". A run with no checks fails that threshold. Use fixed check names. A run keeps at most 100 distinct names; any more are counted together as (other checks). See examples/scenarios/checks.vl.js.

Steps

Name the stages of a flow with step(name, fn) and the summary, the JSON output, the HTML report and the GitHub step summary show the latency and error rate of each one, so you can see which stage is slow.

const token = step("login", () => http.post(base + "/login", { body }).json().token);
step("checkout", () => { /* ... */ });

In Python, with step("login"): times a block, and step("login", fn) runs a function and returns its value. A step that throws (or raises) is a failed step, and the error carries on, so the iteration fails too. Steps can nest; each is counted on its own. Gate on one step with a selector: -threshold 'p95{step="login"} < 300ms'. A step that never ran fails its threshold. Step names with a quote mark in them cannot be targeted. A run keeps at most 100 distinct step names; any more are counted together as (other steps). See examples/scenarios/crud-flow.vl.js.

JUnit XML for CI

-junit results.xml also writes the verdicts as JUnit XML, so a CI system can show them as test results. Each threshold, each check and the baseline gate is one test case. A failed threshold, a check that failed even once, or a baseline the run is worse than is a failed test case. A failed check does not change the exit code of vegaload run, but it does show as a failed test case, because the report says what happened and the exit code is the gate. A run with none of these writes an empty suite.

Thresholds can also come from a file, with -thresholds gate.json. The file is a JSON list of {"name", "metric", "operator", "value"}, or the output of vegaload diagnose -output json, so a baseline run can set the bar for the next ones:

./vegaload diagnose -no-llm -output json baseline.json > gate.json
./vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -vus 10 -duration 30s -thresholds gate.json

diagnose also prints the same suggestion as ready-to-paste -threshold flags. From an agent, run_test takes a thresholds list; a breach comes back as a normal result with thresholds_passed: false.

5. Hand all of this to an agent
./vegaload init

writes six files into the current project, each skippable if already present: two Claude Code skills (.claude/skills/vegaload for real load tests and .claude/skills/vegaload-smoke for a quick ten-second check), two Cursor rules files (.cursor/rules/vegaload.mdc and .cursor/rules/vegaload-smoke.mdc), and an MCP server entry merged into both .mcp.json and .cursor/mcp.json, pointing at this same compiled binary running vegaload mcp serve. Open the project in Claude Code or Cursor afterward and the agent has eight tools — create_scenario, run_test, get_results, suggest_thresholds, diagnose_failure, compare_reports, generate_from_spec, validate_scenario — each one calling the exact CLI command shown above and parsing its -output json result; there is no agent-only path that skips the CLI.

To set up only one editor, use -editor:

./vegaload init -editor cursor
./vegaload init -editor claude-code,cursor

To see what is set up, without changing anything, use -status:

./vegaload init -status

It lists each file as ok, missing, outdated (the rules file differs from the one this binary ships), other binary (the MCP entry points to another copy of vegaload), wrong args (the MCP entry does not run mcp serve) or invalid (the file cannot be read). It exits 1 if anything is not ok, so a script can check it. Run vegaload init -force to fix what it reports.

By default the MCP server talks over stdio. To use it over the network (for example from a container), run it over HTTP:

vegaload mcp serve -http 127.0.0.1:8765

POST /mcp takes one JSON-RPC message and returns the answer. GET /sse opens a Server-Sent Events stream (MCP protocol 2024-11-05) and POST /message sends requests to it. On a loopback address no token is needed. On any other address a token is required: put it in an environment variable and pass its name, for example -token-env VEGALOAD_MCP_TOKEN. Clients then send Authorization: Bearer <token>. Browser requests are refused unless their Origin is a loopback host or the one given with -allow-origin. HTTP is off by default, and stays off in the Docker image unless you pass -http.

vegaload mcp eval runs a versioned, non-LLM suite of {tool call, expected outcome} cases against those same tools directly — the thing to run in CI after upgrading, to check the tool layer itself still behaves, independent of any model's tool-picking behavior:

./vegaload mcp eval

There are two suites. v1 is the default and never changes. v2 keeps every v1 case and adds cases for validate_scenario, the baseline gate, JUnit output and checks. Run it with ./vegaload mcp eval -suite v2.

5. Check that everything is wired up
./vegaload doctor

checks that VegaLoad works from here and says how to fix anything that does not. It looks at the CLI itself (version, PATH, writable folders), at each agent host it finds (Cursor, Claude Code, and Claude Desktop on macOS), and optionally at a target. For a host that is installed but has no VegaLoad MCP entry, that is a warning, not a failure — using the CLI alone is healthy. When VegaLoad is registered, doctor starts the configured server, performs a real MCP handshake, and expects all eight tools. An installed editor with no VegaLoad setup does not fail the command.

./vegaload doctor -target http://localhost:8080   # also check a target
./vegaload doctor -fix                            # repair what can be repaired safely
./vegaload doctor -fix -dry-run                   # show what -fix would change
./vegaload doctor -output json                    # for CI; exits 1 if any check fails

-fix only adds missing MCP entries and rules files in the project, and rewrites a stale server command. It never overwrites a rules file you edited, and it changes files in your home directory only when you name the host, as in -host cursor. -smoke adds a one-user, one-second test against -target (it sends real traffic, so it is off by default). -harness is a placeholder until --move-to-harness ships: it makes no network call and cannot verify credentials.

See examples/scenarios/README.md for this same walkthrough as a standalone, copy-pasteable script.

Command reference

Command What it does
vegaload run Run a load test: a scenario file, or a protocol-direct target
vegaload validate Run a scenario once, with one user, to check that it works
vegaload new Scaffold a starter scenario file, or a runbook from an OpenAPI spec
vegaload import har Make a scenario file from a browser recording (a HAR file)
vegaload diagnose Print environment info, or explain a report's results
vegaload mcp serve Run an MCP server over stdio (or -http addr) for agent-native use
vegaload mcp eval Run the versioned MCP tool-calling eval suite against this binary
vegaload init Register the MCP server and skill bundles (-editor, -status)
vegaload doctor Check the CLI, agent hosts, and a target; -fix repairs what it can

Every command supports -output text (default), json, or (run only) jsonl. Run vegaload <command> -h for its full flag list, or vegaload help for the top-level summary.

Use in Kubernetes

A Helm chart in charts/vegaload runs a load test as a Kubernetes Job, close to the service you are testing. It needs no CRD and no cluster-wide permissions, only access to one namespace. It uses the published image ghcr.io/vegaload/vegaload (from v0.5.0):

helm install smoke ./charts/vegaload --namespace perf \
  --set run.target=http://orders.shop.svc:8080/health --set run.protocol=http1 \
  --set run.vus=5 --set run.duration=30s --set 'run.thresholds={p95 < 300ms}' \
  --wait --wait-for-jobs
kubectl logs -n perf job/smoke-vegaload-1

From v0.7.0, you can install the chart without a clone: helm install smoke oci://ghcr.io/vegaload/charts/vegaload --version <version> ....

A scenario file works too: --set-file scenario=./checkout.vl.js. A broken threshold fails the Job. See the chart's README. For plain kubectl, use examples/k8s/job.yaml.

Use in GitHub Actions

This repository is also a GitHub Action. It installs a released VegaLoad (Linux and macOS runners) and runs it, and the step fails when vegaload exits with a non-zero code. With -threshold, that means a broken threshold fails the build:

- uses: vegaload/vegaload@v0.3.0
  with:
    args: >-
      run -target https://staging.example.com/health -protocol http1
      -vus 20 -duration 1m -allow-target staging.example.com
      -threshold "p95 < 300ms" -threshold "error_rate < 1%"

Inside GitHub Actions, vegaload run also appends a summary to the job's page: the key numbers, and the verdict of each threshold, check and baseline gate. It does this on its own, because GitHub sets GITHUB_STEP_SUMMARY. Pass -no-step-summary to turn it off. Add -junit to write JUnit XML as well, which many CI systems show as test results:

- uses: vegaload/vegaload@v0.3.0
  with:
    args: >-
      run -target https://staging.example.com/health -protocol http1
      -vus 20 -duration 1m -allow-target staging.example.com
      -threshold "p95 < 300ms" -junit vegaload-junit.xml
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: vegaload-junit
    path: vegaload-junit.xml
  • args is what you would type after vegaload, with the same quoting. Leave it out to only install, then call vegaload in later steps.
  • The action installs the version you pin after the @. Set version: to install a different one. A branch name such as @main installs the latest release.
  • The archive is checked against the release's checksums.txt before it is used. Nothing is sent anywhere except the downloads from the GitHub release.
  • The step's version output is the installed version.

License

Apache-2.0. See LICENSE.

Directories

Path Synopsis
cmd
vegaload command
doctor.go implements `vegaload doctor`: it checks that VegaLoad is set up and working on this machine, for the CLI alone and for each agent host (Cursor, Claude Code, Claude Desktop).
doctor.go implements `vegaload doctor`: it checks that VegaLoad is set up and working on this machine, for the CLI alone and for each agent host (Cursor, Claude Code, Claude Desktop).
internal
audit
Package audit implements FR-CLI-07: an audit record of every run — trigger source, target, parameters, and timestamp — appended to a local, append-only JSONL file.
Package audit implements FR-CLI-07: an audit record of every run — trigger source, target, parameters, and timestamp — appended to a local, append-only JSONL file.
compare
Package compare diffs two report.Result values (typically JSON from `vegaload run -out`) so a later run can be checked against a baseline without a baseline registry or history store — just two files.
Package compare diffs two report.Result values (typically JSON from `vegaload run -out`) so a later run can be checked against a baseline without a baseline registry or history store — just two files.
diagnose
Package diagnose implements the rule-based half of FR-MCP-05's diagnose_failure / vegaload diagnose: a set of fixed heuristics over a report.Result that flag the failure patterns a human reviewing a load test would look for first, plus a pure-arithmetic threshold suggester.
Package diagnose implements the rule-based half of FR-MCP-05's diagnose_failure / vegaload diagnose: a set of fixed heuristics over a report.Result that flag the failure patterns a human reviewing a load test would look for first, plus a pure-arithmetic threshold suggester.
doctor
Package doctor implements `vegaload doctor`: a set of small, independent checks that answer "will VegaLoad work from here?" for the CLI, for each agent host (Cursor, Claude Code, Claude Desktop), and for a target.
Package doctor implements `vegaload doctor`: a set of small, independent checks that answer "will VegaLoad work from here?" for the CLI, for each agent host (Cursor, Claude Code, Claude Desktop), and for a target.
engine
Package engine implements VegaLoad's core execution engine: the virtual user (VU) scheduler and the load-shape executors that decide how many VUs run, and when, over the life of a scenario.
Package engine implements VegaLoad's core execution engine: the virtual user (VU) scheduler and the load-shape executors that decide how many VUs run, and when, over the life of a scenario.
eval
Package eval implements FR-MCP-04's versioned MCP tool-calling evaluation suite: a fixed set of {tool, arguments, expected outcome} cases, embedded into the binary and versioned by directory (v1, and any v2+ added later without touching v1's cases) so a suite someone has pinned to doesn't silently change underneath them.
Package eval implements FR-MCP-04's versioned MCP tool-calling evaluation suite: a fixed set of {tool, arguments, expected outcome} cases, embedded into the binary and versioned by directory (v1, and any v2+ added later without touching v1's cases) so a suite someone has pinned to doesn't silently change underneath them.
har
Package har turns a HAR file (the recording a browser's network tab can save) into a VegaLoad JavaScript scenario.
Package har turns a HAR file (the recording a browser's network tab can save) into a VegaLoad JavaScript scenario.
hosts
Package hosts describes the agent hosts VegaLoad integrates with (Cursor, Claude Code, Claude Desktop) in one place: where each host keeps its MCP server config, which rules or skill files it reads, and how to detect that it is installed.
Package hosts describes the agent hosts VegaLoad integrates with (Cursor, Claude Code, Claude Desktop) in one place: where each host keeps its MCP server config, which rules or skill files it reads, and how to detect that it is installed.
inputs
Package inputs gives scenario scripts the data and settings they read from outside the script (FR-CLI-17): data files whose rows feed virtual users, and environment variables the run exposes by name.
Package inputs gives scenario scripts the data and settings they read from outside the script (FR-CLI-17): data files whose rows feed virtual users, and environment variables the run exposes by name.
llm
Package llm implements FR-MCP-05's optional BYO-LLM narrative layer: turning a diagnose.Findings into a short plain-English explanation by calling a user-configured LLM endpoint.
Package llm implements FR-MCP-05's optional BYO-LLM narrative layer: turning a diagnose.Findings into a short plain-English explanation by calling a user-configured LLM endpoint.
mcp
Package mcp implements FR-MCP-01/02/03's agent-native layer: a hand-rolled JSON-RPC 2.0 server speaking the Model Context Protocol over stdio (no third-party SDK — see go.mod's dependency-pinning history for why this project prefers stdlib-only solutions).
Package mcp implements FR-MCP-01/02/03's agent-native layer: a hand-rolled JSON-RPC 2.0 server speaking the Model Context Protocol over stdio (no third-party SDK — see go.mod's dependency-pinning history for why this project prefers stdlib-only solutions).
mcpprobe
Package mcpprobe is a minimal MCP client for health checks.
Package mcpprobe is a minimal MCP client for health checks.
openapi
Package openapi implements FR-MCP-06's `vegaload new --from-openapi` and the generate_from_spec MCP tool: turning an OpenAPI document into a ready-to-run starting point for load testing its endpoints.
Package openapi implements FR-MCP-06's `vegaload new --from-openapi` and the generate_from_spec MCP tool: turning an OpenAPI document into a ready-to-run starting point for load testing its endpoints.
protocol
Package protocol defines the shared interface every wire protocol driver (HTTP/1.1, HTTP/2, gRPC, WebSocket, TCP, UDP) implements, plus the request and result types they exchange with the engine.
Package protocol defines the shared interface every wire protocol driver (HTTP/1.1, HTTP/2, gRPC, WebSocket, TCP, UDP) implements, plus the request and result types they exchange with the engine.
protocol/ftp
Package ftp implements the "ftp" protocol.Protocol driver.
Package ftp implements the "ftp" protocol.Protocol driver.
protocol/ftp/ftptest
Package ftptest is a small FTP server for tests.
Package ftptest is a small FTP server for tests.
protocol/grpc
Package grpc implements a protocol.Protocol driver for gRPC.
Package grpc implements a protocol.Protocol driver for gRPC.
protocol/grpc/grpctest
Package grpctest runs a small in-process gRPC server for tests in other packages.
Package grpctest runs a small in-process gRPC server for tests in other packages.
protocol/http1
Package http1 implements a protocol.Protocol driver that speaks plain HTTP/1.1.
Package http1 implements a protocol.Protocol driver that speaks plain HTTP/1.1.
protocol/http2
Package http2 implements a protocol.Protocol driver that speaks HTTP/2, over TLS (the normal case, negotiated via ALPN) or over plain TCP ("h2c") when the target is an http:// URL — many internal services run h2c precisely to skip TLS termination, and a load tester that only understood h2-over-TLS would be unable to test them at all.
Package http2 implements a protocol.Protocol driver that speaks HTTP/2, over TLS (the normal case, negotiated via ALPN) or over plain TCP ("h2c") when the target is an http:// URL — many internal services run h2c precisely to skip TLS termination, and a load tester that only understood h2-over-TLS would be unable to test them at all.
protocol/kafka
Package kafka implements the "kafka" protocol.Protocol driver, for load testing an Apache Kafka cluster (or any broker that speaks the Kafka protocol).
Package kafka implements the "kafka" protocol.Protocol driver, for load testing an Apache Kafka cluster (or any broker that speaks the Kafka protocol).
protocol/kafka/kafkatest
Package kafkatest is a small fake Kafka broker for tests, so the Kafka driver and the scripting layer can be tested without Docker.
Package kafkatest is a small fake Kafka broker for tests, so the Kafka driver and the scripting layer can be tested without Docker.
protocol/mqtt
Package mqtt implements the "mqtt" protocol.Protocol driver, for load testing an MQTT 3.1.1 broker.
Package mqtt implements the "mqtt" protocol.Protocol driver, for load testing an MQTT 3.1.1 broker.
protocol/mqtt/mqtttest
Package mqtttest is a very small MQTT 3.1.1 broker for tests in other packages, so scripts can be tested without a real broker.
Package mqtttest is a very small MQTT 3.1.1 broker for tests in other packages, so scripts can be tested without a real broker.
protocol/mysql
Package mysql implements the "mysql" protocol.Protocol driver, for load testing a MySQL or MariaDB server (or a database that speaks the same wire protocol, such as TiDB).
Package mysql implements the "mysql" protocol.Protocol driver, for load testing a MySQL or MariaDB server (or a database that speaks the same wire protocol, such as TiDB).
protocol/mysql/mysqltest
Package mysqltest is a small fake MySQL server for tests, in this package and in others.
Package mysqltest is a small fake MySQL server for tests, in this package and in others.
protocol/postgres
Package postgres implements the "postgres" protocol.Protocol driver, for load testing a PostgreSQL server (or a database that speaks its wire protocol, such as CockroachDB, YugabyteDB or Aurora).
Package postgres implements the "postgres" protocol.Protocol driver, for load testing a PostgreSQL server (or a database that speaks its wire protocol, such as CockroachDB, YugabyteDB or Aurora).
protocol/postgres/postgrestest
Package postgrestest is a small fake PostgreSQL server for tests, in this package and in others.
Package postgrestest is a small fake PostgreSQL server for tests, in this package and in others.
protocol/rabbitmq
Package rabbitmq implements the "rabbitmq" protocol.Protocol driver, for load testing a RabbitMQ 3.12 or later broker (and other brokers that speak AMQP 0-9-1).
Package rabbitmq implements the "rabbitmq" protocol.Protocol driver, for load testing a RabbitMQ 3.12 or later broker (and other brokers that speak AMQP 0-9-1).
protocol/rabbitmq/rabbitmqtest
Package rabbitmqtest is a small AMQP 0-9-1 broker for tests.
Package rabbitmqtest is a small AMQP 0-9-1 broker for tests.
protocol/redis
Package redis implements the "redis" protocol.Protocol driver, for load testing a Redis server or a store that speaks the same wire protocol (Valkey, and often KeyDB, Dragonfly and Garnet).
Package redis implements the "redis" protocol.Protocol driver, for load testing a Redis server or a store that speaks the same wire protocol (Valkey, and often KeyDB, Dragonfly and Garnet).
protocol/redis/redistest
Package redistest is a small Redis server for tests.
Package redistest is a small Redis server for tests.
protocol/socket
Package socket implements the "tcp" and "udp" protocol.Protocol drivers: raw sockets, for a service that speaks its own wire protocol (a custom binary protocol, SMTP, Redis, a syslog or DNS port) and has no driver of its own.
Package socket implements the "tcp" and "udp" protocol.Protocol drivers: raw sockets, for a service that speaks its own wire protocol (a custom binary protocol, SMTP, Redis, a syslog or DNS port) and has no driver of its own.
protocol/sqlcommon
Package sqlcommon holds the small pieces the SQL drivers share: reading the args option, and the min_rows and expect checks.
Package sqlcommon holds the small pieces the SQL drivers share: reading the args option, and the min_rows and expect checks.
protocol/websocket
Package websocket implements a protocol.Protocol driver for WebSocket.
Package websocket implements a protocol.Protocol driver for WebSocket.
protocol/xfercommon
Package xfercommon holds helpers for a file transfer that do not know which protocol is moving the bytes.
Package xfercommon holds helpers for a file transfer that do not know which protocol is moving the bytes.
pyfind
Package pyfind finds a Python 3 interpreter.
Package pyfind finds a Python 3 interpreter.
report
Package report implements FR-RPT-01 through 04 and FR-CLI-05: turning a run's recorded iterations into the structured data a self-contained HTML report, a JSON summary, and (eventually) the MCP get_results tool all read from.
Package report implements FR-RPT-01 through 04 and FR-CLI-05: turning a run's recorded iterations into the structured data a self-contained HTML report, a JSON summary, and (eventually) the MCP get_results tool all read from.
safety
Package safety implements FR-CLI-06: a target allowlist plus hard caps on RPS, duration, and concurrency, enforced by default on every run.
Package safety implements FR-CLI-06: a target allowlist plus hard caps on RPS, duration, and concurrency, enforced by default on every run.
scripting/js
Package js runs a scenario written as a JavaScript or TypeScript file, using the embedded Goja ECMAScript runtime — no Node.js, no network fetch of a runtime, and no separate build step for the author.
Package js runs a scenario written as a JavaScript or TypeScript file, using the embedded Goja ECMAScript runtime — no Node.js, no network fetch of a runtime, and no separate build step for the author.
scripting/netapi
Package netapi gives VegaLoad's scripting runtimes (internal/scripting/js and /python) the real HTTP and WebSocket access FR-CLI-08 asks for: a scenario script can make an actual network call and read the response (status, headers, body) back into the script, unlike internal/protocol's drivers, which exist to repeat one fixed Target and discard the response body entirely -- see protocol.Result's doc comment, and http1.Driver.Do, which io.Copy's the body straight to io.Discard.
Package netapi gives VegaLoad's scripting runtimes (internal/scripting/js and /python) the real HTTP and WebSocket access FR-CLI-08 asks for: a scenario script can make an actual network call and read the response (status, headers, body) back into the script, unlike internal/protocol's drivers, which exist to repeat one fixed Target and discard the response body entirely -- see protocol.Result's doc comment, and http1.Driver.Do, which io.Copy's the body straight to io.Discard.
scripting/python
Package python runs a scenario written as a Python file, by shelling out to a python3 interpreter the user has installed separately.
Package python runs a scenario written as a Python file, by shelling out to a python3 interpreter the user has installed separately.
secrets
Package secrets keeps the values a scenario read as secrets (FR-CLI-17) out of everything VegaLoad writes or prints.
Package secrets keeps the values a scenario read as secrets (FR-CLI-17) out of everything VegaLoad writes or prints.
skills
Package skills implements FR-MCP-04's agent skill bundles and the `vegaload init` command built on them: the actual Markdown content Claude Code and Cursor read to know when and how to call VegaLoad's MCP tools, embedded into the compiled binary at build time (via go:embed) so `vegaload init` can write them out without needing the vegaload source tree to be present on the machine it's installed on.
Package skills implements FR-MCP-04's agent skill bundles and the `vegaload init` command built on them: the actual Markdown content Claude Code and Cursor read to know when and how to call VegaLoad's MCP tools, embedded into the compiled binary at build time (via go:embed) so `vegaload init` can write them out without needing the vegaload source tree to be present on the machine it's installed on.
threshold
Package threshold implements FR-CLI-11: pass/fail thresholds on a run's own results, so a run can gate a CI pipeline.
Package threshold implements FR-CLI-11: pass/fail thresholds on a run's own results, so a run can gate a CI pipeline.
tlsconf
Package tlsconf turns the shared TLS file options into a tls.Config.
Package tlsconf turns the shared TLS file options into a tls.Config.
tlsconf/tlstest
Package tlstest builds a short-lived CA, server certificate and client certificate for tests.
Package tlstest builds a short-lived CA, server certificate and client certificate for tests.
urlerr
Package urlerr keeps a password out of an error about a URL.
Package urlerr keeps a password out of an error about a URL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL