Configuration#

A scenario says what to do. Everything about this run — which environment, how big, where the report goes — is configuration, and it comes from three places.

Precedence#

surge.conf  →  SURGE_* environment variables  →  command-line flags

Later wins. A shared file sets the team's defaults, CI overrides a few with environment variables, and a person at a keyboard always wins.

surge.conf#

key = value, one per line. surge looks for surge.conf or .surge.conf beside the scenario, then in each parent directory, then in your home directory, and uses the first it finds — so a repository can set defaults and a sub-project can override them.

# perf/surge.conf
base-url  = https://staging.example.com
vus       = 50
duration  = 5m
threshold = p95 < 500ms
threshold = error_rate < 1%

• Keys are flag names without the dash. base-url and base_url are the same key.
• # and ; start a comment. A [section] header is accepted and ignored, so an existing ini file does not have to be rewritten.
• Values may be quoted; the quotes are stripped.
• A repeated key accumulates. That is how several thresholds fit in a format with one setting per line.
• A line with no = or : is an error naming the file and the line number, not something quietly skipped.

Environment#

Every flag has a SURGE_* variable: SURGE_VUS, SURGE_BASE_URL, SURGE_DURATION, SURGE_TOKEN. The name is the flag in upper case with dashes as underscores.

SURGE_BASE_URL=https://staging.example.com surge run perf/checkout.yaml

This is the layer CI should use: the pipeline knows which environment it is deploying to, and the scenario file in the repository should not.

Inside the scenario#

vars: are scenario-wide values for ${…}, and ${env.NAME} reads the process environment at run time:

vars:
  password: "${env.TEST_PASSWORD}"
  region: eu-west-1

An unknown ${…} is left as written, so a typo shows up in the request rather than becoming an empty string — and surge verify reports it before the run as was never set, so it was sent as that literal text.

Never put a credential in the scenario file. ${env.…} is there so the file can be committed and the secret cannot.

Output files#

Either in the scenario:

output:
  json:     reports/summary.json
  html:     reports/report.html
  csv:      reports/timeline.csv
  failures: reports/failures.csv
  snapshot: reports/raw.json
  no_failure_bodies: false

or as flags of the same name, which override it. no_failure_bodies withholds the response body from the failure log: the body is the most useful thing in a failure and the most likely to hold something private, so it is kept by default and this turns it off for a report that will be passed around.

Paths#

A relative path in a scenario resolves against the scenario file, not against the working directory. surge run perf/shop.yaml finds perf/accounts.csv and perf/scripts/seed.sh from anywhere in the repository. Do not cd first, and do not tell anyone else to.

Choosing what a run is called#

name: is the report title, and it defaults to the filename. It is also the baseline key a regression gate compares against, so changing it starts a new history.