spring-lifecycle-smoke-tests/README.adoc

= Spring Lifecycle Smoke Tests

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, applied by default to your application or specifically to the training run, to prevent early database interaction for example.
See related documentation for the most common dependencies:

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

NOTE: Keep in mind that with CDS, a regular startup lifecycle will be performed during the optimized run, while
checkpoint/restore will resume the lifecyle where it was stopped, without refreshing the configuration unless you use
https://cloud.spring.io/spring-cloud-commons/reference/html/#refresh-scope[Spring Cloud refresh scope].

== 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,]
----
gradle :<name of the group>:<name of the smoke test>:build
----

for example

[source,]
----
gradle :framework:webmvc-tomcat:build
----

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

[source,]
----
gradle :<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,]
----
gradle :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. Consult the https://github.com/spring-projects/spring-lifecycle-smoke-tests/tree/ci/README.adoc[README in the `ci` branch] to update the CI infrastructure

==== Test against local changes

===== Your project uses Gradle

[source,]
----
gradle :<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,]
----
gradle :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,]
----
gradle :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,]
----
lifecycleSmokeTest {
    checkpointEvent = "com.example.MyCustomEvent"
}
----