Jakarta REST SeBootstrap JUnit Integration

Table of Contents

• Documentation
• Usage
  • Dependencies
  • Examples
  • Injection
• Releasing
  • Supported Arguments

This is a simple project which allows a unit testing for Jakarta REST endpoints using the SeBootstrap from Jakarta REST 3.1.

Documentation

For complete documentation including advanced features, extension points, and best practices, see the full documentation.

The documentation is also published to GitHub Pages with each release: https://resteasy.dev/resteasy-junit-extension/

Usage

To use this JUnit integration you simply need to add a @RestBootstrap(YourApplication.class) annotation to your test. A SeBoostrap.Instance will be created and started based on the implementation you choose.

Dependencies

The first dependency you need is the JUnit extension.

<dependencies>
    <dependency>
        <groupId>dev.resteasy.junit.extension</groupId>
        <artifactId>resteasy-junit-extension</artifactId>
        <version>${version.dev.resteasy.junit.extension</version>
    </dependency>
</dependencies>

Next you need to define an implementation. This project chose not to be implementation specific and should work with any Jakarta REST 3.1+ implementation.

RESTEasy Example

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-bom</artifactId>
            <version>${version.org.jboss.resteasy}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.junit</groupId>
            <artifactId>junit-bom</artifactId>
            <version>${version.org.junit}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>org.jboss.resteasy</groupId>
        <artifactId>resteasy-core-spi</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.jboss.resteasy</groupId>
        <artifactId>resteasy-client</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.jboss.resteasy</groupId>
        <artifactId>resteasy-undertow-cdi</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Examples

Simple Test

@RestBootstrap(value = SimpleTest.TestApplication.class)
public class SimpleTest {

    @RestResource
    @RequestPath("/test/echo")
    private WebTarget webTarget;

    @Test
    public void invokeResource(final UriBuilder builder) {
        try (Client client = ClientBuilder.newClient()) {
            final String result = client.target(builder.path("/test/echo/"))
                    .request()
                    .post(Entity.text("Hello"), String.class);
            Assertions.assertEquals("Hello", result);
        }
    }

    @Test
    public void invokeResourceOnInjectedClient() {
        final String result = webTarget.request()
                    .post(Entity.text("Hello"), String.class);
        Assertions.assertEquals("Hello", result);
    }

    @ApplicationPath("/test")
    public static class TestApplication extends Application {
        @Override
        public Set<Class<?>> getClasses() {
            return Set.of(EchoResource.class);
        }
    }
    @Path("/echo")
    public static class EchoResource {
        @POST
        public String echo(String text) {
            return text;
        }
    }
}

Injection

You can inject some types into your tests. For fields you use the @RestResource annotation. Constructor and method parameters do not require the @RestResource annotation. The following types can be injected.

• jakarta.ws.rs.SeBootstrap.Configuration

  The configuration from the SeBoostrap.Instance that was started.

• jakarta.ws.rs.client.Client

  A REST Client. This can have a qualifier of @RestClientConfig which returns a RestClientBuilderProvider and allows the configuration to be overridden for the client.

• jakarta.ws.rs.core.UriBuilder

  Injects a URI builder. Given this is a mutable builder, this should likely only be injected as a method parameter.

• java.net.URI

  The base URI for SeBootstrap.Instance that was started.

• jakarta.ws.rs.client.WebTarget

  This can be used with the @RequestPath qualifier. It creates a WebTarget from a configured client.

Type	Field	Parameter	Constructor	Qualifiers
jakarta.ws.rs.SeBootstrap.Configuration	X	X	X
jakarta.ws.rs.client.Client	X	X	X	@RestClientConfig (optional)
jakarta.ws.rs.core.UriBuilder		X	X
java.net.URI	X	X	X
jakarta.ws.rs.client.WebTarget	X	X	X	@RequestPath (optional) @RestClientConfig (optional)

Releasing

Releasing the project requires permission to deploy to Maven Central see Maven Central Release Requirements. Once everything is setup, you simply need to run the ./release.sh script. There are two required parameters:

1. -r or --release which is the version you want to release

2. -d or --development which is the next development version.

By default the release version cannot contain SNAPSHOT and the development version, must container SNAPSHOT.

.Example Command

/release -r 1.0.0.Final -d 1.0.1.Final-SNAPSHOT

Supported Arguments

Argument	Requires Value	Description
-d, --development	Yes	The next version for the development cycle.
-f, --force	No	Forces to allow a SNAPSHOT suffix in release version and not require one for the development version.
-h, --help	N/A	Displays this help
--notes-start-tag	Unused	Passes the --notes-from-tag and the argument to the gh create release command.
-p, --prerelease	Unused	Passes the --prerelease to the gh create release command.
-r, --release	Yes	The version to be released. Also used for the tag.
--dry-run	No	Executes the release in as a dry-run. Nothing will be updated or pushed.
--no-push	No	Executes the release in, but doesn’t actually push the changes to GitHub or publish the release on Maven Central. Any next steps should you want to continue the release will need to be manual.
-v, --verbose	No	Prints verbose output.

Any additional arguments are considered arguments for the Maven command.