Package ru.vyarus.dropwizard.guice.test.jupiter

Annotation Type TestDropwizardApp

  • @Retention(RUNTIME)
@Target(TYPE)
@ExtendWith(TestDropwizardAppExtension.class)
@Inherited
public @interface TestDropwizardApp
    Dropwizard app junit 5 extension. Runs complete dropwizard application. Useful for testing web endpoints.

    Extension may be declared on test class or on any nested class. When declared on nested class, applies to all lower nested classes (default junit 5 extension appliance behaviour). Multiple extension declarations (on multiple nested levels) is useless as junit will use only the top declared extension instance (and other will be ignored).

    Application started before all tests (before BeforeAll) and shut down after all tests (after AfterAll). If you need to restart application between tests then declare extension in RegisterExtension non-static field instead of annotation.

    Guice injections will work on test fields annotated with Inject or Inject (Injector.injectMembers(Object) applied on test instance). Guice AOP will not work on test methods (because test itself is not created by guice).

    Test constructor, lifecycle and test methods may use additional parameters:

    • Any declared (possibly with qualifier annotation or generified) guice bean
    • For not declared beans use Jit to force JIT binding (create declared bean with guice, even if it wasn't registered)
    • Specially supported objects:
      • Application or exact application class
      • ObjectMapper
      • ClientSupport for calling application web endpoints (or external urls). Also it provides actual application ports.

    Internally use DropwizardTestSupport.

    It is possible to apply extension manually using RegisterExtension and TestDropwizardAppExtension.forApp(Class) builder. For static field the behaviour would be the same as with annotation, for non-static field application will restart before each test method.

    Since:
    28.04.2020

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      java.lang.Class<? extends io.dropwizard.core.Application<?>> value  

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.Class<? extends TestClientFactory> clientFactory
      Custom client factory for ClientSupport object.
      java.lang.String config  
      java.lang.String[] configOverride
      Each value must be written as key: value.
      boolean debug
      Enables debug output for extension: used setup objects, hooks and applied config overrides.
      java.lang.Class<? extends GuiceyConfigurationHook>[] hooks
      Hooks provide access to guice builder allowing complete customization of application context in tests.
      boolean randomPorts
      Enables random ports usage.
      java.lang.String restMapping
      Specifies rest mapping path.
      boolean reuseApplication
      By default, new application instance is started for each test.
      java.lang.Class<? extends TestEnvironmentSetup>[] setup
      Environment support object is the simplest way to prepare additional objects for test (like database) and apply configuration overrides.

    • Element Detail

      • value

        java.lang.Class<? extends io.dropwizard.core.Application<?>> value
        Returns:
        application class

      • config

        java.lang.String config
        Returns:
        path to configuration file (optional)
        Default:
        ""

      • configOverride

        java.lang.String[] configOverride
        Each value must be written as key: value.

        In order to specify raw ConfigOverride values (for delayed evaluation) use direct extension registration with RegisterExtension instead of annotation.

        Returns:
        list of overridden configuration values (may be used even without real configuration)
        Default:
        {}

      • hooks

        java.lang.Class<? extends GuiceyConfigurationHook>[] hooks
        Hooks provide access to guice builder allowing complete customization of application context in tests.

        For anonymous hooks you can simply declare hook as field: @EnableHook static GuiceyConfigurationHook hook = builder -> builder.disableExtension(Something.class). Non-static fields may be used only when extension is registered with non-static field (static fields would be also counted in this case). All annotated fields will be detected automatically and objects registered. Fields declared in base test classes are also counted.

        Returns:
        list of hooks to use
        See Also:
        for more info, EnableHook
        Default:
        {}

      • randomPorts

        boolean randomPorts
        Enables random ports usage. Supports both simple and default dropwizard servers. Random ports would be set even if you specify exact configuration file with configured ports (option overrides configuration).

        To get port numbers in test use ClientSupport parameter in lifecycle or test method: 

        
 static beforeAll(ClientSupport client) {
     String baseUrl = "http://localhost:" + client.getPort();
     String baseAdminUrl = "http://localhost:" + client.getAdminPort();
 }
        Or use client target methods directly.
        Returns:
        true to use random ports
        Default:
        false

      • restMapping

        java.lang.String restMapping
        Specifies rest mapping path. This is the same as specifying configOverride() "server.rootMapping=/something/*". Specified value would be prefixed with "/" and, if required "/*" applied at the end. So it would be correct to specify restMapping = "api" (actually set value would be "/api/*").

        This option is only intended to simplify cases when custom configuration file is not yet used in tests (usually early PoC phase). It allows you to map servlet into application root in test (because rest is no more resides in root). When used with existing configuration file, this parameter will override file definition.

        Returns:
        rest mapping (empty string - do nothing)
        Default:
        ""

      • setup

        java.lang.Class<? extends TestEnvironmentSetup>[] setup
        Environment support object is the simplest way to prepare additional objects for test (like database) and apply configuration overrides. Provided classes would be instantiated with the default constructor.

        To avoid confusion with guicey hooks: setup object required to prepare test environment before test (and apply required configurations) whereas hooks is a general mechanism for application customization (not only in tests).

        Anonymous implementation could be simply declared as field: @EnableSetup static TestEnvironmentSetup ext = ext -> ext.configOverrides("foo:1"). Non-static fields may be used only when extension is registered with non-static field (static fields would be also counted in this case). All annotated fields will be detected automatically and objects registered. Fields declared in base test classes are also counted.

        Returns:
        setup objects to use
        See Also:
        EnableSetup
        Default:
        {}

      • debug

        boolean debug
        Enables debug output for extension: used setup objects, hooks and applied config overrides. Might be useful for concurrent tests too because each message includes configuration prefix (exactly pointing to context test or method).

        Configuration overrides are printed after application startup (but before the test) because overridden values are resolved from system properties (applied by DropwizardTestSupport.before()). If application startup failed, no configuration overrides would be printed (because dropwizard would immediately cleanup system properties). Using system properties is the only way to receive actually applied configuration value because property overrides might be implemented as value providers and potentially return different values.

        System property might be used to enable debug mode: -Dguicey.extensions.debug=true. Or alias in code: TestSupport.debugExtensions().

        Returns:
        true to enable debug output, false otherwise
        Default:
        false

      • reuseApplication

        boolean reuseApplication
        By default, new application instance is started for each test. If you want to re-use the same application instance between several tests then declare application in BASE test class and enable reuse option: all tests, derived from this base class would use the same application instance.

        You may have multiple base classes with reusable application declaration (different test hierarchies) - in this case, multiple applications would be kept running during tests execution.

        All other extensions (without enabled re-use) will start new applications: take this into account to prevent port clashes with already started reusable apps.

        Reused application instance would be stopped after all tests execution.

        Returns:
        true to reuse application, false to start application for each test
        Default:
        false

      • clientFactory

        java.lang.Class<? extends TestClientFactory> clientFactory
        Custom client factory for ClientSupport object. Custom factory may be required in case when custom client configuration is required for test.
        Returns:
        client factory class
        Default:
        ru.vyarus.dropwizard.guice.test.client.DefaultTestClientFactory.class