content/openwebbeans-junit5.md

Title: OpenWebBeans JUnit 5

# OpenWebBeans JUnit 5

OpenWebBeans provides a JUnit 5 integration. It brings an extension which will be backed by CDI Standalone Edition API (`SeContainer`).

The entry point is `@Cdi` API which maps the main methods of `SeContainerInitializer`.
It typically enables you to define which classes you want to deploy for the test or if you want to use classpath scanning.

Here is how a test can look like:

    @Cdi(disableDiscovery = true, classes = MyService.class)
    class CdiTest {
        @Inject
        private MyService service;

        @Test
        void test() {
            assertEquals("ok", service.ok());
        }
    }

As you may notice, this test disable the default classpath scanning and only activate `MyService` bean.

Once a test is marked `@Cdi` you get injections of the underlying container available in the test class. This is how previous snippet can inject `MyService` into the test class without having anything else to do.

## Dependency

     <dependency>
        <groupId>org.apache.openwebbeans</groupId>
        <artifactId>openwebbeans-junit5</artifactId>
        <version>${owb.version}</version>
      </dependency>

IMPORTANT: this feature comes with OpenWebBeans >= 2.0.11.

## Reusable mode

`@Cdi` also adds a specific API called `reusable`. When this is set to `true`, the container is started and then reused by next test.
This enables to speed up the test suite a lot when reusing the same JVM to run all tests.

For example if you have these two tests:

    @Cdi(reusable = true)
    class MyFirstTest {
        @Inject
        private MyService service;

        @Test
        void test() {
            assertEquals("ok", service.ok());
        }
    }

and

    @Cdi(reusable = true)
    class MySecondTest {
        @Inject
        private MyOtherService service;

        @Test
        void test() {
            assertEquals("ok2", service.ok());
        }
    }

Then CDI container will be started only once.

However if the first test is:

    @Cdi(reusable = true, disableDiscovery = true, classes = MyService.class)
    class MyFirstTest {
        // .. as before
    }

Then the second test will not have its `MyOtherService` bean since previous test will only deploy `MyService`.

To avoid that it is recommended to follow these best practises:

- Never mix reusable and not reusable tests in the same suite (define multiple surefire executions for example),
- For reusable tests define a meta annotation which shares the configuration for all tests, this means you must have a single `reusable = true` in your whole code (per execution).

To define a reusable setup you just define a new annotation decorated with `@Cdi`:

    @Target(TYPE)
    @Retention(RUNTIME)
    @Cdi(reusable = true, disableDiscovery = true, packages = MyService.class)
    public @interface TestConfig {
    }

Then your test class can look like:


    @TestConfig
    class MySecondTest {
        @Inject
        private MyService service;

        @Test
        void test() {
            assertEquals("ok", service.ok());
        }
    }

### Surefire

For reusable mode to be efficient, it is recommended to use this surefire configuration:

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>${surefire.version}</version>
      <configuration>
        <forkCount>1</forkCount>
      </configuration>
    </plugin>

And here is how to define executions to mix reusable and not reusable tests - which can have a different deployment setup:

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>${surefire.version}</version>
        <executions>
            <execution> <!-- skip default setup since we redefine it -->
                <id>default-test</id>
                <configuration>
                    <skip>true</skip>
                </configuration>
            </execution>
            <execution>
                <id>not-reusable</id>
                <phase>test</phase>
                <goals>
                    <goal>test</goal>
                </goals>
                <configuration>
                    <includes>**/perclass/*</includes>
                </configuration>
            </execution>
            <execution>
                <id>reusable</id>
                <phase>test</phase>
                <goals>
                    <goal>test</goal>
                </goals>
                <configuration>
                    <includes>**/reusable/*</includes>
                </configuration>
            </execution>
        </executions>
        <configuration>
          <forkCount>1</forkCount>
        </configuration>
    </plugin>

This setup assumes not reusable tests are in a `perclass` package and reusable ones are in a `reusable` package.
Alternatively you can use categories (just define markers in your test code) but this is generally less obvious to manage on the long run.