Package org.apache.juneau.microservice.test

Annotation Interface MicroserviceTest

@Documented @Retention(RUNTIME) @Target(TYPE) @ExtendWith(MicroserviceExtension.class) @Tag("microservice") public @interface MicroserviceTest
Boots a whole Microservice (config + lifecycle + embedded Jetty server) for the annotated JUnit 5 test class — the standalone-microservice analog of Spring's @SpringBootTest.

@MicroserviceTest is a single, server-agnostic meta-annotation: it composes @ExtendWith(MicroserviceExtension) plus a @Tag("microservice") marker. The extension builds the microservice on an OS-assigned ephemeral port before the test class runs, and stop()s it afterward (releasing the port and firing @PreDestroy hooks).

Specifying the system under test

The SUT is declared explicitly (no classpath scanning), two complementary ways:

  1. configurations() — one or more @Configuration classes whose @Bean Servlet methods are auto-mounted by the microservice (the common case).
  2. A static method on the test class returning a Microservice.Builder — for full control over the builder. Discovered by name "microserviceBuilder" (override via builderMethod()). Configurations from configurations() are appended to whatever the supplier returns.

In both cases the extension additionally installs an EphemeralJettyServerConfig (binding a Jetty Server to port 0) and JettyConfiguration, so tests only contribute their resources.

Mock-bean injection

Declare collaborators to substitute with the existing @TestBean (the @MockBean analog) — no parallel injection annotation. By default these are installed via Mode INJECT (through Microservice.Builder.overridingBeanStore(...)) before boot, so the service sees them from startup. @TestBean(mode = Mode.OVERLAY) pushes/pops against the already-booted instance instead.

What gets injected into tests

Test methods (and lifecycle methods) may declare parameters resolved by the extension: RestClient (bound to the booted server's root URL — the primary convenience), Microservice, the WritableBeanStore, and the bound port (as int / Integer). The same TestBeanStore parameter the underlying JuneauBeanStoreExtension resolves is available too.

When to use this vs. MockRestClient

Use @MicroserviceTest for a genuine full-microservice integration test — real server, real connectors, real lifecycle, over HTTP. For an in-JVM test of a single @Rest resource (no server, no sockets), use MockRestClient directly; the two paths are intentionally distinct.

Example:

@MicroserviceTest(configurations=MyServerConfig.class) class MyServiceTest { @Configuration static class MyServerConfig { @Bean Servlet myService() { return new MyRestService(); } } @TestBean MyExternalApi mockApi = Mockito.mock(MyExternalApi.class); @Test void aTest(RestClient client) { client.get("/widgets/1").run().assertStatus().is(200); } }

See Also:
Since:
10.0.0

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    builderMethod
    Name of an optional static method on the test class returning a Microservice.Builder to seed the boot.
    Class<?>[]
    configurations
    The @Configuration classes whose @Bean Servlet methods the microservice auto-mounts.

  • Element Details

    • configurations

      Class<?>[] configurations
      The @Configuration classes whose @Bean Servlet methods the microservice auto-mounts.

      Appended after any builder produced by a builderMethod() supplier, and before the framework's EphemeralJettyServerConfig + JettyConfiguration.

      Returns:
      The configuration classes. Empty by default (rely on a builderMethod() supplier).
      Default:
      {}

    • builderMethod

      String builderMethod
      Name of an optional static method on the test class returning a Microservice.Builder to seed the boot.

      The method must be static, take no arguments, and return a Microservice.Builder. When absent, a fresh Microservice.create() builder is used. configurations() are appended either way.

      Returns:
      The supplier method name. Defaults to "microserviceBuilder".
      Default:
      "microserviceBuilder"