Repository navigation
The first page: what RESTest is and how to start, with a real run, for humans and for agents - #4
Merged
Merged
Conversation
…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>
10 tasks done
…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>
10 tasks done
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.htmlin 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:
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:
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 mastershows the new one.How it works
The page is no page of Starlight's:
src/pages/index.astrowith its frame insrc/layouts/Landing.astroand its look insrc/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.mjsreads the run RESTest's manual keeps indocs/manual/images/clinic-run/, held there by a test of RESTest's, copies its six pictures and writes, insrc/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 runto 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 underrestest-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 ontokens.css.scripts/lib/landing-run.mjs(new) andtest/landing-run.test.mjs— what the page shows of a run, and the sentence for a coding agent, each tested.scripts/sync-docs.mjs— writessrc/generated/landing.jsonand 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 buildwithrestest-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./docs/, whose own still works; nothing moving with less motion; the animation paused out of view.report.json.Decisions taken
restest-landing-theme, the documentation's understarlight-theme.Open questions
restest-versionreadsv2.5.0and this branch builds green with the five bands.🤖 Generated with Claude Code