Ahead of Time Support for Tests

This chapter covers Infra Ahead of Time (AOT) support for integration tests using the Infra TestContext Framework.

The testing support extends Infra core AOT support with the following features.

Build-time detection of all integration tests in the current project that use the TestContext framework to load an ApplicationContext.
- Provides explicit support for test classes based on JUnit Jupiter and JUnit 4 as well as implicit support for TestNG and other testing frameworks that use Infra core testing annotations — as long as the tests are run using a JUnit Platform TestEngine that is registered for the current project.
Build-time AOT processing: each unique test ApplicationContext in the current project will be refreshed for AOT processing.
Runtime AOT support: when executing in AOT runtime mode, a Infra integration test will use an AOT-optimized ApplicationContext that participates transparently with the context cache.

All tests are enabled in AOT mode by default. However, you can selectively disable an entire test class or individual test method in AOT mode by annotating it with @DisabledInAotMode. When using JUnit Jupiter, you may selectively enable or disable tests in a GraalVM native image via Jupiter’s @EnabledInNativeImage and @DisabledInNativeImage annotations. Note that @DisabledInAotMode also disables the annotated test class or test method when running within a GraalVM native image, analogous to JUnit Jupiter’s @DisabledInNativeImage annotation.

By default, if an error is encountered during build-time AOT processing, an exception will be thrown, and the overall process will fail immediately.

If you would prefer that build-time AOT processing continue after errors are encountered, you can disable the failOnError mode which results in errors being logged at WARN level or with greater detail at DEBUG level.

The failOnError mode can be disabled from the command line or a build script by setting a JVM system property named infra.test.aot.processing.failOnError to false. As an alternative, you can set the same property via the TodayStrategies mechanism.

The @ContextHierarchy annotation is not supported in AOT mode.

To provide test-specific runtime hints for use within a GraalVM native image, you have the following options.

Implement a custom TestRuntimeHintsRegistrar and register it globally via META-INF/config/aot.factories.
Implement a custom RuntimeHintsRegistrar and register it globally via META-INF/config/aot.factories or locally on a test class via @ImportRuntimeHints.
Annotate a test class with @Reflective or @RegisterReflectionForBinding.
See Runtime Hints for details on Infra core runtime hints and annotation support.

The TestRuntimeHintsRegistrar API serves as a companion to the core RuntimeHintsRegistrar API. If you need to register global hints for testing support that are not specific to particular test classes, favor implementing RuntimeHintsRegistrar over the test-specific API.

If you implement a custom ContextLoader, it must implement AotContextLoader in order to provide AOT build-time processing and AOT runtime execution support. Note, however, that all context loader implementations provided by the TODAY Framework and Infra App already implement AotContextLoader.

If you implement a custom TestExecutionListener, it must implement AotTestExecutionListener in order to participate in AOT processing. See the SqlScriptsTestExecutionListener in the today-test module for an example.