Checkmate

A single-module test toolkit that provides reusable test utilities for Java and Kotlin Spring Boot projects, covering:

• shared architecture rules,
• marker annotations,
• Testcontainers helpers,
• and Spring/Kafka test utilities.

This project is a personal experiment and might become abandoned at any time.

Table of Contents

• Getting Started
• Annotations
• ArchUnit rules
• Testcontainers
• Spring Kafka

Getting Started

Project is not published to a public repository. To access it, generate a GitHub personal access token with read:packages scope and configure your Gradle project as follows. Browse https://github.com/settings/tokens to create a new token.

# ~/.gradle/gradle.properties - global Gradle properties to avoid accidental commit of credentials
#                               to version control
#
gpr.user={your GitHub username}
gpr.token={your GitHub personal access token with read:packages scope}

// build.gradle.kts
//
repositories {
    mavenCentral()
    maven {
        url = uri("https://maven.pkg.github.com/malczuuu/checkmate")
        credentials {
            username = project.findProperty("gpr.user")?.toString() ?: System.getenv("GPR_USER")
            password = project.findProperty("gpr.token")?.toString() ?: System.getenv("GPR_TOKEN")
        }
    }
}

// verify CHANGELOG.md for latest version
dependencies {
    testImplementation("io.github.malczuuu:checkmate:0.0.6")
}

Building requires Java 25. Usage requires Java 17 or later.

@ContainerTest
@SpringBootTest
internal class OrderProcessingTests : KafkaAwareTest {

    @TestListener("orders")
    private lateinit var ordersConsumer: TestKafkaConsumer

    @TestListener("notifications")
    private lateinit var notificationsConsumer: TestKafkaConsumer

    @BeforeEach
    fun beforeEach() {
        ordersConsumer.clear()
        notificationsConsumer.clear()
    }

    @Test
    fun givenOrder_whenProcessed_thenNotificationSent() {
        // publish to "orders" topic ...

        await().atMost(Duration.ofSeconds(10)).untilAsserted {
            assertThat(notificationsConsumer.poll(Duration.ofMillis(500))).isNotEmpty()
        }
    }
}

Annotations

Marker annotations in io.github.malczuuu.checkmate.annotation.

Annotation	Target	Purpose
@ContainerTest	class	Applies the testcontainers JUnit tag so container-backed tests can be included/excluded from a build via -Pcontainers.enabled.
@TestListener	field	Declares a field as a consumer of a messaging destination. The framework wires the appropriate consumer bean and injects it before each test.

ArchUnit rules

Shared ArchUnit rules in io.github.malczuuu.checkmate.archunit that can be imported into any test suite to enforce project-wide conventions.

Testcontainers

Interfaces in io.github.malczuuu.checkmate.container that expose pre-configured, shared Testcontainer singletons. Implementing one of these interfaces in a Spring Boot test class is enough for Spring auto-configuration to pick up the container's connection details via @ServiceConnection.

Interface	Container image
KafkaAwareTest	apache/kafka:4.2.0
MongoAwareTest	mongo:8.2-alpine
PostgresAwareTest	postgres:18.3-alpine

Container-gated tests must be tagged with @ContainerTest.

By default, the interfaces above use the image names shown in the table. Image resolution can be overridden via the ImageNamePlugin SPI (io.github.malczuuu.checkmate.spi.ImageNamePlugin).

1. Implement the interface in your test sources.

   public class MirrorRegistryPlugin implements ImageNamePlugin {
   
     @Override
     public Optional<String> getImageName(String service) {
       return switch (service) {
         case "kafka"    -> Optional.of("registry.example.com/mirror/apache/kafka:4.2.0");
         case "mongo"    -> Optional.of("registry.example.com/mirror/mongo:8.2-alpine");
         case "postgres" -> Optional.of("registry.example.com/mirror/postgres:18.3-alpine");
         default         -> Optional.empty();
       };
     }
   }

2. Register the implementation via the standard ServiceLoader mechanism.

   Create src/test/resources/META-INF/services/io.github.malczuuu.checkmate.spi.ImageNamePlugin containing the FQCN:

   com.example.MirrorRegistryPlugin
   

The loader is a lazy singleton: plugins are discovered once on first access and the resolved image names are cached per service key. If you register multiple plugins for the same service, the one with the lowest value in getPriority() takes precedence.

Spring Kafka

Extensions in io.github.malczuuu.checkmate.spring.kafka for the Spring test context that automate the setup of in-process Kafka consumers during integration tests.

• TestKafkaConsumer - interface for polling and draining a Kafka topic from test code.
• @TestListener - annotate a TestKafkaConsumer field in your test class with the target topic name; the framework registers the consumer bean and injects it automatically.

Maintenance

1. Releases are published to GitHub Packages on tags following the v{version} pattern, e.g. v0.0.1.
2. Make sure to configure the GPR_USER and GPR_TOKEN secrets if tokens expire at (link). Use repo and write:packages scopes.