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

Annotation Interface StubRest

@Retention(RUNTIME) @Target(FIELD) public @interface StubRest
Resources stubbing: start lightweight rest container (with, probably, only one or a couple of services to test) without web (no servlets, filters, etc. would work). This is the same as dropwizard's ResourceExtension, but with full guice support. Rest extensions like exception mappers, filters, etc. could also be disabled (including dropwizard default extensions). As guicey knows all registered extensions, it provides them automatically (so, by default, no configuration is required - all jersey resources and extensions are available).

It is not quite correct to call it stubs - because this is a fully functional rest (same as in normal application). It is called stub just to highlight customization ability (for example, we can start only resource with just a bunch of enabled extensions). Other stubbing extensions should simplify testing resources (e.g., by mocking authorization support, etc.): StubBean, MockBean, SpyBean, TrackBean.

Could be used ONLY with TestGuiceyApp (or TestGuiceyAppExtension). Stubbing is enabled by a field declaration: @StubRest RestClient rest. This declaration activates custom rest container, started on random port and with all rest resources and extensions. As test container does not support web resources (will simply not work), all registered web extensions are disabled (to avoid confusion by console output), together with GuiceFilter.

Only one rest stub field could be declared in test! Rest client is injected into the declared field: use it to call rest methods: Something result = rest.get("/relative/rest/path", Something.class) (see RestClient class for usage info).

To limit started rest resources, simply specify what resources to start (test could start only one resource to test it): @StubRest(Resources1.class, Resource2.class). Alternatively, if many resources required, you can disable some resources: @StubRest(disableResources = {Resources1.class, Resource2.class}).

By default, all jersey extensions, declared in application are applied. You can disable all of them: @StubRest(disableAllJerseyExtensions = true) (note that dropwizard extensions remain!). Or you can specify just required extensions: @StubRest(jerseyExtensions = {Ext1.class, Ext2.class}). Also, only some extensions could be disabled: @StubRest(disableJerseyExtensions = {Ext1.class, Ext2.class}).

Default dropwizard's exception mappers could be disabled with: @StubRest(disableDropwizardExceptionMappers = true). This is very useful for testing rest errors (to receive exception instead of generic 500 response).

By default, in-memory container (lightweight, but not all features supported) would be used and grizzly container, if available in classpath. Use container() option to force the exact container type (prevent incorrect usage).

Use @TestGuiceyApp(debug = true) to see a list of active rest resources and jersey extensions. The full list of enabled jersey extensions (including dropwizard and jersey core) could be seen with .printJerseyConfig() option, activated in application (guice builder) or using a hook.

Log requests option (@StubRest(logRequests = true) activates complete requests and responses logging.

Warn: the default guicey client (ClientSupport) would not work - but you don't need it as a complete rest client provided.

Since:
20.02.2025

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    autoReset
    By default, the rest client state is re-set after each test.
    TestContainerPolicy
    container
    By default, use a lightweight in-memory container, but switch to grizzly when it's available in classpath (this is the default behavior of JerseyTest).
    boolean
    disableAllJerseyExtensions
    NOTE: if extensions specified in jerseyExtensions() then the disable option would be ignored (all required extensions already specified).
    boolean
    disableDropwizardExceptionMappers
    By default, all dropwizard exception mappers registered (same as in real application).
    Class<?>[]
    disableJerseyExtensions
    NOTE: if extensions specified in jerseyExtensions() then the disable option would be ignored (all required extensions already specified).
    Class<?>[]
    disableResources
    NOTE: if resources specified in value() then the disable option would be ignored (all required resources already specified).
    Class<?>[]
    jerseyExtensions
    By default, all jersey extension, registered in application, would be registered.
    boolean
    logRequests
    Requests log enabled by default (like in ClientSupport).
    Class<?>[]
    value
    By default, all resources would be available.

  • Element Details

    • value

      Class<?>[] value
      By default, all resources would be available. Use this option to run a subset of resources.
      Returns:
      resources to use in stub
      See Also:
      Default:
      {}

    • disableResources

      Class<?>[] disableResources
      NOTE: if resources specified in value() then the disable option would be ignored (all required resources already specified). This option is useful to exclude only some resources from the registered application resources

      Important: affects only resources, recognized as guicey extensions. Manually registered resources would remain!

      Returns:
      resources to disable
      Default:
      {}

    • jerseyExtensions

      Class<?>[] jerseyExtensions
      By default, all jersey extension, registered in application, would be registered. Use this option to specify exact required extensions (all other application extensions would be disabled).

      Important: this affects only guicey extensions (all other guicey extension would be simply disabled). To disable core dropwizard exception mappers use disableDropwizardExceptionMappers().

      Returns:
      jersey extensions to use in stub
      Default:
      {}

    • disableAllJerseyExtensions

      boolean disableAllJerseyExtensions
      NOTE: if extensions specified in jerseyExtensions() then the disable option would be ignored (all required extensions already specified).

      Does not affect dropwizard default extensions (only affects extension, controlled by guicey). Dropwizard exception mappers could be disabled with disableDropwizardExceptionMappers().

      Returns:
      true to disable all application jersey extensions
      Default:
      false

    • disableDropwizardExceptionMappers

      boolean disableDropwizardExceptionMappers
      By default, all dropwizard exception mappers registered (same as in real application). For tests, it might be more convenient to disable them and receive direct exception objects after test.
      Returns:
      true dropwizard exception mappers
      Default:
      false

    • disableJerseyExtensions

      Class<?>[] disableJerseyExtensions
      NOTE: if extensions specified in jerseyExtensions() then the disable option would be ignored (all required extensions already specified). This option is useful to exclude only some extensions from the registered application jersey extensions.

      Does not affect dropwizard default extensions (only affects extension, controlled by guicey). Dropwizard exception mappers could be disabled with disableDropwizardExceptionMappers().

      Returns:
      jersey extensions to disable
      Default:
      {}

    • autoReset

      boolean autoReset
      By default, the rest client state is re-set after each test. Client could be reset with manual TestClientDefaults.reset() call.
      Returns:
      false to disable automatic rest client state reset
      Default:
      true

    • logRequests

      boolean logRequests
      Requests log enabled by default (like in ClientSupport).
      Returns:
      true to print all requests and responses into console
      Default:
      true

    • container

      TestContainerPolicy container
      By default, use a lightweight in-memory container, but switch to grizzly when it's available in classpath (this is the default behavior of JerseyTest).
      Returns:
      required test container policy
      Default:
      DEFAULT