or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

http-testing.mdindex.mdlaunchers.mdtest-annotations.mdtest-context.mdtest-resources.mdutilities.md
tile.json

tessl/maven-io-quarkus--quarkus-test-common

Common test utilities and framework for Quarkus applications, providing core testing infrastructure including application launchers, test isolation, configuration management, and integration with REST Assured for HTTP testing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-test-common@3.26.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-test-common@3.26.0

index.mddocs/

Quarkus Test Common

Common test utilities and framework for Quarkus applications, providing core testing infrastructure including application launchers, test isolation, configuration management, and integration with REST Assured for HTTP testing. This library serves as the foundational layer for the Quarkus test framework ecosystem, enabling comprehensive testing of Quarkus applications across different deployment modes and runtime environments.

Package Information

  • Package Name: quarkus-test-common
  • Package Type: maven
  • Group ID: io.quarkus
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-test-common</artifactId>
    <version>3.26.2</version>
    <scope>test</scope>
</dependency>

Core Imports

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
import io.quarkus.test.common.http.TestHTTPResource;
import io.quarkus.test.common.http.TestHTTPEndpoint;

Common test annotations:

import io.quarkus.test.Mock;
import io.quarkus.test.InjectMock;
import io.quarkus.test.TestTransaction;
import io.quarkus.test.TestReactiveTransaction;
import io.quarkus.test.ActivateSessionContext;
import io.quarkus.test.common.WithTestResource;
import io.quarkus.test.common.TestResourceScope;

Basic Usage

import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.common.QuarkusTestResourceLifecycleManager;
import io.quarkus.test.common.http.TestHTTPResource;
import io.quarkus.test.Mock;
import io.quarkus.test.InjectMock;
import org.junit.jupiter.api.Test;

// Define a test resource for external dependencies
@QuarkusTestResource(DatabaseTestResource.class)
public class MyServiceTest {
    
    @TestHTTPResource("/api/users")
    URL usersEndpoint;
    
    @InjectMock
    MyService mockService;
    
    @Test
    public void testUserEndpoint() {
        // Test implementation using injected HTTP resource and mock
        // The database test resource is automatically managed
    }
}

// Example test resource implementation
public class DatabaseTestResource implements QuarkusTestResourceLifecycleManager {
    @Override
    public Map<String, String> start() {
        // Start test database container
        return Map.of("quarkus.datasource.jdbc.url", "jdbc:testcontainers:postgresql://...");
    }
    
    @Override
    public void stop() {
        // Clean up resources
    }
}

Architecture

The Quarkus test framework is built around several key components:

  • Test Resource Management: Sophisticated lifecycle management for external dependencies (databases, message brokers, etc.) with scoping control
  • HTTP Testing Support: Automatic URL injection and endpoint configuration for REST API testing
  • Test Annotations: Core annotations for mocking, transactions, and session context management
  • Launcher Infrastructure: Support for testing different artifact types (JVM, native, container)
  • Utility Classes: Helper classes for path mapping, system properties, and test context management

This design enables comprehensive testing of Quarkus applications with automatic resource management, simplified HTTP endpoint testing, and support for various runtime environments including native compilation and containerized deployments.

Capabilities

Test Resource Management

Comprehensive lifecycle management for external test dependencies like databases, message brokers, and external services. Supports sophisticated scoping strategies and parallel resource startup.

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(QuarkusTestResource.List.class)
public @interface QuarkusTestResource {
    Class<? extends QuarkusTestResourceLifecycleManager> value();
    ResourceArg[] initArgs() default {};
    boolean parallel() default false;
    boolean restrictToAnnotatedClass() default false;
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(WithTestResource.List.class)
public @interface WithTestResource {
    Class<? extends QuarkusTestResourceLifecycleManager> value();
    ResourceArg[] initArgs() default {};
    boolean parallel() default false;
    TestResourceScope scope() default TestResourceScope.MATCHING_RESOURCES;
}

public enum TestResourceScope {
    RESTRICTED_TO_CLASS,    // Complete isolation, restart for each test
    MATCHING_RESOURCES,     // Restart only when resources differ  
    GLOBAL                  // Apply to all tests in suite
}

public interface QuarkusTestResourceLifecycleManager {
    Map<String, String> start();
    void stop();
    default void setContext(Context context) {}
    default void init(Map<String, String> initArgs) {}
    default void inject(Object testInstance) {}
    default void inject(TestInjector testInjector) {}
    default int order() { return 0; }
}

Test Resource Management

HTTP Testing Support

Specialized support for HTTP endpoint testing with automatic URL injection and endpoint configuration. Integrates seamlessly with REST Assured and other HTTP testing libraries.

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface TestHTTPResource {
    String value() default "";
    @Deprecated(since = "3.10", forRemoval = true)
    boolean ssl() default false;
    boolean tls() default false;
    boolean management() default false;
}

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})  
@Retention(RetentionPolicy.RUNTIME)
public @interface TestHTTPEndpoint {
    Class<?> value();
}

HTTP Testing

Core Test Annotations

Essential annotations for mocking, transaction management, and session context control in Quarkus tests.

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Stereotype
public @interface Mock {}

@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface InjectMock {}

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@InterceptorBinding
public @interface TestTransaction {}

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@InterceptorBinding
public @interface TestReactiveTransaction {}

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@InterceptorBinding
public @interface ActivateSessionContext {}

Test Annotations

Launcher Infrastructure

Interfaces and implementations for launching and managing different types of Quarkus artifacts during testing, including JVM, native, and containerized deployments.

public interface ArtifactLauncher<T> extends Closeable {
    void init(T initContext);
    void start() throws IOException;
    LaunchResult runToCompletion(String[] args);
    void includeAsSysProps(Map<String, String> systemProps);
    boolean listensOnSsl();
    void close() throws IOException;
}

public static class LaunchResult {
    public LaunchResult(int statusCode, byte[] output, byte[] stderror) {}
    public int getStatusCode() {}
    public byte[] getOutput() {}
    public byte[] getStderror() {}
}

Launcher Infrastructure

Test Context and Status

Access to test execution context, Dev Services properties, and test failure status for advanced test scenarios and resource cleanup.

public class TestStatus {
    public TestStatus(Throwable testErrorCause) {}
    public Throwable getTestErrorCause() {}
    public boolean isTestFailed() {}
}

public interface DevServicesContext {
    Map<String, String> devServicesProperties();
    Optional<String> containerNetworkId();
}

Test Context

Utilities

Helper classes for common testing scenarios including path mapping, system property management, and annotation processing.

public class RestorableSystemProperties implements Closeable {
    public static RestorableSystemProperties setProperties(
        Map<String, String> props, 
        String... additionalKeysToSave
    ) {}
    public void close() {}
}

public class PathTestHelper {
    public static Path getTestClassesLocation(Class<?> testClass) {}
    public static Path getAppClassLocationForTestLocation(Path testClassLocationPath) {}
    public static boolean isTestClass(String className, ClassLoader classLoader, Path testLocation) {}
}

Utilities

Types

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME) 
public @interface ResourceArg {
    String name();
    String value();
}

public enum TestResourceScope {
    RESTRICTED_TO_CLASS,
    MATCHING_RESOURCES, 
    GLOBAL
}

public class ListeningAddress {
    public ListeningAddress(Integer port, String protocol) {}
    public Integer getPort() {}
    public String getProtocol() {}
    public boolean isSsl() {}
}