Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ jbang app install restest@https://isa-group.github.io/jbang-catalog/jbang-catalo
the folder you are in as `/work`:

```bash
docker run --rm -v "$PWD:/work" ghcr.io/isa-group/restest:2.4.0 version
docker run --rm -v "$PWD:/work" ghcr.io/isa-group/restest:2.5.0 version
```

Homebrew and jbang leave `restest` as a command on your `PATH`, and `restest version` says which
Expand Down
58 changes: 29 additions & 29 deletions docs/manual/02-installing.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ brew install isa-group/tap/restest

`isa-group/tap` is RESTest's own *tap*, the place Homebrew reads how to install it from, and Homebrew
fetches it the first time. With the Java and what that Java needs, the first installation keeps
about 625 MB on macOS and 823 MB on Ubuntu 24.04. On a Linux whose C library is older than
about 628 MB on macOS and 824 MB on Ubuntu 24.04. On a Linux whose C library is older than
Homebrew's, Homebrew brings its own, and a compiler with it, and the total comes to some 1.5 GB.
Homebrew lists what it installs as it goes. Then:

Expand All @@ -26,8 +26,8 @@ restest version
```

```
RESTest 2.4.0
Java 21.0.12.1 (Homebrew), Mac OS X 26.6.2 aarch64
RESTest 2.5.0
Java 21.0.13.0.3 (Homebrew), Mac OS X 26.7.2 aarch64
```

The `restest` Homebrew installs always runs on that Java 21, whatever `JAVA_HOME` says; for RESTest on
Expand All @@ -54,19 +54,19 @@ restest version
```

```
RESTest 2.4.0
Java 27 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
RESTest 2.5.0
Java 27.0.1.0.2 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
```

and on Windows, in the command prompt or in PowerShell:

```
RESTest 2.4.0
Java 27 (Eclipse Adoptium), Windows Server 2025 10.0 amd64
RESTest 2.5.0
Java 27.0.1.0.2 (Eclipse Adoptium), Windows Server 2025 10.0 amd64
```

Those are machines with no Java, where jbang downloads two into `~/.jbang`: a Java 17 for jbang
itself, and the newest Java for RESTest, some 600 MB together, as well as RESTest's libraries, 37 MB,
itself, and the newest Java for RESTest, some 640 MB together, as well as RESTest's libraries, 37 MB,
into `~/.m2/repository`. On a machine with a JDK 21 or later — a JDK, which jbang looks for, not a
plain Java runtime — jbang downloads the libraries alone and runs RESTest on that Java. With
`JBANG_DEFAULT_JAVA_VERSION` set to `21` before the first jbang command of all — `export` it in a
Expand Down Expand Up @@ -130,11 +130,11 @@ The image holds RESTest and the Java it runs on, for Intel and AMD processors an
as Apple silicon. The first command downloads it, about 145 MB:

```bash
docker run --rm ghcr.io/isa-group/restest:2.4.0 version
docker run --rm ghcr.io/isa-group/restest:2.5.0 version
```

```
RESTest 2.4.0
RESTest 2.5.0
Java 21.0.13 (Eclipse Adoptium), Linux 7.0.14-linuxkit aarch64
```

Expand All @@ -143,7 +143,7 @@ the container that folder is `/work`, and it has to be lent from your machine: `
lends the folder you are in. What you would give `restest` then goes after the image's name:

```bash
docker run --rm -v "$PWD:/work" ghcr.io/isa-group/restest:2.4.0 run openapi.yaml --url https://api.example.com --budget 30s
docker run --rm -v "$PWD:/work" ghcr.io/isa-group/restest:2.5.0 run openapi.yaml --url https://api.example.com --budget 30s
```

That reads `openapi.yaml` from the folder you are in and leaves `restest-out/`, with the report, in
Expand All @@ -156,7 +156,7 @@ runs the image with the folder you are in, and the rest a run needs, every time:

```bash
mkdir -p ~/.local/bin
printf '%s\n' '#!/bin/sh' 'exec docker run --rm -v "$PWD:/work" --user "$(id -u):$(id -g)" -e RESTEST_AUTH --add-host=host.docker.internal:host-gateway ghcr.io/isa-group/restest:2.4.0 "$@"' > ~/.local/bin/restest
printf '%s\n' '#!/bin/sh' 'exec docker run --rm -v "$PWD:/work" --user "$(id -u):$(id -g)" -e RESTEST_AUTH --add-host=host.docker.internal:host-gateway ghcr.io/isa-group/restest:2.5.0 "$@"' > ~/.local/bin/restest
chmod +x ~/.local/bin/restest
export PATH="$HOME/.local/bin:$PATH"
```
Expand Down Expand Up @@ -209,43 +209,43 @@ found, install a current Java — [Eclipse Temurin](https://adoptium.net/) is on
open a new terminal.

Every release carries an archive with RESTest and every library it runs with, in two forms,
`restest-2.4.0.tgz` and `restest-2.4.0.zip`, on its [page on
GitHub](https://github.com/isa-group/RESTest/releases/tag/v2.4.0). Download one and unpack it:
`restest-2.5.0.tgz` and `restest-2.5.0.zip`, on its [page on
GitHub](https://github.com/isa-group/RESTest/releases/tag/v2.5.0). Download one and unpack it:

```bash
curl -fLO https://github.com/isa-group/RESTest/releases/download/v2.4.0/restest-2.4.0.tgz
tar -xzf restest-2.4.0.tgz
restest-2.4.0/bin/restest version
curl -fLO https://github.com/isa-group/RESTest/releases/download/v2.5.0/restest-2.5.0.tgz
tar -xzf restest-2.5.0.tgz
restest-2.5.0/bin/restest version
```

```
RESTest 2.4.0
RESTest 2.5.0
Java 25.0.4.1 (Eclipse Adoptium), Mac OS X 27.0.1 aarch64
```

The release also carries `checksums_sha256.txt`, which says whether the archive arrived whole.
Downloaded beside it,

```bash
curl -fLO https://github.com/isa-group/RESTest/releases/download/v2.4.0/checksums_sha256.txt
curl -fLO https://github.com/isa-group/RESTest/releases/download/v2.5.0/checksums_sha256.txt
sha256sum --ignore-missing -c checksums_sha256.txt
```

answers `restest-2.4.0.tgz: OK`; on macOS, write `shasum -a 256` in place of `sha256sum`.
answers `restest-2.5.0.tgz: OK`; on macOS, write `shasum -a 256` in place of `sha256sum`.

The folder `restest-2.4.0` holds `bin/`, with the command, `lib/`, with the libraries, `schemas/`,
The folder `restest-2.5.0` holds `bin/`, with the command, `lib/`, with the libraries, `schemas/`,
with the JSON Schemas of a dictionary and a plan ([chapter 6](06-dictionaries.md)), `skills/`, with
the skill that teaches a coding agent to use RESTest ([RESTest and coding
agents](../for-coding-agents.md)), and the licences.
It can live anywhere. This line puts its `bin/` on the `PATH`, which makes `restest` the command,
from any folder:

```bash
export PATH="$PWD/restest-2.4.0/bin:$PATH"
export PATH="$PWD/restest-2.5.0/bin:$PATH"
```

On Windows, unpack `restest-2.4.0.zip` and run `restest-2.4.0\bin\restest.cmd` from the ordinary
command prompt, or `restest-2.4.0/bin/restest` from Git Bash.
On Windows, unpack `restest-2.5.0.zip` and run `restest-2.5.0\bin\restest.cmd` from the ordinary
command prompt, or `restest-2.5.0/bin/restest` from Git Bash.

When the command finds no Java it can use, it says so and ends with `127`:

Expand All @@ -272,7 +272,7 @@ git version 2.54.0 (Apple Git-157)
Then:

```bash
git clone --branch v2.4.0 https://github.com/isa-group/RESTest.git
git clone --branch v2.5.0 https://github.com/isa-group/RESTest.git
cd RESTest
./mvnw -q package -DskipTests
```
Expand All @@ -282,7 +282,7 @@ first build downloads everything RESTest is built from and takes a few minutes;
than one. `-q` keeps it quiet, so it prints nothing when it works, and `-DskipTests` leaves out
RESTest's own tests, which take longer than the build and which you do not need to use the tool.

`--branch v2.4.0` fetches the release; without it, `git clone` fetches what is being built next, whose
`--branch v2.5.0` fetches the release; without it, `git clone` fetches what is being built next, whose
version ends in `-SNAPSHOT`. `./restest`, at the root of the checkout, runs what was built, and this
line puts the checkout on the `PATH`, which makes it `restest`, from any folder:

Expand Down Expand Up @@ -321,18 +321,18 @@ from that shell find it too.
- **Homebrew:** `brew upgrade restest` installs the latest release.
- **jbang:** nothing: it runs the latest release within twelve hours of it, or at once after
`jbang --fresh restest@https://isa-group.github.io/jbang-catalog/jbang-catalog.json version`.
- **Docker:** change `2.4.0` in the script to the version you want.
- **Docker:** change `2.5.0` in the script to the version you want.
- **The archive:** download and unpack the new one, and point the `PATH` at its `bin/`.
- **The source:** from the root of the checkout, fetch the new release's tag, move to it, and build
again:

```bash
git fetch --tags
git checkout v2.4.0
git checkout v2.5.0
./mvnw -q clean package -DskipTests
```

with the new version in place of `2.4.0`. `clean` throws away what the last build left behind, so
with the new version in place of `2.5.0`. `clean` throws away what the last build left behind, so
that the jars of the version you had are not found beside the ones of the version you now have.

The [next chapter](03-a-first-run.md) starts a practice API and runs RESTest against it.
8 changes: 4 additions & 4 deletions docs/manual/09-exit-codes-and-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ jobs:
java-version: '21'

- name: Get RESTest
run: curl -fsSL https://github.com/isa-group/RESTest/releases/download/v2.4.0/restest-2.4.0.tgz | tar -xz
run: curl -fsSL https://github.com/isa-group/RESTest/releases/download/v2.5.0/restest-2.5.0.tgz | tar -xz

- name: Wait for the API
run: |
Expand All @@ -103,7 +103,7 @@ jobs:
exit 1

- name: Test the API
run: restest-2.4.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m
run: restest-2.5.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m

- name: Keep the report
if: always()
Expand Down Expand Up @@ -136,7 +136,7 @@ Some things to decide for your own build:
warnings fail it too:

```bash
restest-2.4.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m --set checks.failOnWarnings=true
restest-2.5.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m --set checks.failOnWarnings=true
```

The summary then says so under the warnings it found, and the run ends with `1`. From a run of the
Expand All @@ -156,7 +156,7 @@ Some things to decide for your own build:
answering, a misspelt file — by treating `1` as a pass:

```bash
restest-2.4.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m || [ $? -eq 1 ]
restest-2.5.0/bin/restest run http://localhost:9966/petclinic/v3/api-docs --budget 2m || [ $? -eq 1 ]
```

The [next chapter](10-troubleshooting.md) is about runs that do not do what you expected.
2 changes: 1 addition & 1 deletion pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
Central as es.us.isa:restest. The Java packages stay io.restest. ADR-0044. -->
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
<packaging>pom</packaging>

<name>RESTest</name>
Expand Down
2 changes: 1 addition & 1 deletion restest-arch-tests/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-arch-tests</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-cli/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-cli</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-core/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-core</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-exec/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-exec</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-gen/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-gen</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-oracles/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-oracles</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-report/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-report</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-spec/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-spec</artifactId>
Expand Down
2 changes: 1 addition & 1 deletion restest-store/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<parent>
<groupId>es.us.isa.restest</groupId>
<artifactId>restest</artifactId>
<version>2.5.0-SNAPSHOT</version>
<version>2.5.0</version>
</parent>

<artifactId>restest-store</artifactId>
Expand Down
Loading