Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
eaac480
feat(web): bootstrap the web app, its mock server and the end-to-end …
cuioss-oliver Nov 20, 2026
c1d9a7d
fix: resolve the Sonar findings of the bootstrap
cuioss-oliver Nov 20, 2026
f2c9698
feat(app): bootstrap the Quarkus application with the BFF login and t…
cuioss-oliver Nov 20, 2026
bf5b207
fix(app): query response mode, native login and the Sonar findings
cuioss-oliver Nov 20, 2026
7d588a2
test(it): integration tests of the native image with Keycloak
cuioss-oliver Nov 20, 2026
066f56d
fix(app): state why the two producers use @Singleton (Sonar java:S9068)
cuioss-oliver Nov 20, 2026
37e1519
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 20, 2026
386a964
docs: state the bootstrap and describe the end-to-end suite
cuioss-oliver Nov 21, 2026
d0ee810
Merge branch 'feature/bootstrap-ui' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
f72c231
docs(app): README of the application module and the native JGit state
cuioss-oliver Nov 21, 2026
dd54eb3
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
eb103d3
docs: remove doc/ai-rules.md
cuioss-oliver Nov 21, 2026
dc9deff
Merge commit 'eb103d3' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
d32ed2c
Merge branch 'main' into feature/bootstrap-app
cuioss-oliver Nov 21, 2026
86f1cfe
fix(app): handle the review of the application module
cuioss-oliver Nov 21, 2026
a6b2aac
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
93811ed
test(it): log in through Keycloak's PAR flow
cuioss-oliver Nov 21, 2026
d5d3ad8
test(app): check that the native build arguments keep the escaped comma
cuioss-oliver Nov 21, 2026
61c3c6c
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
8da268f
fix(app): handle the second review round of the application module
cuioss-oliver Nov 21, 2026
b71919e
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
bdeb8bd
fix(app): handle the third review round of the application module
cuioss-oliver Nov 21, 2026
bff0b1a
fix(app): split the IPv6 serialization and name the status event (Sonar)
cuioss-oliver Nov 21, 2026
f38bdf4
Merge branch 'feature/bootstrap-app' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
d5334a1
Merge branch 'main' into feature/bootstrap-integration
cuioss-oliver Nov 21, 2026
9f34154
fix(it): handle the review of the integration tests
cuioss-oliver Nov 21, 2026
f4a7ff8
fix: follow the new fetch input of git-document-repository; derive th…
cuioss-oliver Nov 21, 2026
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
7 changes: 4 additions & 3 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,14 @@ The target is Java 25; CI builds on Java 25 and 27.
The modules of link:doc/specification/architecture-and-modules.adoc[Architecture and Modules] are added as they are
built, each with its own README: link:web-app/README.adoc[`web-app`] (the Svelte web app),
link:web-mock/README.adoc[`web-mock`] (the mock server of its requests, development and tests only),
link:trailhand/README.adoc[`trailhand`] (the Quarkus application) and link:web-e2e/README.adoc[`web-e2e`] (Playwright
and axe-core). The end-to-end suite runs with the profile `e2e`, the native image with the profile `native` (Mandrel
in a container):
link:trailhand/README.adoc[`trailhand`] (the Quarkus application), link:web-e2e/README.adoc[`web-e2e`] (Playwright
and axe-core) and link:integration-tests/README.adoc[`integration-tests`] (the native image with Keycloak). The
end-to-end suite runs with the profile `e2e`, the native image with the profile `native` (Mandrel in a container):

[source,bash]
----
./mvnw verify -Pe2e -pl web-e2e -am
./mvnw verify -Pintegration-tests -pl integration-tests -am # native image + Keycloak, Docker required
./mvnw package -Pnative -pl trailhand -am
docker build -f trailhand/src/main/docker/Dockerfile.native -t trailhand:dev trailhand
----
Expand Down
2 changes: 1 addition & 1 deletion doc/specification/architecture-and-modules.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ Root: `de.cuioss:trailhand-parent` (working coordinates). Parent `de.cuioss:cui-
|Playwright and axe-core suite; profile `e2e`

|`integration-tests`
|pom
|jar (not deployed)
|Native image, distroless container, compose stack, failsafe `*IT`; profile `integration-tests`; the measurements of
xref:testing.adoc#TRH-NFR-1[TRH-NFR-1] and xref:testing.adoc#TRH-NFR-2[TRH-NFR-2] in the profile `benchmarks`

Expand Down
4 changes: 3 additions & 1 deletion doc/specification/testing.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,9 @@ xref:../concepts/application-architecture.adoc#_testing[Application Architecture

|Integration
|Profile `integration-tests` (failsafe `*IT`)
|Native image, distroless container, compose stack with Keycloak and Gitea
|Native image, distroless container, compose stack with Keycloak and Gitea; until the Git round trip
(<<TRH-NFR-5>>) is built, the repositories are local bare repositories mounted as `file:` remotes (TRH-CONF-2) and
Gitea is not started

|Benchmarks
|Profile `benchmarks` of the `integration-tests` module, in a CI job of its own
Expand Down
127 changes: 127 additions & 0 deletions integration-tests/README.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
= TrailHand Integration Tests
:toc: left
:toclevels: 2

The integration lane of `doc/specification/testing.adoc`: the native image of `trailhand` in its distroless container,
with a Keycloak, in one compose stack. The tests talk to it over HTTPS as a browser would, including the login form of
Keycloak. Gitea joins with the Git round trip (TRH-NFR-5); until then the repositories are local bare repositories
mounted as `file:` remotes (TRH-CONF-2). The module deploys nothing, and CI does not run the profile yet.

== Running

Docker with compose is required.

[source,bash]
----
./mvnw verify -Pintegration-tests -pl integration-tests -am
----

Without the profile the module only compiles. With it, Maven:

. before the tests: stops a leftover stack, generates the certificates, seeds the remotes, builds the native runner
and the image `trailhand:it` when they are missing or built from other inputs, and starts the stack
(`scripts/start-integration-stack.sh` waits until Keycloak is ready and the TrailHand container is ready and
reported healthy; a start that fails stops the stack again);
. runs every `*IT` with failsafe;
. afterwards: writes the container logs to `target/compose.log` and removes the stack with its volume, then checks
that an invalid configuration fails `--validate-config` and stops the boot with exactly the `TRAILHAND-200` records
`--validate-config` reports, one per violation (`scripts/verify-invalid-config-fails.sh`, TRH-NFR-5).

The native build runs Mandrel in a container and takes minutes. A later run reuses the runner while its inputs are
unchanged: `scripts/build-native-if-needed.sh` fingerprints the reactor's build files, the sources of `trailhand` and
`web-app` and the web app's package lock by path and content (`trailhand/target/native-inputs.sha256`), so a changed
dependency version or a deleted file rebuilds it.

=== Against a Running Stack

To look at the stack in a browser or to repeat the tests without restarting it, run the scripts by hand. `-pl
integration-tests` without `-am` takes `trailhand` from the local repository, so install it once
(`./mvnw install -DskipTests -pl trailhand -am`).

From the repository root:

[source,bash]
----
S=integration-tests/scripts
$S/generate-certificates.sh && $S/seed-remotes.sh && $S/build-native-if-needed.sh && $S/start-integration-stack.sh
./mvnw test-compile failsafe:integration-test failsafe:verify -Pintegration-tests -pl integration-tests
$S/stop-integration-stack.sh --clean # logs to target/compose.log; without --clean the data volume stays
----

While it runs, the application is at https://localhost:10443 (the certificate is self-signed) and signs in with a user
of the realm below.

== The Stack

[cols="1,1,3"]
|===
|Service |Host ports |Notes

|`keycloak`
|1443 (HTTPS), 1090 (management)
|Keycloak 26.8.1, pinned by digest; realm `trailhand` imported from `src/main/docker/keycloak/trailhand-realm.json`;
admin `admin`/`admin`

|`trailhand`
|10443 (HTTPS), 19000 (management)
|The image `trailhand:it`, read-only root file system, all capabilities dropped, `no-new-privileges`; configuration
`src/main/docker/trailhand-config/`, client secret `src/main/docker/secrets/`, data in the volume `trailhand-data`
|===

Every port is published on `127.0.0.1` only. The browser reaches Keycloak as `https://localhost:1443`, the application as `https://keycloak:8443` on the compose
network. Keycloak mints every issuer and redirect address from the browser-facing name (`KC_HOSTNAME`); the
application reaches it through `SHERIFF_CLIENT_BACK_CHANNEL_ORIGIN` and `TRAILHAND_OIDC_JWKS_URL`.

The scripts generate into `target/` (never committed): `certificates/`, one self-signed PEM pair for `localhost`,
`keycloak` and `trailhand` plus the PKCS#12 trust store with which the application trusts Keycloak, and `remotes/`, the
bare repositories `samm-assessments.git` and `directory.git`.

=== Realm

[cols="1,1,2"]
|===
|User |Group |Rights in `trailhand.yaml`

|`alex-assessor` |`assessors` |`samm-assessments`: read, edit
|`ana-approver` |`approvers` |`samm-assessments`: read, approve
|`cara-catalog` |`catalog-admins` |`directory`: read, administer catalogs
|`rudi-reader` |`readers` |`samm-assessments`: read
|`otto-outsider` |`auditors` |none: the group has no mapping (deny by default)
|===

Each password is `<user>-password`. The confidential client `trailhand-web` (secret `trailhand-it-client-secret`)
admits only `https://localhost:10443/api/v1/auth/callback`; the client `trailhand-mcp-agent` is registered for the MCP
server and not used yet. All of it is test data of this stack only.

== Tests

[cols="1,3"]
|===
|Class |What it checks

|`HealthIT`
|Liveness and readiness are `UP` once the repositories are cloned; the `git-remote` group and the metrics are on the
management port, not on 8443; the status answers without login and is not degraded

|`WebAppServingIT`
|Every canonical address answers the start page with the page security headers; the files of the web app come from
the application; the catalogue answers both languages

|`WebLoginIT`
|The login through Keycloak sets `HttpOnly` `Secure` cookies, ends at the return address and gives no token to the
browser; the session carries the rights mapped from the groups; a group without mapping grants nothing; a callback
without the login transaction opens no session

|`ReturnAddressIT`
|Only a canonical address is returned to; anything else becomes `/`

|`CsrfIT`
|Without a session `401` with the login address; a state-changing request without the anti-CSRF header, with a wrong
one or from a foreign origin is refused

|`LogoutIT`
|The logout ends the session, revokes the tokens and leads to Keycloak's end-session address
|===

`Stack` holds the addresses (system properties `trailhand.it.base`, `trailhand.it.management`, `trailhand.it.keycloak`)
and the browser-like login: no automatic redirects, cookies per site, the Keycloak form filled in.
129 changes: 129 additions & 0 deletions integration-tests/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>de.cuioss</groupId>
<artifactId>trailhand-parent</artifactId>
<version>0.1.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>trailhand-integration-tests</artifactId>
<packaging>jar</packaging>
<name>TrailHand Integration Tests</name>
<description>The integration lane (doc/specification/testing.adoc): the native image in its distroless container with
Keycloak, driven over HTTPS by failsafe *IT classes. Runs with the profile integration-tests.
</description>

<properties>
<maven.jar.plugin.automatic.module.name>de.cuioss.trailhand.integration</maven.jar.plugin.automatic.module.name>
<maven.deploy.skip>true</maven.deploy.skip>
<maven.install.skip>true</maven.install.skip>
<sonar.skip>true</sonar.skip>
<skipITs>true</skipITs>
</properties>

<dependencies>
<!-- Reactor order only: the native runner of trailhand is built by the scripts of this module. -->
<dependency>
<groupId>de.cuioss</groupId>
<artifactId>trailhand</artifactId>
<version>${project.version}</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<profiles>
<profile>
<id>integration-tests</id>
<properties>
<skipITs>false</skipITs>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<id>prepare-stack</id>
<phase>pre-integration-test</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>bash</executable>
<arguments>
<argument>-c</argument>
<argument>scripts/stop-integration-stack.sh --clean; scripts/generate-certificates.sh &amp;&amp; scripts/seed-remotes.sh &amp;&amp; scripts/build-native-if-needed.sh &amp;&amp; scripts/start-integration-stack.sh</argument>
</arguments>
<workingDirectory>${project.basedir}</workingDirectory>
</configuration>
</execution>
<!-- The stack stops first, so a failing invalid-config check cannot leave it running;
that check needs only the image. -->
<execution>
<id>stop-stack</id>
<phase>post-integration-test</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>${project.basedir}/scripts/stop-integration-stack.sh</executable>
<arguments>
<argument>--clean</argument>
</arguments>
<workingDirectory>${project.basedir}</workingDirectory>
</configuration>
</execution>
<execution>
<id>invalid-config</id>
<phase>post-integration-test</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>${project.basedir}/scripts/verify-invalid-config-fails.sh</executable>
<workingDirectory>${project.basedir}</workingDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<configuration>
<!-- The qualified pattern **/integration/**/*IT.java matches nothing under failsafe 3.6.0
(observed in API Sheriff); the plain pattern is used. -->
<includes>
<include>**/*IT.java</include>
</includes>
<systemPropertyVariables>
<trailhand.it.base>https://localhost:10443</trailhand.it.base>
<trailhand.it.management>http://localhost:19000</trailhand.it.management>
<trailhand.it.keycloak>https://localhost:1443</trailhand.it.keycloak>
</systemPropertyVariables>
</configuration>
<executions>
<execution>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
44 changes: 44 additions & 0 deletions integration-tests/scripts/build-native-if-needed.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
#!/usr/bin/env bash
#
# Copyright © 2026-present CUI-OpenSource-Software (info@cuioss.de)
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Builds the native runner of the trailhand module unless the one in target/ was built from the same inputs, then the
# image trailhand:it. The native build runs in a container (Mandrel, profile native). The inputs are fingerprinted by
# path and content: the build files of the reactor (dependency versions included), the sources and resources of
# trailhand and web-app, and the web app's package lock. An added, changed or deleted file rebuilds.
set -euo pipefail
source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"

APP_DIR="$REPO_ROOT/trailhand"
STAMP="$APP_DIR/target/native-inputs.sha256"
fingerprint() {
(cd "$REPO_ROOT" && find pom.xml .mvn trailhand/pom.xml trailhand/src/main web-app/pom.xml web-app/package.json \
web-app/package-lock.json web-app/vite.config.ts web-app/tsconfig.json web-app/src web-app/static \
-type f -not -path '*/node_modules/*' -print0 2>/dev/null \
| LC_ALL=C sort -z | xargs -0 shasum -a 256 | shasum -a 256 | cut -d' ' -f1)
}
RUNNER="$(ls "$APP_DIR"/target/*-runner 2>/dev/null | head -n1 || true)"
INPUTS="$(fingerprint)"
if [ -z "$RUNNER" ] || [ ! -f "$STAMP" ] || [ "$(cat "$STAMP")" != "$INPUTS" ]; then
echo "building the native runner"
(cd "$REPO_ROOT" && ./mvnw -q package -Pnative -pl trailhand -am)
echo "$INPUTS" > "$STAMP"
else
echo "native runner is current: $RUNNER"
fi
docker build -q -f "$APP_DIR/src/main/docker/Dockerfile.native" \
--build-arg APP_VERSION=it --build-arg APP_REVISION="$(git -C "$REPO_ROOT" rev-parse --short HEAD)" \
-t trailhand:it "$APP_DIR" >/dev/null
echo "image trailhand:it built"
40 changes: 40 additions & 0 deletions integration-tests/scripts/generate-certificates.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
#!/usr/bin/env bash
#
# Copyright © 2026-present CUI-OpenSource-Software (info@cuioss.de)
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Generates the TLS material of the stack into target/certificates (never committed): one self-signed key pair
# (PEM) for Keycloak and TrailHand with the names they are reached under, and a PKCS#12 trust store holding the
# certificate, with which TrailHand trusts Keycloak.
set -euo pipefail
source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"

CERT_DIR="$TARGET_DIR/certificates"
# A complete set is reused; a missing file regenerates all of them, so key, certificate and trust store match.
if [ -f "$CERT_DIR/tls.key" ] && [ -f "$CERT_DIR/tls.crt" ] && [ -f "$CERT_DIR/truststore.p12" ]; then
echo "certificates present in $CERT_DIR"
exit 0
fi
mkdir -p "$CERT_DIR"
openssl req -x509 -newkey rsa:2048 -nodes -days 30 -sha256 \
-subj "/CN=localhost" \
-addext "subjectAltName=DNS:localhost,DNS:keycloak,DNS:trailhand,IP:127.0.0.1" \
-keyout "$CERT_DIR/tls.key" -out "$CERT_DIR/tls.crt" 2>/dev/null
# Read by the containers' non-root users; the material is test-only and lives in target/.
chmod 644 "$CERT_DIR/tls.key" "$CERT_DIR/tls.crt"
rm -f "$CERT_DIR/truststore.p12"
keytool -importcert -noprompt -alias trailhand-it -file "$CERT_DIR/tls.crt" \
-keystore "$CERT_DIR/truststore.p12" -storetype PKCS12 -storepass trailhand-it >/dev/null
chmod 644 "$CERT_DIR/truststore.p12"
echo "certificates written to $CERT_DIR"
Loading