How to define agent for a test run in Gradle and Maven (JEP 451 workaround)

[nineninesevenfour]

This is not a question, I rather want to share the result of my research.

Background

JEP 451 with JDK 21 is the first step to restrict dynamic loading of agents. Currently when calling ByteBuddyAgent.install() with JDK 21 one will recieve the following warings:

WARNING: A Java agent has been loaded dynamically (C:\Users\<user>\.m2\repository\net\bytebuddy\byte-buddy-agent\1.14.6\byte-buddy-agent-1.14.6.jar)
WARNING: If a serviceability tool is in use, please run with -XX:+EnableDynamicAgentLoading to hide this warning
WARNING: If a serviceability tool is not in use, please run with -Djdk.instrument.traceUsage for more information
WARNING: Dynamic loading of agents will be disallowed by default in a future release

-XX:+EnableDynamicAgentLoading cannot be seen as a permanent solution as well. It is there for monitoring purposes. Dyamic loading of an agent from a jar already present on the class path will be prohibited in a future JDK version.

So I wanted to know how to add -javaagent to a test run including downloading the dependency to the agent from the configured repositories. This is the result:
(corrections and comments are of course welcome).

Gradle

The artifact byte-buddy-agent can be resolved with an auxiliary configuration item byteBuddyAgent + using configurations.byteBuddyAgent.singleFile (the name of the configuration can be chosen according to personal taste, of course).

plugins {
    id 'java'
}

group = 'org.example'
version = '1.0-SNAPSHOT'

repositories {
    mavenCentral()
}

configurations {
    byteBuddyAgent
}

dependencies {
    testImplementation platform('org.junit:junit-bom:5.9.1')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    byteBuddyAgent "net.bytebuddy:byte-buddy-agent:1.14.5"
}

test {
    useJUnitPlatform()
    jvmArgs( "-javaagent:${ configurations.byteBuddyAgent.singleFile }" )
}

--> 5 Lines added

Maven

Usage of maven-dependency-plugin to create a temporary copy beneath the target directory. This avoids having to specify an absolute path (to the local repo). However the version must be repeated in -javaagent, therefor I used an additional byte.buddy.version property.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>maven-playground</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <byte.buddy.version>1.14.5</byte.buddy.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <!-- copy agent jar either from local or remote repository -->
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.6.0</version>
                <executions>
                    <execution>
                        <!-- the correct phase is important so it is available before the test starts -->
                        <phase>test-compile</phase>
                        <goals>
                            <goal>copy</goal>
                        </goals>
                        <configuration>
                            <artifact>net.bytebuddy:byte-buddy-agent:${byte.buddy.version}</artifact>
                            <!-- store within separate "test-agent" directory beneath "target" -->
                            <outputDirectory>${project.build.directory}/test-agent</outputDirectory>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.1.2</version>
                <configuration>
                    <!-- pick jar from "target/test-agent" -->
                    <argLine>-javaagent:"${project.build.directory}/test-agent/byte-buddy-agent-${byte.buddy.version}.jar"</argLine>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

--> 1 property + 2 plugin configurations added

Test Code

To test the actual presence of the ByteBuddy agent I used:

    @Test
    public void testByteBuddyAgentPresent() throws ReflectiveOperationException {
        Class<?> agentClass = Class.forName("net.bytebuddy.agent.ByteBuddyAgent");
        Method getInstrumentation = agentClass.getMethod("getInstrumentation");
        Object instrumentation = getInstrumentation.invoke(null);
        // instanceof includes non-null-check
        assertTrue(instrumentation instanceof Instrumentation);
        System.out.println("test passed: we have ByteBuddy!");
    }

Conclusion

• It is possible, but not super elegant. I hope Gradle and Maven will come up with easier ways for configuring agents.
• One can keep using ByteBuddyAgent.install(), because luckily it tries getInstrumentation() first and will therefor resolve (the instrumentation of) the previously configured Java agent and skip dynamic installation.

[raphw]

The easiest approach I know is to specify -XX:+EnableDynamicAgentLoading (and -Djdk.attach.allowAttachSelf=true for performance). Then you can simply use ByteBuddyAgent.install() from your application.