This commit adds the supporting testing infrastructure using the
`RuntimeHintsAgent`. Given that the agent is loaded by the JVM running
the test suite, we can then use it to record method invocations at
runtime and check whether the prepared `RuntimeHints` match the expected
behavior.
This commit contributes the `RuntimeHintsRecorder`. With this, we can
record relevant method invocations for a given lambda, focusing on a
specific part of the code behavior. This returns a
`RuntimeHintsInvocations` instance, which is an AssertJ assert provider.
From there, we can perform assertions on the recorded invocations and
check that a given collection of hints cover the reflection, resources
and proxies needs at runtime.
This also ships the `@EnabledIfRuntimeHintsAgent` opinionated
annotation: this applies the `RuntimeHintsAgentCondition` JUnit
extension that detects whether the `RuntimeHintsAgent` is loaded by the
current JVM. Tests annotated with this will be skipped if the agent is
not present. This annotation is also tagged with a JUnit `@Tag` to
gather such tests in a specific `"RuntimeHintsTests"` test suite.
In the Spring Framework build, we have chosen to isolate such tests and
not load the agent for the main test suite ("RuntimeHintsTests" tests
are excluded from the main suite). While the agent's intent is to be as
transparent as possible, there are security and access considerations
that could interefere with other tests.
With this approach, we can then create a separate test suite and run
agent tests in a dedicated JVM.
Note that projects using this infrastructure can choose to use the
condition by itself in a custom annotation.
Here is an example of this testing infrastructure:
```
@EnabledIfRuntimeHintsAgent
class MyTestCases {
@Test
void hintsForMethodsReflectionShouldMatch() {
RuntimeHints hints = new RuntimeHints();
hints.reflection().registerType(String.class,
hint -> hint.withMembers(MemberCategory.INTROSPECT_PUBLIC_METHODS));
RuntimeHintsInvocations invocations = RuntimeHintsRecorder.record(() -> {
Method[] methods = String.class.getMethods();
});
assertThat(invocations).match(hints);
}
}
```
See gh-27981
With the introduction of `RuntimeHints`, we can now contribute
reflection, resources and proxies hints that describe the expected
runtime behavior of the application. While this can be verified at
runtime with smoke tests, managing such tests and compiling to native
there is not very efficient.
This commit introduces the new `RuntimeHintsAgent`, a Java agent that
instruments JDK methods related to `RuntimeHints`.
It is different from the GraalVM agent, which aims at collecting all the
required hints for the runtime behavior of an application and dump those
in the expected format.
Here, the `RuntimeHintsAgent` can collect the related invocations only
for a delimited scope (typically, a lambda within a test) and later
check those against a `RuntimeHints` instance. In the case of testing
`RuntimeHintsRegistrar` implementations, the process is reversed:
instead of manually checking for registered hints in a `RuntimeHints`
instance, tests should exercise the use cases and then check that the
recorded behavior is in line with the prepared hints.
This first commit adds the agent infrastructure that collects the
invocations for all relevant JDK methods.
See gh-27981
Update the `TestCompiler` so that classes can be defined using
a `Lookup`. This update allows package-private classes to be
accessed without needing a quite so unusual classloader setup.
The `@CompileWithTargetClassAccess` should be added to any
test that needs to use `Lookup` based defines. The test will
run with a completed forked classloader so not to pollute the
main classloader.
This commit also adds some useful additional APIs.
See gh-28120
Add a new unpublished `spring-core-test` module to support testing of
generated code. The module include a `TestCompiler` class which can be
used to dynamically compile generated Java code. It also include an
AssertJ friendly `SourceFile` class which uses qdox to provide targeted
assertions on specific parts of a generated source file.
See gh-28120
Sam Brannen
Brian Clozel
Scott Frederick
Phillip Webb
Stephane Nicoll