Module Reference on Garland — Java Integration Testing Framework

garland-kafka — Assert Kafka Events in Java

Wed, 10 Jun 2026 00:00:00 +0000

garland-kafka provides KafkaTestClient — a Kafka consumer and producer wrapped into pipeline steps. It subscribes to one or more topics, retries until the expected event arrives, and asserts the deserialized content. A publish step is included for tests that drive the system via Kafka rather than HTTP.

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-kafka</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

How consuming works
#

flowchart TD
    expected["Expected event\n(input from pipeline)"]
    poll["Poll Kafka topic"]
    deser["Deserialize record\nJSON → EventDto"]
    match["Assert event matches expected\nnull fields ignored"]
    retry["Retry — poll next record"]
    event["Event\n✓ returned to pipeline"]

    expected -->|"consumeMatching()"| poll
    poll --> deser
    deser --> match
    match -->|"no match"| retry
    retry --> poll
    match -->|"matched"| event

    style expected fill:#f5f5f5,stroke:#999
    style event fill:#d4edda,stroke:#28a745
    style retry fill:#fff3cd,stroke:#ffc107

Setup
#

KafkaTestClient kafka = new KafkaTestClient(
        KafkaConfig.builder()
                .bootstrapServers("localhost:9092")
                .topic("user.created")
                .topic("user.updated")
                .topic("user.deleted")
                .groupId(UUID.randomUUID().toString())
                .build(),
        RetryConfig.of(5, Duration.ofSeconds(2))
).withTemporalTolerance(Duration.ofMillis(1));

Always use a random UUID for groupId — reusing a group ID across suite runs causes the consumer to resume from a previous offset and pick up stale events.

garland-mongodb — Assert MongoDB Documents in Java

Wed, 10 Jun 2026 00:00:00 +0000

garland-mongodb provides MongoTestClient — a MongoDB-backed client that produces steps for asserting document state inside pipelines. Its API mirrors garland-postgres exactly: the same methods (findById, findByFields, countByFields, existsById, notExistsById, persist, delete) with the same semantics — only the store and configuration differ.

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-mongodb</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

Setup
#

MongoWrapper mongo = new MongoWrapper(
        MongoConfig.builder()
                .connectionString("mongodb://localhost:27017")
                .database("mydb")
                .collection(UserProjectionDoc.class, "users")
                .collection(OrderProjectionDoc.class, "order_projections")
                .build()
);

MongoTestClient db = new MongoTestClient(mongo, RetryConfig.of(10, Duration.ofSeconds(2)))
        .withTemporalTolerance(Duration.ofMillis(1));

Each document class must be mapped to its MongoDB collection name via .collection(Class, String). An unmapped class causes an IllegalArgumentException at query time, not at construction. The ID field is resolved by field name "id" or any field annotated @Id.

garland-postgres — Assert PostgreSQL State in Java

Wed, 10 Jun 2026 00:00:00 +0000

garland-postgres provides PostgresTestClient — a Hibernate-backed client that produces steps for asserting database state inside pipelines. It holds connection configuration and retry policy, and exposes methods like findById, findByFields, and countByFields that each return a Step ready to be passed to .then().

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-postgres</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

How a query works
#

findById and findByFields do everything in one step: look up the row, wait for it to appear (retry), and assert the entity matches the expected value.

garland-testng — TestNG Base Class for Integration Tests

Wed, 10 Jun 2026 00:00:00 +0000

garland-testng provides two classes that wire Garland into TestNG: AbstractGarlandBaseTest hooks ResourceTracker cleanup into @AfterMethod automatically, and TestNGLogger replaces TestNG’s default output with a structured, colored log that shows class hierarchy, pass/fail/skip indicators, and inline failure messages.

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-testng</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

AbstractGarlandBaseTest
#

Extend it in your base test class. It exposes registerTrackers(...) and attaches an @AfterMethod(alwaysRun = true) hook that calls cleanupAll on every registered tracker after each test, regardless of pass or fail.

garland-core — Pipeline, Verify & Retry

Tue, 09 Jun 2026 00:00:00 +0000

garland-core defines the primitives every other module is built on. It has no external dependencies beyond SLF4J for logging.

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-core</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

Pipeline as a chain of typed functions
#

A pipeline is a sequence of functions where the output type of each function becomes the input type of the next. The compiler enforces that adjacent steps are compatible — if types don’t connect, the code doesn’t compile.

garland-http — Test REST APIs in Java

Tue, 09 Jun 2026 00:00:00 +0000

garland-http provides HttpTestClient — a configured HTTP client that produces steps for use in pipelines. It holds configuration (base URL, default headers, retry policy) and exposes methods like makeCall, pollingCall, and downloadFile that each return a Step ready to be passed to .then().

<dependency>
    <groupId>dev.garlandframework</groupId>
    <artifactId>garland-http</artifactId>
    <version>1.0.1</version>
    <scope>test</scope>
</dependency>

How a call works
#

A single makeCall step does everything: sends the request, checks the status, deserializes the body, and optionally asserts the response matches an expected value.

Module Reference on Garland — Java Integration Testing Framework

garland-kafka — Assert Kafka Events in Java

How consuming works #

Setup #

garland-mongodb — Assert MongoDB Documents in Java

Setup #

garland-postgres — Assert PostgreSQL State in Java

How a query works #

garland-testng — TestNG Base Class for Integration Tests

AbstractGarlandBaseTest #

garland-core — Pipeline, Verify & Retry

Pipeline as a chain of typed functions #

garland-http — Test REST APIs in Java

How a call works #

How consuming works
#

Setup
#

Setup
#

How a query works
#

AbstractGarlandBaseTest
#

Pipeline as a chain of typed functions
#

How a call works
#