Test an HTTP API

VegaLoad speaks HTTP/1.1 (-protocol http1) and HTTP/2 (-protocol http2). Both take http:// and https:// targets.

The examples on this page run against the sample app in the repository. Start it first, in its own terminal:

cd examples/sample-app
go run .

It serves http://127.0.0.1:8080 with GET /health, GET /widgets, GET /widgets/{id} and POST /widgets. Localhost is always allowed. For any other host, see Safety.

One command, no file

Read an endpoint with 5 users for 10 seconds:

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

On a laptop this makes about 600 requests in 3 seconds, with p50 near 25 ms. The sample app adds 10 to 40 ms of delay on purpose.

Send a write with a method, a header and a body:

vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -method POST -header 'Content-Type: application/json' -body '{"name":"bolt"}' \
  -vus 5 -duration 3s -out post.json
vegaload diagnose post.json

The sample app fails about 3% of creates on purpose. The run shows a failure rate near 3%, and diagnose says so.

Flag	What it does
-method	The HTTP verb. The default is GET.
-header "Key: Value"	A request header. Repeat it for more.
-body	The request body.
-timeout	The limit for one iteration. The default is 30 seconds.
-insecure	Skip the TLS certificate check.
-data	Fill {data.NAME.COLUMN} in -body from a CSV or JSON file. See Data files.

HTTP/2

Use -protocol http2:

vegaload run -target http://127.0.0.1:8080/widgets -protocol http2 -vus 5 -duration 3s

The sample app serves HTTP/1.1 and HTTP/2 on one port, with the same handlers. A run with http1 and a run with http2 compare like for like. Any gap is protocol overhead. -method POST works here too.

TLS

For https:// targets, VegaLoad checks the certificate. To trust your own CA, or to send a client certificate, pass ca_file, cert_file, key_file and tls_server_name with -opt. See TLS with your own CA.

Pass or fail limits

Add a threshold to stop a pull request when the API is too slow:

vegaload run -target http://127.0.0.1:8080/widgets -protocol http1 \
  -vus 5 -duration 3s \
  -threshold 'p95{protocol="http1"} < 300ms' -threshold 'error_rate < 1%'

A breach exits with code 3. See Thresholds.

A flow of calls

One URL is not a user session. For a flow, such as create, read back and list, write a scenario. The script has http.get, http.post, http.put, http.patch, http.delete and http.request. A value from one call can go into the next.

crud-flow.vl.js (and its Python twin, crud_flow.py) creates a widget, reads it back by id, and lists all widgets. Each stage is a named step(), so the report shows latency and errors for each one. Run it:

vegaload run -vus 5 -duration 10s crud-flow.vl.js

Flags go before the scenario file. See Scenarios for the full script reference.

Start from what you have

• From an OpenAPI file: vegaload new -from-openapi openapi.json. See the cookbook recipe.
• From a browser recording: vegaload import har. See Start from a browser recording.

Options

vegaload protocols http1 lists the options for the protocol, and the scenario calls it has. HTTP/1.1 and HTTP/2 take ca_file, cert_file, key_file and tls_server_name. They write nothing to the server beyond what your requests send.