Building and Testing

Building and Testing

---

1. Toolchain

Requirement	Version
JDK	25 (use the toolchain, not a system default)
Gradle	9.6.1 — use the wrapper, ./gradlew
Spring Boot	4.1.0 (applied in evento-server/build.gradle)
Docker Desktop	Only for the JDBC integration tests

Other pinned versions, from the root build.gradle at 2.4.0: Jackson 2.22.1, Netty 4.2.16.Final, Flyway 13.0.0, HikariCP 7.1.0, Micrometer 1.13.6, JUnit 5.11.4, Testcontainers 1.21.3, Jazzer 0.30.0.

On macOS:

export JAVA_HOME=$(/usr/libexec/java_home -v 25)

Versions are centralised in the root build.gradle under allprojects { ext { … } } — bump them there, not per module.

---

2. Build

JAVA_HOME=$(/usr/libexec/java_home -v 25) ./gradlew clean build -x test

For local publishing, copy the template and fill in your own credentials (the real file is gitignored):

cp gradle.properties.template gradle.properties

---

3. Core test suite

No Docker required:

JAVA_HOME=$(/usr/libexec/java_home -v 25) ./gradlew \
  :evento-transport-api:test \
  :evento-transport-netty:test \
  :evento-server:test --tests 'com.evento.server.bus.*' \
  :evento-common:test \
  :evento-bundle:test \
  :evento-lab:test \
  :evento-lab-microservices:evento-lab-ms-it:test

Add the JDBC module for the full sweep:

  :evento-consumer-state-store:evento-consumer-state-store-jdbc:test

---

4. JDBC integration tests

Postgres and MySQL via Testcontainers, gated behind an environment variable so a normal build does not require Docker:

EVENTO_RUN_JDBC_IT=true JAVA_HOME=$(/usr/libexec/java_home -v 25) \
  ./gradlew :evento-consumer-state-store:evento-consumer-state-store-jdbc:test

---

5. Coverage

./gradlew jacocoTestReport

Minimum 70% on new modules.

---

6. Test counts

Approximate, as of the v2.0.0-rc1 baseline on JDK 25:

Module	Tests
evento-transport-api	41+
evento-transport-netty	8 (7 IT + 1 chunking)
evento-server	76+ — includes an 80 MB large-payload round trip and 10 disconnect scenarios
evento-common	52 — consumer processor + in-memory SPI implementations
evento-bundle	7 — engine supervisor + admin handle
evento-lab	31 — 6 in-memory, 6 connectivity, 4 command RTT, 9 failure matrix, 2 projector retry, 2 stress, 2 consumer interceptor
evento-lab-ms-it	22 — consumer lifecycle, sagas, reconnect, order lifecycle, payment saga, notifications, multi-context, RTT/stress, command RTT
JDBC ITs	50+ — 23 scenarios × 2 dialects, gated

---

7. Test philosophy

Tests at the boundary. Integration tests use real TCP — NettyServerTransport plus a real BundleClient — not mocks. Mocks appear only as the in-memory transport test double.

This is why the failure matrix is meaningful: disconnects, reconnects, supersede races and backpressure are exercised against an actual socket, which is the only place those bugs live.

---

8. Integration-test harnesses

evento-lab — single-bundle

Class	Purpose
EmbeddedBroker	Spins up a real BusLifecycle on an ephemeral port
TestEventStoreBundleClient	In-process event journal: handles EventFetchRequest and EventLastSequenceNumberRequest; publishWithMetadata() injects metadata flags
CommandAwareEmbeddedBroker	EmbeddedBroker + CommandBrokerHandler + a TestGatewayClient factory
CommandAwareTestEventStore	Implements BrokerEventStore in memory for command round-trip tests
LabStore	Thread-safe in-memory singleton for cross-component assertions

evento-lab-microservices — multi-bundle

Class	Purpose
MsHarness	Starts multiple EventoBundle instances against a shared MsEmbeddedBroker
MsTestEventStore	Handles EventFetchRequest; publishWithContext() for context-aware filtering
MsCommandAwareEmbeddedBroker	Multi-bundle equivalent of CommandAwareEmbeddedBroker

Static singleton stores — OrderViewStore, MsSagaStore, MsObservedEvents — are the cross-bundle assertion surfaces within a single JVM.

The modules under test are evento-lab-ms-{api,command,query,saga,observer}, with the tests themselves in evento-lab-ms-it.

---

9. Test requirements for a PR

• All tests must pass before a PR is eligible for review.
• New features must include integration tests.
• Bug fixes must include a regression test.

---

See also

• Contributing and Conventions
• Consumer State Store § 6 — the JDBC IT matrix