Spring Lifecycle Smoke Tests

A suite of tests and documentation for Spring Boot applications using either CDS or JVM Checkpoint Restore as implemented by Project CRaC. There are two types of tests: unit tests and application tests.

Unit tests can be run using the test task.

The appTest task tests the application running on the JVM. The checkpointRestoreAppTest (also available with the shorter cRAT task name) task tests the application running on the JVM after a checkpoint/restore.

Prerequisites

Linux or Windows via WSL2

• CRaC enabled JDK such as the one provided by Azul.

• Docker to run external services such as database servers.

Note	If using SDKMan then run sdk env install.

Mac

• Docker Desktop (Colima + QEMU does not support CRaC JDK in a reliable way)

• Use ./run-dev-container.sh before running Gradle commands.

Contributing

Please read and follow the contributing guide.

How to

Run all of a project’s smoke tests

./gradlew :<name of the group>:<name of the smoke test>:build

for example

./gradlew :framework:webmvc-tomcat:build

Run a specific type of tests for a project

./gradlew :<name of the group>:<name of the smoke test>:<test task name>

Valid test task names are:

1. appTest – tests the application running on the JVM

2. checkpointRestoreAppTest (also available with the shorter cRAT task name) – tests the application running on the JVM after a checkpoint/restore

3. test – executes the unit tests on the JVM

for example

./gradlew :framework:webmvc-tomcat:appTest

Add a new smoke test

1. Create a new directory for your smoke test in the appropriate group

2. Include the directory in settings.gradle (new groups only)

3. Run ./gradlew updateInfrastructure to add the smoke test to the status page and CI pipeline

Test against local changes

Your project uses Gradle

./gradlew :<name of the group>:<name of the smoke test>:build --include-build /path/to/your/project

Gradle will then substitute the dependency with your provided version.

Hint: You can use --include-build multiple times.

Your project uses Maven or --include-build does not work

First, install the snapshots into your local Maven cache. You can now consume those snapshots using -PfromMavenLocal which takes an optional comma-separated list of group IDs:

./gradlew :framework:webmvc-tomcat:build -PfromMavenLocal=org.springframework

The preceding example will run the webmvc-tomcat smoke test, resolving Spring Framework from your local Maven cache.

You can also just specify:

./gradlew :framework:webmvc-tomcat:build -PfromMavenLocal

Here all the dependencies will be resolved from your local Maven cache.

Override a dependency version

As the test doesn’t use the Spring Dependency Management Plugin, you can’t use the ext['…​'] = '…​' method.

Instead, use Gradle dependency constraints. Say, for example, you want to update the version of Spring Session JDBC to 3.0.0-SNAPSHOT:

dependencies {
    // ...
    constraints {
        implementation('org.springframework.session:spring-session-jdbc:3.0.0-SNAPSHOT')
    }
}

This works for direct and transitive dependencies.

Use a custom event to trigger the checkpoint

By default, org.springframework.boot.context.event.ApplicationReadyEvent is used to trigger the checkpoint when the application is ready. It is possible to specify another event to trigger the checkpoint with the following Gradle configuration:

crSmokeTest {
    checkpointEvent = "com.example.MyCustomEvent"
}