Skip to main content

​
Overview

This guide will walk you through creating a complete integration test using TNB. You’ll write a test that automatically deploys Kafka, produces messages, consumes them, and validates the results.

​
Prerequisites

  • Java 17 or higher
  • Maven 3.6+
  • Basic familiarity with JUnit 5

​
Create your first test

1

Add TNB dependency

Add the TNB Kafka service to your pom.xml:
pom.xml
<dependency>
    <groupId>software.tnb</groupId>
    <artifactId>system-x-kafka</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>test</scope>
</dependency>
See the installation guide for more dependency options including BOM imports.
2

Create the test class

Create a new JUnit 5 test class:
KafkaTest.java
import software.tnb.common.service.ServiceFactory;
import software.tnb.kafka.service.Kafka;
import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.RegisterExtension;
import java.util.List;

public class KafkaTest {
    @RegisterExtension
    public static Kafka kafka = ServiceFactory.create(Kafka.class);

    @Test
    public void testWithKafka() {
        final String topic = "myTopic";
        final String message = "Hello kafka!";
        kafka.validation().produce(topic, message);

        final List<ConsumerRecord<String, String>> records = kafka.validation().consume(topic);
        Assertions.assertEquals(1, records.size());
        Assertions.assertEquals(message, records.get(0).value());
    }
}
3

Run the test

Execute your test using Maven:
mvn test
TNB will automatically:
  1. Pull the Kafka Docker image
  2. Start a Kafka container with Zookeeper
  3. Wait for Kafka to be ready
  4. Run your test
  5. Stop and remove the container

​
What’s happening

Let’s break down the test code:

​
Service creation

@RegisterExtension
public static Kafka kafka = ServiceFactory.create(Kafka.class);
The ServiceFactory.create() method:
  • Determines the deployment environment (local by default)
  • Creates the appropriate service implementation
  • Registers JUnit 5 lifecycle hooks for automatic deployment
The service field must be static and annotated with @RegisterExtension to work with JUnit 5’s extension model.

​
Validation API

kafka.validation().produce(topic, message);
The validation object provides convenient methods for common operations:
  • produce(topic, message) - Sends a message to a Kafka topic
  • consume(topic) - Polls all messages from a topic
  • Both methods handle the complexity of Kafka producers/consumers internally

​
Service lifecycle

TNB manages the service lifecycle automatically:
1

Before all tests

The @BeforeAll hook:
  • Deploys the Kafka container
  • Waits for Kafka to be ready
  • Opens client connections
2

During tests

Your test code:
  • Uses the validation API to interact with Kafka
  • Performs assertions on results
3

After all tests

The @AfterAll hook:
  • Closes client connections
  • Stops the Kafka container
  • Cleans up resources

​
Testing with multiple services

You can use multiple services in a single test:
MultiServiceTest.java
import software.tnb.common.service.ServiceFactory;
import software.tnb.kafka.service.Kafka;
import software.tnb.postgresql.service.PostgreSQL;
import org.junit.jupiter.api.extension.RegisterExtension;

public class MultiServiceTest {
    @RegisterExtension
    public static Kafka kafka = ServiceFactory.create(Kafka.class);
    
    @RegisterExtension
    public static PostgreSQL database = ServiceFactory.create(PostgreSQL.class);

    @Test
    public void testKafkaToDatabase() {
        // Produce to Kafka
        kafka.validation().produce("events", "user-signup");
        
        // Verify in database
        // (your application logic would process Kafka -> DB)
        database.validation().query("SELECT * FROM events");
    }
}

​
Switching to OpenShift

To run the same test on OpenShift instead of locally: 
mvn test -Dtest.use.openshift=true
TNB will automatically:
  • Deploy Kafka as an OpenShift deployment
  • Create routes for external access
  • Run your tests against the cluster deployment
OpenShift deployment requires cluster access and proper credentials configured.

​
Customizing services

Some services support configuration: 
import software.tnb.splunk.service.Splunk;
import software.tnb.splunk.service.configuration.SplunkProtocol;

@RegisterExtension
public static Splunk splunk = ServiceFactory.create(
    Splunk.class, 
    config -> config.protocol(SplunkProtocol.HTTP)
);

​
Next steps

Core concepts

Learn about accounts, clients, and validation objects

Available services

Explore all 50+ supported System-X services

Configuration

Configure service images, credentials, and deployment options

Camel testing

Test Apache Camel applications with TNB

Build docs developers (and LLMs) love

Get started for freeTalk to us