spring-lifecycle-smoke-tests/README.adoc

= Spring Lifecycle Smoke Tests

image:https://img.shields.io/badge/3.2.x-status-blue["Status", link="https://github.com/spring-projects/spring-lifecycle-smoke-tests/blob/main/STATUS.adoc"]

A suite of tests and documentation for Spring Boot applications using a custom lifecycle to perform a training run with
https://docs.spring.io/spring-framework/reference/integration/cds.html[CDS] or
https://docs.spring.io/spring-framework/reference/integration/checkpoint-restore.html[JVM Checkpoint Restore].

== Training run configuration

The training run of your application may require custom configuration, to prevent early database interaction for example,
see related documentation depending on the dependencies used:

- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-jpa[Spring Data JPA]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-jdbc[Spring Data JDBC]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-r2dbc[Spring Data R2DBC]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-mongodb[Spring Data MongoDB]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-mongodb-reactive[Spring Data MongoDB Reactive]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/data/data-redis[Spring Data Redis]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/batch/batch[Spring Batch]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/boot/flyway[Flyway]
- https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/main/boot/liquibase[Liquibase]

== Tests

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

- Docker to run external services such as database servers.
- For CRaC, a CRaC enabled JDK such as https://bell-sw.com/pages/downloads/?package=jdk-crac[the one provided by Bellsoft].

> NOTE: If using SDKMan then run `sdk env install`.

==== Mac

- https://www.docker.com/products/docker-desktop/[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 link:CONTRIBUTING.adoc[contributing guide].

=== How to

==== Run all of a project's smoke tests

[source,]
----
./gradlew :<name of the group>:<name of the smoke test>:build
----

for example

[source,]
----
./gradlew :framework:webmvc-tomcat:build
----

==== Run a specific type of tests for a project

[source,]
----
./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

[source,]
----
./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

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

Gradle https://docs.gradle.org/current/userguide/composite_builds.html#command_line_composite[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:

[source,]
----
./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:
[source,]
----
./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 https://docs.gradle.org/current/userguide/dependency_constraints.html[Gradle dependency constraints].
Say, for example, you want to update the version of Spring Session JDBC to `3.0.0-SNAPSHOT`:

[source,]
----
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:

[source,]
----
crSmokeTest {
    checkpointEvent = "com.example.MyCustomEvent"
}
----