Merge pull request #50986 from geoand/aot-docs

Add mention of AOT file generation from tests in docs

Author: gsmet

docs/src/main/asciidoc/appcds.adoc

@@ -116,6 +116,13 @@ java -XX:AOTCache=app.aot -jar quarkus-run.jar
 ----
 ====
 
+=== Generate the AOT cache from integration tests
+
+Although Quarkus can generate an AOT cache file without ever running the production application, the file will not be optimal as the application was never exercised against any load. To alleviate this,
+Quarkus can use the existing testsuite of tests annotated with `@QuarkusIntegrationTest` to create an AOT cache file.
+See the xref:getting-started-testing.adoc#generating-an-aot-cache-during-integration-tests[corresponding section] in the Testing Guide for more details.
+
+
 === Usage in containers
 
 When building container images using the `quarkus-container-image-jib` extension, Quarkus automatically takes care of all the steps needed to generate the archive and make it usable at runtime in the container.

docs/src/main/asciidoc/getting-started-testing.adoc

@@ -1354,6 +1354,32 @@ packaged as *jar*, you can use:
 
 as an argument to Maven/Gradle when launching the test. This will make the application wait until a remote JVM debugger is connected to port `5005`.
 
+[#generating-an-aot-cache-during-integration-tests]
+=== Generating an AOT cache during integration tests
+
+When targeting JDK 25+, you can instruct Quarkus to generate an AOT cache (`app.aot`) while running `@QuarkusIntegrationTest` tests.
+Enable this by adding the following system property to your integration test run:
+
+[source,bash]
+----
+-Dquarkus.package.jar.appcds.use-aot=true
+----
+
+With this flag, the tested application is launched with the JVM’s AOT cache output option, and an `app.aot` file is produced next to the built jar (for example `target/quarkus-app/app.aot`). You can then run the application with:
+
+[source,bash]
+----
+java -XX:AOTCache=app.aot -jar quarkus-run.jar
+----
+
+This feature essentially turns the existing testsuite into a training run.
+
+[NOTE]
+====
+- The feature requires JDK 25 or newer.
+- The effectiveness of the generated cache depends on how representative your integration tests are of production startup and early traffic.
+====
+
 === Launching containers
 
 When `@QuarkusIntegrationTest` results in launching a container (because the application was built with `quarkus.container-image.build` set to `true`), the container is launched on a predictable container network. This facilitates writing integration tests that need to launch services to support the application.
@@ -1496,13 +1522,13 @@ You can use this tag to isolate the `@QuarkusTest` test in a specific execution
 
 [NOTE]
 --
-Currently `@QuarkusTest` and `@QuarkusIntegrationTest` should not be run in the same test run.  
+Currently `@QuarkusTest` and `@QuarkusIntegrationTest` should not be run in the same test run.
 
 For Maven, this means that the former should be run by the surefire plugin while the latter should be run by the failsafe plugin.
 
 For Gradle, this means the two types of tests should belong to different source sets.
 
-.Source set configuration example  
+.Source set configuration example
 [%collapsible]
 ====
 [source,kotlin,subs=attributes+]