Testing

Vertique provides test extensions for exercising a complete application, a REST mount, a real database or Kafka broker, and generated code.

• Application tests. Boot your application once per test class, supply its configuration, and let the extension await startup and shutdown.
• Focused integration tests. Exercise REST resources with the framework’s routing and middleware, or connect your own test fixtures to PostgreSQL and Kafka.
• Code-generation tests. Compile source fixtures with annotation processors, check diagnostics, and load the generated classes to test their behavior.

Use the smallest fixture that covers the behavior you need to prove. Plain unit tests can exercise your own logic without a running application. Use the application extension when startup, component wiring, or the complete HTTP server matters; use the focused fixtures for individual integrations. The Quickstart shows how to run a generated application’s tests.

Choose a test extension

These are the framework’s five public test-support modules. Add the modules you need as test-scoped dependencies; they are separate from the application’s runtime dependencies.

Test subject	Module	Main support
Complete application	Application test	VertiqueAppExtension
REST resources and middleware	REST test	RestTestFixtureModule, RestTestMounts
PostgreSQL repositories and migrations	Database test	PostgresContainer, DatabaseExtension
Kafka producers and consumers	Kafka test	KafkaTestContainers
Annotation processors and generated code	Code generation test	ProcessorTestHarness, SourceFiles

Application tests

VertiqueAppExtension starts the application from its generated component factory and shuts it down after the test class. Register it as a static final JUnit 5 extension. This excerpt from the REST archetype’s generated ApplicationIT shows configuration and port discovery; the management-server configuration and test methods are omitted:

@RegisterExtension
static final VertiqueAppExtension app = VertiqueAppExtension
        .forFactory(new AppComponentVertiqueComponentFactory())
        .withConfig(new JsonObject()
                .put("http", new JsonObject().put("port", 0).put("host", "127.0.0.1")));

@BeforeAll
static void setUp() {
    RestAssured.baseURI = "http://127.0.0.1";
    RestAssured.port = app.httpPort();
}

@AfterAll
static void tearDown() {
    RestAssured.reset();
}

Port 0 lets the operating system choose a free port; app.httpPort() returns the bound port after startup. The extension owns the Vert.x instance it creates. If you supply an instance with withVertx, your test owns closing it. RestAssured’s global configuration is separate test state; avoid changing it concurrently across test classes.

Use this fixture for application lifecycle and wiring, or server behavior such as multiple mounts and HTTP server configuration. The Application test reference documents configuration, startup timeouts, teardown, and component access.

REST tests

vertique-rest-test assembles a single JAX-RS mount using the real encoders, exception mappers, and middleware. Include RestTestFixtureModule in a test Dagger component and use RestTestContributions to add test middleware or other supported collaborators.

Choose the security wiring explicitly: RestTestNoSecurityModule supplies the no-security binding, while AuthModule enables the real startup security-policy checks. Include exactly one. If the graph has no request-validation module, set jaxrs.validationStrategy to none.

RestTestMounts.startServer starts an HTTP server on an ephemeral loopback port with both ROOT and API middleware. Your test closes the server and its supplied Vert.x instance. The fixture covers one mount; use the application extension for server options, mount ordering, and server customization. See the REST test reference for a complete component and fixture setup.

Database tests

vertique-db-test supplies PostgresContainer and the JUnit 5 DatabaseExtension. The extension starts and closes static database-container fields for a test class. Docker must be available. After startup, use toPoolConfig() to connect the repository or SQL pool under test.

The no-argument PostgresContainer provisions a separate database on a server shared within the test JVM. Use unique test data within a class, and use the dedicated-container constructor when the test needs cluster-level isolation. withMigration() runs Flyway migrations during fixture startup and requires vertique-db-flyway on the test classpath.

For a whole-application test, start the database before the application and pass its connection settings into the application configuration. Choose whether the fixture or the application owns migration execution. See Persistence for application wiring and the Database test reference for fixture lifecycle and isolation.

Kafka tests

vertique-kafka-test supplies a real Kafka broker shared within the test JVM. Docker must be available. KafkaTestContainers.shared() starts the broker on first use and verifies metadata access and consumer-group readiness before returning it.

This setup comes from the Kafka test reference:

static final KafkaContainer kafka = KafkaTestContainers.shared();

String bootstrapServers = kafka.getBootstrapServers();

Use the bootstrap servers in your producer or consumer configuration. Give test scenarios their own topic and consumer-group names. Close the clients your test creates, but do not stop the shared broker; Testcontainers cleans it up when the JVM exits. The module reference documents startup probes, retry limits, and broker lifecycle.

Code-generation tests

vertique-codegen-test supplies ProcessorTestHarness for testing annotation processors. Create Java source fixtures with SourceFiles.inline, run them through your processors, and assert compilation success or expected diagnostics. You can also inspect generated source and load generated classes to test their behavior.

Use this when developing a processor or a framework extension that generates code. It does not start an application or require Docker. The Code generation test reference contains complete examples for compilation failures, processor options, and generated-class tests.

Add test dependencies

With the Vertique BOM imported as described in Artifacts, add each selected module to your application’s pom.xml in test scope. For example, the application harness uses:

<dependency>
    <groupId>dev.vertique</groupId>
    <artifactId>vertique-application-test</artifactId>
    <scope>test</scope>
</dependency>

Your build determines when tests run. Generated applications run their ApplicationIT through Maven Failsafe. From the generated application’s root directory, run:

mvn -ntp verify -Dit.test=ApplicationIT

Expect BUILD SUCCESS and no failed integration tests. The fixture you choose does not configure Surefire or Failsafe for you; the Quickstart covers the generated build setup.

Learn more

• Generated REST application test source: complete source for the application-harness excerpt above.
• Application model: startup, component wiring, and shutdown.
• REST APIs, Persistence, and Messaging with Kafka: the capabilities exercised by the integration fixtures.
• Code generation: annotation processors and generated application wiring.

Continue reading

• Previous: Security
• Next: Observability