Skip to content

The first page: what RESTest is and how to start, with a real run, for humans and for agents - #4

Merged
ssegura merged 9 commits into
mainfrom
feat/landing-page
Nov 10, 2026
Merged

ssegura merged 9 commits into
mainfrom
feat/landing-page

Conversation

@ssegura

@ssegura ssegura commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Related: isa-group/RESTest#440, the run of the clinic RESTest's manual keeps, which this page shows; and the pull request of RESTest that changes the sentence for coding agents, which this page takes from RESTest's page. This pull request is merged once RESTest 2.5.0 is published: it offers the coding agent and jbang, which 2.5.0 brings.

What you can do now that you could not before

Open https://isa-group.github.io/restest-site/ and learn in ten seconds what RESTest is and how to start, with a coding agent, Homebrew, jbang or Docker, each a command to copy; then see, band by band, how it works, with an animation whose figures and faults are those of a real run, that run's report.html in three views, what a coding agent does with RESTest, the three inputs that shape a run, and how to reach us. Until now / led to the documentation.

Try it yourself

With Node 26, from a clean clone:

git clone --branch feat/landing-page https://github.com/isa-group/restest-site && cd restest-site
npm ci && npm test 2>&1 | grep -E '^ℹ (pass|fail)'
npm run build | grep -E 'Copied|page\(s\) built'
grep -o 'class="kicker">[^<]*' dist/index.html
ℹ pass 56
ℹ fail 0
Copied 72 pages and 3 images of RESTest 2.4.0
[build] 74 page(s) built in 1.80s
class="kicker">01 · Shaping a run
class="kicker">02 · About us

That is the page RESTest 2.4.0 can give: it keeps no run and has no page for coding agents, so the bands that need them are left out. With RESTest's branch that keeps the run:

npm run sync -- --ref feat/m12-7-clinic-run | grep Copied && npx astro build | grep 'page(s) built'
grep -o 'class="kicker">[^<]*' dist/index.html
npm run preview
Copied 76 pages and 10 images of RESTest at feat/m12-7-clinic-run, and the run its first page shows
[build] 78 page(s) built in 1.91s
class="kicker">01 · How it works
class="kicker">02 · The report
class="kicker">03 · For coding agents
class="kicker">04 · Shaping a run
class="kicker">05 · About us

Open http://localhost:4321/restest-site/: the animation's figures are those of the kept report.json (182,898 requests, 26,973 errors on 30 of 43 operations, 71,237 warnings on 39); the report's tabs switch views; a picture opens at full size; the theme buttons keep their choice apart from /docs/'s. On that branch the sentence for a coding agent is still the old one; once RESTest's pull request that changes it is merged, npm run sync -- --ref master shows the new one.

How it works

The page is no page of Starlight's: src/pages/index.astro with its frame in src/layouts/Landing.astro and its look in src/styles/landing.css, ported from the approved mock-up onto the same tokens as the documentation. Everything it says about a run comes from RESTest at the version the site documents: scripts/sync-docs.mjs reads the run RESTest's manual keeps in docs/manual/images/clinic-run/, held there by a test of RESTest's, copies its six pictures and writes, in src/generated/landing.json, the version the site publishes, what the page shows of the run (scripts/lib/landing-run.mjs) and the sentence RESTest's page for coding agents tells a person to give their agent. A version without the run, or without that page, gets a page without the bands that need them; every other link to the documentation is looked up among the pages built, and the build stops on one that is not there.

The animation draws the run as the mock-up did, redrawn so that no text is under 14 pixels: requests from restest run to the API, a black box, and their replies, moved by CSS so that they stop when its button pauses them, while the panel is out of view, or for a reader who asked for less motion; on a narrow screen it is drawn downwards in text. Under it, one fault of each kind the run wrote out, in report.html's order and words, and the report's counts. Without JavaScript the page shows everything, in the system's theme: the four commands one under another, the faults as a list, the three views of the report.

What changed in the code

  • src/pages/index.astro, src/layouts/Landing.astro (new) — the page and its frame; the theme kept under restest-landing-theme, apart from the documentation's.
  • src/components/landing/ (new) — BlackBox.astro (the animation, the faults and the counts), Install.astro (the ways to start), ReportViews.astro (the report's views, served at 1080 and 2160 pixels, the view not shown not fetched, each opening at full size), page.ts (tabs with the keyboard, copying, bands that appear, pausing), tabs.ts, icons.ts, run.ts.
  • src/styles/landing.css (new) — the mock-up's landing page on tokens.css.
  • scripts/lib/landing-run.mjs (new) and test/landing-run.test.mjs — what the page shows of a run, and the sentence for a coding agent, each tested.
  • scripts/sync-docs.mjs — writes src/generated/landing.json and copies the run's pictures.
  • src/components/ThemeSelect.astro — an optional key under which the choice is kept.
  • astro.config.mjs — / no longer leads to /docs/.
  • README.md — the landing page, and where what it shows comes from.

Evidence

  • npm test: 56 tests pass, 8 of them new.
  • npm run build with restest-version (2.4.0): 74 pages, the first with two bands; with RESTest's branch that keeps the run: 78 pages, the first with five.
  • In the browser, at 1440, 1024, 768, 375 and 320 pixels, light and dark, with and without JavaScript, and with less motion asked for: no horizontal scroll, no text under 14 pixels, the animation included; tabs with the keyboard; the theme apart from /docs/, whose own still works; nothing moving with less motion; the animation paused out of view.
  • Each figure and fault on the page compared with the kept report.json.
  • Weight, gzipped: the page 8.4 KB, its CSS 3.8 KB, its scripts 1.1 KB plus 1.6 KB inline; fonts 22.3 KB (Space Grotesk, preloaded, since the title is set in it), 40.4 KB (JetBrains Mono) and 33.7 KB (Sora, for the numbers); each picture of the report 65 KB at 1080 pixels or 145 KB at 2160, fetched only for the view shown once the band comes near.

Decisions taken

  • Only the animation, no terminal recording; plain CSS, not Tailwind; the band on real APIs left to the showcase; merged with 2.5.0 (maintainer, 6 November).
  • The text, then the page itself as the mock-up, approved at the preview (maintainer), after two rounds of changes: the agent note, faults without the kind's advice, three counts, no note under the animation, the run of the clinic as the Web Fuzzing Dataset builds it rather than in emulation, pictures twice as sharp, the sentence for a coding agent pointing at the site's page, About us and the foot.
  • The sentence for a coding agent is read from RESTest's page, the first block of code under "Asking your agent", which RESTest holds its README to; so the page, the README and this page cannot say different things.
  • Each part keeps its own theme (maintainer, 4 November): the landing page's under restest-landing-theme, the documentation's under starlight-theme.
  • Sora is kept for the numbers, as the look settled, at 33.7 KB; cutting it down to digits needs a tool and changes the vendored file, and is left for when it is weighed again.
  • Quality 90 for the report's pictures (maintainer asked for them sharp): 25% heavier than 80.
  • Not taken from reviewers:
    • the API's name, "Spring PetClinic REST", is written in the page rather than read from the run, whose report holds only its document's title; RESTest's test of the kept run does not pin the API either;
    • no test of a version without the run: the build at 2.4.0 is that test until 2.5.0;
    • the page for coding agents is looked up rather than required, so that 2.4.0 still builds; RESTest's own test holds that page;
    • the logos stay as two pictures, cached from the documentation.

Open questions

  • Merge after 2.5.0 is published, once restest-version reads v2.5.0 and this branch builds green with the five bands.
  • Since #440 changes the run, its pictures and figures here will be those of whatever run 2.5.0's tag keeps.
  • GitHub's "homepage" field of RESTest's repository can point at this page once it is published.

🤖 Generated with Claude Code

ssegura and others added 7 commits November 6, 2026 13:36
…the manual's clinic

Bands under a centred top, as the site's mock-up drew them: how it works, with an animation of the run
whose figures and faults come from the report.json RESTest's manual keeps; that run's report.html in
three views; coding agents; the three inputs of a run; and how to reach us. The run, the pictures and
the page for coding agents are read from the version the site documents, and their bands are left out
of a version that does not have them. The theme picker keeps the first page's choice apart from the
documentation's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…taset's clinic in sharper pictures, and who to write to

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on, the prompt RESTest gives, and open source

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… comes from, and what it leaves out

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…abs, CSS that applies, and nothing fetched or run out of sight

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t, whole fault sentences, and controls that work or are not shown

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…picture of the report at full size

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ot without a link

Asked for by the maintainer at the preview of the showcase, which builds on this page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ssegura added a commit to isa-group/RESTest that referenced this pull request Nov 8, 2026
…ntation site, in the same words everywhere (#441)

**Related:** isa-group/restest-site#4, the
documentation site's first page, which shows the sentence this pull
request gives, read from the page for coding agents;
#440, the run that page shows.
**This pull request is merged while 2.5.0 is prepared, before its tag**:
the address it gives answers only once 2.5.0 is published.

## What you can do now that you could not before

Give a coding agent two sentences — "Use RESTest to test the REST APIs
you develop in this project. Follow the setup and usage instructions at
https://isa-group.github.io/restest-site/docs/for-coding-agents/" — and
have it read, on the documentation site, the page for coding agents of
the version it will install, rather than the page as `master` has it.
The README, that page and the site's first page give the same sentence,
and the build fails if the README and the page ever differ.

## Try it yourself

With Java and git, from a clean clone:

```bash
git clone --branch feat/m12-7-agent-prompt https://github.com/isa-group/RESTest.git restest-agent-prompt
cd restest-agent-prompt
sed -n '/^## Asking your agent/,/^```$/p' docs/for-coding-agents.md | tail -4
./mvnw verify -pl restest-arch-tests -am -Dtest='io.restest.arch.DocumentedSkillTest' \
  -Dsurefire.failIfNoSpecifiedTests=false | grep -E 'Tests run:.*in io|BUILD'
```

````
Two sentences are enough:

```
Use RESTest to test the REST APIs you develop in this project. Follow
the setup and usage instructions at
https://isa-group.github.io/restest-site/docs/for-coding-agents/
[INFO] Tests run: 10, Failures: 0, Errors: 0, Skipped: 0, Time elapsed:
6.385 s -- in io.restest.arch.DocumentedSkillTest
[INFO] BUILD SUCCESS
````

Now have the README say something else than the page:

```bash
sed -i.bak 's/develop in this project\. Follow/develop. Follow/'
README.md && rm README.md.bak
./mvnw verify -pl restest-arch-tests -am
-Dtest='io.restest.arch.DocumentedSkillTest' \
-Dsurefire.failIfNoSpecifiedTests=false | grep -E '^\[ERROR\]
DocumentedSkillTest|BUILD'
```

```
[ERROR] DocumentedSkillTest.the_readme_asks_as_the_page_does:199 [what
the README tells an agent under "From a coding agent" is what
docs/for-coding-agents.md tells it under "Asking your agent", which the
website's first page shows too: change the two together]
[INFO] BUILD FAILURE
```

Undo it with `git checkout -- README.md`. The address itself answers once 2.5.0 is published; today the site documents 2.4.0, which has no page for coding agents.

## How it works

The README, under "From a coding agent", and the page for coding agents, under "Asking your agent", each give a person a sentence to paste into their agent. It used to point at the page on GitHub as `master` has it, which may describe options the version the agent installs does not have yet. It now asks the agent to follow the setup and usage instructions on the documentation site, which documents the latest release, the one Homebrew, jbang and the image install; the page tells the agent how to install RESTest and the skill, and ends with the skill itself.

The sentence is now given in three places: the README, the page, and the documentation site's first page, which reads it from the page at the version it documents, so the two on the site cannot differ. A test holds the README to the page: the first block of code under each heading must be the same, or the build fails saying where to change it.

## What changed in the code

- `README.md` and `docs/for-coding-agents.md` — the new sentence, "two sentences" rather than "one", and "the second can go" once the skill is installed.
- `restest-arch-tests/.../DocumentedSkillTest.java` — `the_readme_asks_as_the_page_does`, with `firstBlockUnder(page, heading)`, which reads the first block of code under a heading and stops at the next one.
- `docs/adr/0047-the-documentation-site.md` §3 — the site's first page relies on that block of the page, held by the test.
- `docs/ci.md` — the table of gates says what the test now catches.

## Evidence

- [x] Tests: one added to `DocumentedSkillTest`, now 10; it fails when the README's sentence differs from the page's, as shown above. Architecture and documentation rules: all green. — the checks of this pull request
- [x] Architecture tests: none weakened.
- [x] Mutation score: not applicable; no oracle or constraint touched.
- [x] Per-request overhead: not applicable.
- [x] Smoke run: not applicable.
- [x] Idle time: not applicable.
- [x] Artefact: the documentation site's first page built from this branch shows the same sentence under "Coding agent" and in its band for coding agents (isa-group/restest-site#4).

## Decisions taken

- **The page on the documentation site, not the skill, and not the page on GitHub** (maintainer): the page gives both the setup — installing RESTest and the skill, so that a later session needs no address — and the use, the skill word for word at its end; and on the site it describes the version the agent installs, where `master` may describe the next one.
- **A pull request of its own, merged with 2.5.0** (maintainer): until 2.5.0 is published, the site documents 2.4.0 and the address answers "page not found".
- **The site reads the sentence from the page** rather than keeping a copy, and RESTest holds the README to the page, so one sentence is changed in one place and checked in the other.
- **`restest --help` still names the page on GitHub at the running version's tag**, which is right for the version a person has; ADR-0046, a record, still speaks of the one sentence it decided then.

## Open questions

- **Merge with 2.5.0**, before its tag, so that the site's first page of 2.5.0 shows this sentence.
- **#440 changes the same row of `docs/ci.md`'s table of gates**; whichever is merged second keeps both additions.

---

- [x] Targets `master`
- [x] English throughout, including comments and test names
- [x] The hard rules in `AGENTS.md` hold

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura
ssegura merged commit 2b19300 into main Nov 10, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant