Garland on Garland — Java Integration Testing Framework

How to create test DTOs

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

Before writing pipeline tests you need test DTOs — classes that mirror your production types but are shaped for test use. This page explains what to create and why.

Step 1 — Locate the production DTO
#

Start in the service source. Find the DTO your endpoint accepts and returns:

// user-service/src/main/java/.../dto/UserDto.java
public record UserDto(
        UUID uuid,
        String name,
        String surname,
        AddressDto address,
        List<CarDto> cars,
        LocalDateTime createdAt,
        LocalDateTime modifiedAt
) {}

Note the field types — you will recreate this as a test DTO with the same fields but a different class form.

Quick Start

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

If you want to see working tests before reading anything, clone the demo and run it first — it covers everything described here against a real stack:

Try the demo in 5 minutes

Otherwise, keep reading to understand the setup step by step.

Requirements
#

Java 17+
Maven 3.8+

Add dependencies
#

Add the modules you need to your test pom.xml:

How to test HTTP endpoints with Garland

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

This page covers how to test HTTP endpoints with HttpTestClient — from a basic status assertion to auth failures and validation error checking. All examples are taken from garland-demo and run against the real stack — clone it to see them execute.

These examples assume test DTOs are already in place. If you are starting from scratch, read How to create test DTOs first.

Assert status and deserialize the response
#

The most common pattern. makeCall asserts the status code and deserializes the response body in one step:

Try it in 5 minutes

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

Clone the demo project and run the full test suite against a real stack — no configuration needed beyond Docker.

Requirements
#

Java 17+
Maven 3.8+
Docker

Run
#

git clone https://github.com/garlandframework/garland-demo
cd garland-demo
docker-compose up -d
mvn test -pl tests

docker-compose up -d starts PostgreSQL, Kafka, and MongoDB. Maven runs the full suite against two Spring Boot microservices — user-service and projection-service — that are bundled in the repo.

How to test HTTP → PostgreSQL with Garland

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

This page walks through the full setup for asserting that an HTTP call persisted the correct data in PostgreSQL — from reading production classes through to a working pipeline test. All examples are taken from garland-demo; clone it to run them.

This guide assumes test DTOs are already set up. If not, read How to create test DTOs first.

Step 1 — Locate the entity
#

Find the JPA entity that maps to the table your service writes to:

Why I Built Garland

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

How it started
#

The story of this framework started the day I was laid off from the company I worked at. I was asked to train AI to write automated integration tests, and then one day I just lost access to company resources, the repo, all of it. The company decided they didn’t need me anymore.

Was the AI good enough to make my role less necessary? Probably, at least partly. Was it also just bad timing — budget cuts, restructuring, the usual reasons companies give? Probably that too. Nobody gave me a percentage. I just got a layoff.

Garland 1.0.1

Mon, 15 Jun 2026 00:00:00 +0000

What changed
#

Java 17 support. Garland now requires Java 17 as the minimum version. The previous requirement of Java 21 has been dropped — all modules compile and run on Java 17+.

No API changes. Existing tests require no modifications.

Maven Central
#

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

Requires Java 17.

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.

Generate Java Integration Tests with AI

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

The demo ships with Claude Code slash commands that generate Garland tests. The orders domain — a fully implemented API with no tests — is the blank canvas to practice with.

What you need
#

Claude Code CLI or IDE extension (VS Code / JetBrains)
The demo project open as your working directory

The generation commands are pre-installed in the repo at .claude/commands/. Claude Code picks them up automatically.

How to Run Tests

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

Prerequisites
#

Java 17+
Maven 3.8+
Docker and Docker Compose

Start the stack
#

git clone https://github.com/garlandframework/garland-demo
cd garland-demo
docker-compose up -d --build

This builds and starts both Spring Boot services alongside PostgreSQL, Kafka, and MongoDB. Wait about 15 seconds for services to be ready.

Swagger UI — explore the APIs once the stack is running:

Support layer

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

The support layer lives in tests/src/test/java/dev/garlandframework/demo/tests/support/. It contains everything the test classes depend on but does not itself contain any test methods.

Connections
#

Connections.java is the single place that holds all infrastructure coordinates — service URLs, database credentials, Kafka topic names. Test classes never hardcode URLs or credentials; they reference constants from this class.

public static final String USER_SERVICE_URL       = "http://localhost:8080";
public static final String PROJECTION_SERVICE_URL = "http://localhost:8081";

public static final String PG_URL      = "jdbc:postgresql://localhost:5432/userdb?TimeZone=UTC";
public static final String PG_USERNAME = "user";

public static final String KAFKA_BOOTSTRAP_SERVERS  = "localhost:9092";
public static final String KAFKA_TOPIC_USER_CREATED = "user.created";
public static final String KAFKA_TOPIC_USER_UPDATED = "user.updated";
public static final String KAFKA_TOPIC_USER_DELETED = "user.deleted";

public static final String MONGO_CONNECTION_STRING = "mongodb://localhost:27017";
public static final String MONGO_DATABASE          = "projectiondb";

Centralizing this means changing the target environment is a one-file edit.

Test layers

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

The demo suite is organized into four layers. Each layer tests a different slice of the system and answers a different question. Tests live in tests/src/test/java/dev/garlandframework/demo/tests/.

Layer	Package	Question
Endpoint	`users/endpoint/`	Does this endpoint behave correctly in isolation?
Flow	`users/flow/`	Are state transitions within one service consistent?
Component	`users/component/`	Does this service boundary work end-to-end?
E2E	`UserEndToEndTest`	Does the full system chain hold together?

Endpoint tests
#

One test class per endpoint. Each class covers the happy path plus all validation and error cases for that endpoint. Fast to run, narrow in scope — a failure here points directly to the endpoint and nothing else.

Garland 1.0.0

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

First public release of Garland — type-safe pipeline composition for Java integration testing.

Modules
#

garland-core — Pipeline DSL, Step, PipelineContext, Verify, Retry
garland-http — HttpTestClient with makeCall, pollingCall, auth, query params, form/multipart body
garland-postgres — PostgresTestClient with findById, findByFields, countByFields, notExistsById
garland-kafka — KafkaTestClient with consumeMatching, publish, warmup
garland-mongodb — MongoTestClient with findById, findByFields, exists, notExists
garland-testng — AbstractMtoBaseTest, TestNGLogger, ResourceTracker
garland-bom — Bill of materials for centralized version management

Maven Central
#

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

Requires Java 17.

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.

Garland on Garland — Java Integration Testing Framework

How to create test DTOs

Step 1 — Locate the production DTO #

Quick Start

Requirements #

Add dependencies #

How to test HTTP endpoints with Garland

Assert status and deserialize the response #

Try it in 5 minutes

Requirements #

Run #

How to test HTTP → PostgreSQL with Garland

Step 1 — Locate the entity #

Why I Built Garland

How it started #

Garland 1.0.1

What changed #

Maven Central #

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 #

Generate Java Integration Tests with AI

What you need #

How to Run Tests

Prerequisites #

Start the stack #

Support layer

Connections #

Test layers

Endpoint tests #

Garland 1.0.0

Modules #

Maven Central #

garland-core — Pipeline, Verify & Retry

Pipeline as a chain of typed functions #

garland-http — Test REST APIs in Java

How a call works #

Step 1 — Locate the production DTO
#

Requirements
#

Add dependencies
#

Assert status and deserialize the response
#

Requirements
#

Run
#

Step 1 — Locate the entity
#

How it started
#

What changed
#

Maven Central
#

How consuming works
#

Setup
#

Setup
#

How a query works
#

AbstractGarlandBaseTest
#

What you need
#

Prerequisites
#

Start the stack
#

Connections
#

Endpoint tests
#

Modules
#

Maven Central
#

Pipeline as a chain of typed functions
#

How a call works
#