spring-boot-testjars

Spring Boot + Testcontainers support for Spring Boot applications, but without the need for a Docker container.

This project is intended to add support for running external Spring Boot applications during development and testing by building on Spring Boot’s existing support. It is composed of two main features:

• Adding the ability to easily start an External Spring Boot application

• Extending Spring Boot’s support for DynamicPropertyRegistry

Note	This project is an experimental project and may make breaking changes including, but not limited to, the name of the project.

Videos

• Spring Tips

Motivation

Why not just create a Docker image of the Spring Boot application and use Testcontainers?

• Lighter weight than spinning up a Docker image

• When you are consuming dependencies, you don’t always have a docker image available. Sure you can create one, but why add additional overhead?

Maven / Gradle

You can add Spring Boot Testjars to your project by adding them to your Gradle or Maven build.

build.gradle

testImplementation("org.springframework.experimental.boot:spring-boot-testjars:0.0.3")

pom.xml

<dependency>
    <groupId>org.springframework.experimental.boot</groupId>
    <artifactId>spring-boot-testjars</artifactId>
    <version>0.0.3</version>
</dependency>

Releases are published to Maven Central. For any other release type, refer to the Spring Repositories.

Starting an External Spring Boot Application

This project allows users to easily start an external Spring Boot application by creating it as a Bean. For example, the code below will start (on a arbitrary available port) and stop an external Spring Boot application as a part of the lifecycle of the Spring container:

@Bean
static CommonsExecWebServerFactoryBean messagesApiServer() {
  return CommonsExecWebServerFactoryBean.builder()
    .classpath((cp) -> cp
        .files("build/libs/messages-0.0.1-SNAPSHOT.jar")
    );
}

The CommonsExecWebServerFactoryBean creates a CommonsExecWebServer and the property CommonsExecWebServer.getPort() returns the port that the application starts on.

MavenClasspathEntry

User’s can also resolve Maven dependencies from Maven Central. The following will add spring-boot-starter-authorization-server and it’s transitive dependencies to the classpath.

@Bean
@OAuth2ClientProviderIssuerUri
static CommonsExecWebServerFactoryBean authorizationServer() {
	// @formatter:off
	return CommonsExecWebServerFactoryBean.builder()
		// ...
		.classpath((classpath) -> classpath
			// Add spring-boot-starter-authorization-server & transitive dependencies
			.entries(springBootStarter("oauth2-authorization-server"))
		);
	// @formatter:on
}

You can also use the MavenClasspathEntry constructor directly or additional helper methods to add dependencies other than Spring Boot starters to the classpath.

To use this feature, add the following to your build:

build.gradle

testImplementation 'org.springframework.experimental.boot:spring-boot-testjars-maven:0.0.3'

pom.xml

<dependency>
    <groupId>org.springframework.experimental.boot</groupId>
    <artifactId>spring-boot-testjars-maven</artifactId>
    <version>0.0.3</version>
</dependency>

Custom Maven Repositories

By default, the following repositories are added: - Maven Central - If it is a SNAPSHOT dependency with a group id that starts with org.springframework, then Spring’s milestone and snapshot repositories are added - If it is a milestone or release candidate dependency with a group id that starts with org.springframework, then Spring’s milestone repository is added

You can customize the repositories that are searched by injecting the repositories like the example below:

List<RemoteRepository> repositories = new ArrayList<>();
repositories.add(new RemoteRepository.Builder("central", "default", "https://repo.maven.apache.org/maven2/").build());
repositories.add(new RemoteRepository.Builder("sonatype-snapshot", "default", "https://oss.sonatype.org/content/repositories/snapshots/").build());
MavenClasspathEntry classpathEntry = new MavenClasspathEntry("org.junit:junit5-api:5.0.0-SNAPSHOT", repositories);

Exclude Transitive Dependencies

If you are resolving a Spring Boot (fat jar), then you do not need to resolve transitive dependencies. To disable downloading transitive dependencies, you can pass in true for the excludeTransitives constructor argument. For example:

boolean excludeTransitives = true;
List<RemoteRepository> repositories = new ArrayList<>();
repositories.add(new RemoteRepository.Builder("example", "default", "https://example.org/maven2/").build());
MavenClasspathEntry classpathEntry = new MavenClasspathEntry("org.example:message-service:1.0.0", repositories, excludeTransitives);

GenericSpringBootApplicationMain

For adhoc applications, you may not have a main class and you may not want to provide boilerplate main method yourself. If that is the case, you can leverage useGenericSpringBootMain:

@Bean
@OAuth2ClientProviderIssuerUri
static CommonsExecWebServerFactoryBean authorizationServer() {
	// @formatter:off
	return CommonsExecWebServerFactoryBean.builder()
		// ...
		// Add a generic class annotated with SpringBootApplication and a main method to the classpath and use it as the main class
		.useGenericSpringBootMain();
	// @formatter:on
}

Default Resources

If present, CommonsExecWebServerFactoryBean will add the resources testjars/$beanName/**, then it is automatically added to the classpath as resources renamed without the path of testjars/$beanName. For example, if the bean name is authorizationServer, then the resource testjars/authorizationServer/application.yml will automatically be added to the classpath as application.yml. Furthermore, a resource named testjars/authorizationServer/foo/bar.txt will automatically be added to the classpath as foo/bar.txt.

Adding Additional Classes to the ApplicationContext

It can often be helpful to add additional classes to the ApplicationContext. Simply adding them to the classpath does not necessarily add the class to the ApplicationContext. For example, if someone wants to start a Config Server instance, the ConfigServerConfiguration must be imported:

@Bean
@DynamicPortUrl(name = "spring.cloud.config.uri")
static CommonsExecWebServerFactoryBean configServer() {
	// @formatter:off
	return CommonsExecWebServerFactoryBean.builder()
		.useGenericSpringBootMain()
		.setAdditionalBeanClassNames("org.springframework.cloud.config.server.config.ConfigServerConfiguration")
		.classpath((classpath) -> classpath
			.entries(springBootStarter("web"))
			.entries(new MavenClasspathEntry("org.springframework.cloud:spring-cloud-config-server:4.2.0"))
		);
	// @formatter:on
}

Debugging

If you need to start the application in debug mode, you can do so using the DebugSettings.

@Bean
@OAuth2ClientProviderIssuerUri
static CommonsExecWebServerFactoryBean authorizationServer() {
	// @formatter:off
	return CommonsExecWebServerFactoryBean.builder()
		// ...
		.debug((settings) -> settings
			.enabled(true)
			// Optional properties with their explicit defaults shown below
			.suspend(true)
			.port(5005)
		);
	// @formatter:on
}

When starting the remote debugger, it is important to remember that the classpath of the CommonsExecWebServerFactoryBean is independent of the project it runs in. This means, the classpath of the debugger will need to match the classpat of the CommonsExecWebServerFactoryBean rather than the project it exists in.

Server Port

By default CommonsExecWebServerFactoryBean starts the application on a random port by specifying the system property server.port=0. If you need to disable this behavior, you can opt out using the useRandomPort property as shown below:

@Bean
@OAuth2ClientProviderIssuerUri
static CommonsExecWebServerFactoryBean authorizationServer() {
	// @formatter:off
	return CommonsExecWebServerFactoryBean.builder()
		// ...
		.useRandomPort(false);
	// @formatter:on
}

@DynamicProperty

This is an extension to Spring Boot’s existing DynamicPropertyRegistry. It allows annotating arbitrary Spring Bean definitions and adding a property that references properties on that Bean.

@EnableDynamicProperty

In order to use @DynamicProperty annotations, it must be enabled with the @EnableDynamicProperty annotation as show below:

@Configuration
@EnableDynamicProperty
class MyConfiguration {
	// ...
}

@DynamicProperty Example

For example, the following @DynamicProperty definition uses SpEL with the current Bean as the root object for the value annotation to add a property named messages.url to the URL and the arbitrary available port of the CommonsExecWebServer:

@Bean
@DynamicProperty(name = "messages.url", value = "'http://localhost:' + port")
static CommonsExecWebServerFactoryBean messagesApiServer() {
  return CommonsExecWebServerFactoryBean.builder()
    .classpath(cp -> cp
        .files("build/libs/messages-0.0.1-SNAPSHOT.jar")
    );
}

Note	While our @DynamicProperty examples use CommonsExecWebServer, the @DynamicProperty annotation works with any type of Bean.

Composed @DynamicProperty Annotations

@DynamicProperty is treated as a meta-annotation, so you can create composed annotations with it. For example, the following works the same as our example above:

MessageUrl.java

@Retention(RetentionPolicy.RUNTIME)
@DynamicProperty(name = "message.url", value = "'http://localhost:' + port")
public @interface MessageUrl {
}

Config.java

@Bean
@MessageUrl
static CommonsExecWebServerFactoryBean oauthServer() {
  return CommonsExecWebServerFactoryBean.builder()
    .classpath(cp -> cp
      .files("build/libs/authorization-server-0.0.1-SNAPSHOT.jar")
    );
}

Well Known Composed @DynamicProperty Annotations

This is a list of well known composed @DynamicProperty annotations.

@DynamicPortUrl

This provides a simple way of mapping a property to a URL with a dynamic port that is expressed as the port property on the Bean that is created. The value is calculated as http://{host}:{port}{contextRoot}.

• name - the property name to use

• host - the host to use (default is localhost)

• port - a valid SpEL expression that determines the port to use for the URL (default port)

• contextRoot - the context root to use (default is empty String)

@CloudConfigUri

This simplifies mapping the to the property spring.cloud.config.uri. The value is calculated as http://{host}:{port}{contextRoot} such that:

• host - the host to use (default is localhost)

• port - a valid SpEL expression that determines the port to use for the URL (default port)

• contextRoot - the context root to use (default is empty String)

@OAuth2ClientProviderIssuerUri

This provides a mapping to issuer-uri of the OAuth provider details.

• name spring.security.oauth2.client.provider.{providerName}.issuer-uri with a default providerName of spring. The providerName can be overridden with the OAuth2ClientProviderIssuerUri.providerName property.

• value 'http://127.0.0.1:' + port which can be overriden with the OAuth2ClientProviderIssuerUri.value property

Samples

Run TestOauth2LoginMain. This starts the oauth2-login sample and a Spring Authorization Server you assembled in the previous step.

Visit http://localhost:8080/

You will be redirected to the authorization server. Log in using the username user and password password.

You are then redirected to the oauth2-login application.