[ssegura]

Related: None

What you can do now that you could not before

Nothing changes in the tool. The documentation now says what this version does, everywhere. It was read page by page against the code and the tool's own output, and every place where an earlier change of this version left a page saying something no longer true, or two pages disagreeing, is fixed.

Try it yourself

Only documentation changed. The tests that hold the pages to the tool are the check:

git fetch origin && git switch docs/review-before-2.2.0
./mvnw -q verify -pl restest-arch-tests -am -Dtest='io.restest.arch.**' -Dsurefire.failIfNoSpecifiedTests=false
echo "exit $?"

exit 0

To see a correction for yourself: docs/command-line.md now says that an address with a user name or a password is refused, and the run ends with 3.

./mvnw -q install -DskipTests
./restest run restest-spec/src/test/resources/specifications/restleague-2027/pet-clinic/openapi.yaml --url 'http://u:p@127.0.0.1:1' --budget 1s; echo "exit $?"

restest: the address given with --url carries a user name or a password before its host, which is not repeated here. Give the address without them, such as http://localhost:8080/api/v3, and a key the API asks for with --auth
exit 3

How it works

Four reviewers each read part of the documentation against the code, the poms, the workflows and the tool's output (--help, --print-settings, --print-campaign, runs that send nothing). Each claim found wrong was checked again before it was changed.

The parts were:

• the README and the manual's chapters 1 to 6;
• chapters 7 to 11, the index, CONTRIBUTING.md and AGENTS.md;
• the pages on faults, the report, the command line, settings, switches and known limitations;
• the pages on the plan and dictionary formats and the schemas, ci.md, DESIGN.md, and the index of decision records.

What changed in the code

No code. The pages, by kind of problem:

Wrong

• command-line.md, chapters 9 and 10: an address given with --url that carries a query string, or a user name or a password, is refused, and the run ends with 3, not 2. Chapter 10 now quotes the message, and also covers an --out that cannot be written to.
• Chapter 7: a body longer than RESTest keeps whole is not checked against its shape (notChecked, cutShort). It is not "enough to judge it by".
• DESIGN.md:
  • an architecture test that "nothing blocks the request loop", which does not exist (idle time is what shows it);
  • a base URL as a mandatory input;
  • snakeyaml confined to one module, where it is in two.
• ci.md:
  • seven mutants survive, not three; the four new ones are equivalent;
  • a "just the rules" command that builds everything;
  • the paths that make a pull request rehearse a release.
• report.md:
  • a claim that every line counting one thing is in the singular;
  • no faults found described as a clean verdict, when a run that nothing answered says it too, before ending with 3.

Left behind by an earlier change of this version

• Chapter 1 lists the eight kinds with their titles and severities, and says that only errors end a run with 1.
• Chapter 10 speaks of warnings and titles.
• CONTRIBUTING.md no longer says a run reports only 500s and replies off their schema.
• command-line.md's exception to the freeze now also names the three new kinds that are errors, which can turn a 0 into a 1.
• dictionary-format.md lists an eighth reason an entry is never used.
• The switches page no longer promises a switch "when the code around it is next changed", a promise a change to one of its numbers already broke. It now says when one comes.
• The settings page names the numbers kept in the code on purpose, as ADR-0025's amendment of 14 October 2026 does.

Inconsistent between pages

• The decision records:
  • fifteen records had a status line that left out amendments in their own text;
  • the index now copies each record's own status;
  • two titles in the index differed from their records.
• The glossary:
  • Check, Clinic, Share and Title are added;
  • Strategy gives the four kinds;
  • Switch and Budget are corrected.
• Smaller fixes:
  • "the four ways to change a setting" (there are three);
  • the REDACTED-AUTH word for a key given alone;
  • the README's list of reference pages;
  • "Ctrl-C" alone where kill and docker stop end a run too.
• Wording tied to a version ("its default before 2.1", "as every run did until now", "were widened in 2.1"), against the rule that documentation describes the tool as it ships.

Evidence

• Tests: the architecture and documentation rules pass, DocumentedLinksTest among them. No code changed, so the rest of the build is as on master. CI: added below once it has run.
• Architecture tests: unchanged, none weakened.
• Mutation score: not touched. ci.md now quotes 97% (294 of 304), measured on 22 October 2026.
• Per-request overhead: not touched.
• Smoke run: not touched.
• Idle time: not touched.
• Artefact: this description's list, and the diff.

Decisions taken

• Left for 2.2.0's release pull request, which runs everything again from the release commit:

  • the README's first run and the manual's chapter 3, whose output and the prose describing it still show the screen before errors and warnings;
  • chapter 2's restest version output;
  • the clone pinned to v2.1.0 in chapter 9's workflow. Until it moves, that workflow cannot take --set checks.failOnWarnings=true.

  Changing the prose now, above output it does not match, would make each page contradict itself.

• Not changed:

  • the pull-request template's "if oracles or constraints were touched", which already provides for the constraints still to come;
  • CONTRIBUTING.md's "how hard a run pushes", which the settings page and --help say the same way.

Open questions

None.

---

• Targets master
• English throughout, including comments and test names
• The hard rules in AGENTS.md hold
• Nothing from "Out of scope" in docs/DESIGN.md without explicit approval

🤖 Generated with Claude Code