skip to content

What does Gatling's --reports-only flag make the process do, and what verdict does that process return?

level: middleimportance: nice to knowfreq 26%

answer

  1. Reports without running anything
  2. No simulation class is needed
  3. Reads an existing results directory
  4. Still re-judges the stored assertions
  5. Exits 0 or 2 on old data

basics

~20 s

Gatling's --reports-only flag rebuilds reports from an existing results directory's stored log. No simulation class is loaded and no traffic is sent, but Gatling re-evaluates the assertions recorded in that log, so it still exits 0 or 2.

solid answer

~40 s

`--reports-only <directoryName>`, short form `-ro`, points Gatling at a results sub-directory that an earlier run already produced. Gatling checks that option **before** it resolves which simulation to run, so it never loads a simulation class, never sends a request, and never runs a `before` or `after` hook — which is why it needs no `--simulation` argument at all. It then reads that run's log file, re-evaluates the assertions the original run recorded in it, regenerates the HTML report, and maps the result to the usual exit code. So it is a re-judgement of an earlier run, not a no-op and not a new test: a job left with `-ro` in it will re-publish yesterday's verdict while generating no load whatsoever.

code

bash · 5 lines
bash
# Rebuild reports and re-judge an existing run; no traffic is generated
java -cp "$CP" io.gatling.app.Gatling \
  --results-folder target/gatling \
  --reports-only checkoutsimulation-20260909120000000
echo "verdict re-computed from the stored log: $?"

go deeper

for a junior

Know that this option rebuilds reports from a results directory an earlier run produced, and that it generates no load. Recognise it in a command line before assuming a test ran.

for a middle

Explain that it is handled before any simulation is resolved, which is why no class is named, and that it still re-evaluates the assertions stored in the log and returns 0 or 2.

for a senior

Spot it as a failure mode: a job left carrying it looks green, produces a fresh report, and exercises nothing. Know that a killed run's buffered log tail makes the regenerated picture partial.

for a principal

Be ready to argue what a pipeline should require as evidence that a run really happened, rather than trusting an exit code that a reports-only invocation can produce just as easily.

`--reports-only`, abbreviated `-ro`, is one of seven options Gatling's shared command-line surface defines, and it is the one most likely to surprise someone reading a job definition. Its declared purpose is *generate the reports for the simulation in `<directoryName>`* — the value is the name of a results sub-directory an earlier run already created, not a class name and not a file. ## What it skips Gatling's run wrapper matches on this option **first**, before anything to do with selecting or instantiating a simulation. In that branch it constructs a run result directly from the directory name you gave it. As a result the entire simulation lifecycle is skipped: - no simulation class is looked up or instantiated; - no `before` or `after` hook runs; - no injection profile executes and no request is sent; - no new results directory is created. This is why the option works with **no simulation named at all**. Everywhere else, the JVM launcher needs to be told which simulation to run; with `-ro` there is nothing to name, because nothing is going to run. ## What it does not skip Here is the part people get wrong. The branch builds its run result with the has-assertions flag hardwired to true, so Gatling **always** goes on to read the log file in that directory. And the assertions it evaluates are not taken from any source file — a Gatling log file's run record carries the assertions the original run declared, and those are read back along with the statistics. Gatling therefore: 1. parses the stored log; 2. re-evaluates the original run's assertions against the original run's data; 3. prints each verdict with its actual measured value; 4. writes the HTML report; 5. folds the verdicts and returns `Success` (`0`) or `AssertionsFailed` (`2`). So `-ro` **does** produce a pass/fail verdict. It is the *same* verdict the original run produced, recomputed from the same data. ## Why that matters operationally | what the runner sees | what actually happened | |---|---| | the process ran and exited `0` | an old run's assertions were re-checked and still hold | | a fresh HTML report appeared | it was rebuilt from an existing log | | the job is green | **no traffic was generated at all** | A job that still carries `-ro` from someone's debugging session looks entirely healthy. It produces a report with a timestamp, a verdict, and an exit code, and it exercises nothing. That failure mode belongs to the same family as a simulation with no assertions: the exit code is honest about what it judged and silent about what it did not do. ## Practical details worth knowing - **It needs a results folder.** If Gatling has not been told where results live, the reports path raises an error rather than guessing — the directory name is relative to that root. - **It re-reads, it does not re-record.** The log's statistics are fixed; you cannot use `-ro` to change what was measured, only to rebuild the presentation of it and re-run the judgement. - **The log is buffered while a run is live.** A run that was killed loses its tail, so regenerating reports from it shows a partial picture — accurate for what was flushed, incomplete for what was not. - **It is not documented in Gatling's reference content.** The option exists in the shared command-line definitions and in the application's parser; if you go looking for a page describing it, you will not find one. Work from the option's own help text: *generates the reports for the simulation in `<directoryName>`*. ## The related option people confuse it with `--no-reports` (`-nr`) is almost the mirror image: it **runs** the simulation and skips writing the HTML. Crucially it does not switch off assertions — with assertions declared, Gatling still reads the log, evaluates them, and returns `2` if one fails. The only case where `-nr` truly skips everything is when the simulation also declares no assertions; then Gatling has no reason to read the log at all and returns success immediately, without computing a single statistic. Holding those two apart is the point: one option runs without reporting, the other reports without running, and both can leave a job green.

  • Why does Gatling's --reports-only option need no simulation class on the command line?
    Because it is handled before Gatling resolves which simulation to run. That branch builds its result straight from the named results directory, so nothing is looked up or instantiated and no scenario ever executes. The value you pass identifies a directory of stored results, not a class.
  • Does a --reports-only invocation always exit 0?
    No. It reads the stored log, re-evaluates the assertions the original run recorded there, and folds those verdicts the usual way. If that run's assertions did not hold, the regeneration exits `2` as well — it reproduces the original verdict rather than inventing a clean one.
  • How does --no-reports differ from --reports-only in Gatling?
    They are near mirror images. `--no-reports` runs the simulation and skips writing the HTML, but still evaluates any declared assertions. `--reports-only` writes the HTML and evaluates assertions without running anything at all. Only one of them generates load, and neither of them is a reliable signal on its own.

It is re-printing last week's invoice from the accounting records. The document is new, the numbers are not, and nothing was sold today.

saying these in an interview costs you the question

  • Believing --reports-only re-runs the simulation it names
  • Assuming a reports-only invocation always exits 0
  • Thinking the flag takes a simulation class name
  • Confusing --no-reports with --reports-only in a job definition
  • Expecting --no-reports to also switch assertions off