Chapter 5 · Web UI and Headless Mode

Chapter goals: Read the Web UI statistics and charts, master all headless-mode parameters, and save load test results with CSV and HTML reports.

5.1 Web UI Dashboard

After starting locust, visit http://localhost:8089. Core metrics live in the Statistics tab:

Column	Meaning
Type	HTTP method (GET/POST)
Name	Request path (or the grouped name from name= parameter)
# Requests	Total completed requests
# Fails	Failure count (non-2xx HTTP or manual failure)
Median (ms)	Response time median
95%ile / 99%ile	95th / 99th percentile response time
Average (min/max)	Average / min / max response time
Current RPS	Requests per second right now

The Charts tab shows three real-time graphs: Total Requests per Second, Response Times (ms), and Number of Users.

How to tell if the system has hit its bottleneck

When user count keeps increasing but the RPS curve flattens while response time rises sharply — the target system is saturated. If response time is flat and RPS hasn't met the target, you need to push harder.

5.2 Headless Mode: No GUI

CI pipelines have no browser. Use --headless to specify all parameters on the command line:

locust --headless \
    --users 50 \
    --spawn-rate 5 \
    --run-time 2m \
    -H https://httpbin.org

Parameter	Short	Description
--users	-u	Peak concurrent users
--spawn-rate	-r	User spawn rate (new users per second)
--run-time	-t	Run duration (e.g., 30s, 2m, 1h30m)
-H / --host	—	Target host address
--headless	—	Do not start the Web UI

At the end of the run, the final statistics table prints to the terminal:

Type     Name           # reqs   # fails |  Avg   Min   Max  Median |  # reqs/sec
GET      /get              1500      0(0%)|  210   180   890    200 |      12.50
--------- ------------------------------------------------------------------------------
Aggregated                1500      0(0%)|  210   180   890    200 |      12.50

Adjust during headless run

Even in headless mode you can adjust user count in real time via keyboard: w adds 1, W adds 10, s removes 1, S removes 10.

5.3 CSV Output

Add one flag to write full statistics to disk:

locust --headless --users 20 --run-time 1m \
    -H https://httpbin.org \
    --csv results/run_001

Three files are generated automatically:

File	Content
results/run_001_stats.csv	Final statistics table (one row per endpoint)
results/run_001_stats_history.csv	Time-sliced history data (ideal for trend charts)
results/run_001_failures.csv	Details of every failed request

stats_history.csv is the most valuable file — use pandas or Excel to plot the full RPS and response time curves across the entire test:

import pandas as pd

df = pd.read_csv("results/run_001_stats_history.csv")
df.plot(x="Timestamp", y="Current RPS")

5.4 HTML Report

For team presentations, the HTML report is the most intuitive format:

locust --headless --users 50 --run-time 2m \
    -H https://httpbin.org \
    --html report_{u}u_{r}ps.html

Filename placeholders:

• {u} → concurrent user count
• {r} → spawn rate
• {t} → run duration

5.5 Chapter Summary

• Web UI Statistics tab: Type, Name, # Requests, # Fails, Median, 95/99 percentiles, RPS;
• Headless mode: --headless --users N --spawn-rate R --run-time T -H URL;
• --csv generates stats, stats_history, and failures CSV files;
• --html generates a self-contained HTML report with placeholders for filename variables.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does the --csv flag generate?

2. In headless mode, how do you increase users by 10 during a running test?

3. What placeholder inserts the concurrent user count into an --html filename?

4. Which CSV file is best for plotting RPS trend over time?

🛠️ Hands-On Exercises

1. Run a headless test with --users 20 --run-time 1m --csv results/run_001; open the generated CSV files and verify their contents.
2. Generate an HTML report with --html report_{u}u.html; open it in a browser and check the charts.
3. Run the same test twice with different --run-time values (30s vs 2m); compare the stats_history.csv curves.

Proceed to Chapter 6: Assertions and Failure Detection.