io.earcam.instrumental.agent.junit.rule

Class AgentRule

java.lang.Object

io.earcam.instrumental.agent.junit.rule.AgentRule

All Implemented Interfaces:

org.junit.rules.TestRule

public class AgentRule
extends Object
implements org.junit.rules.TestRule

A JUnit rule capable of adding a Java Agent dynamically. If the agent class provided is determined to have been loaded from a directory, then the assumption is that you're testing an agent. In which case an temporary JAR is created and populated with you're agent class and necessary MANIFEST.MF entries. Otherwise the agent class is considered to be loaded from an existing JAR. In which case this is simply added to the running JVM. Notes:

• You should not reference any class intended to be instrumented as a static field or as argument to the AgentRule. If this is unavoidable then you must invoke reinstrumentation of the relevant classes. However, it should be noted that, reinstrumentation would not be able to remove any class's final modifier
• Entirely dependent on the com.sun.tools.attach API
• Once loaded the agent is not unloaded, worth bearing in mind when reusing JVMs across tests
• Specifying the Agent class via the rule is nothing more than a convenience - the JVM will not hold the same loaded definition of the Agent class as used in the tests, therefore attempts to share state (e.g. via statics) will be in vain
• Dependencies for the Agent class should be provided at test scope or alternatively at runtime scope with optional=true, if not already present
• This does not support native JVM TI agents

Method Summary

Modifier and Type	Method and Description
static AgentRule	agent(Class<?> agentClass, String agentArguments) Dynamically load an agent from the supplied class (created a JAR behind the scenes).
static AgentRule	agent(Path agentJarFile, String agentArguments) Dynamically load an agent from the supplied jar file.
org.junit.runners.model.Statement	apply(org.junit.runners.model.Statement base, org.junit.runner.Description description)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

agent

public static AgentRule agent(Path agentJarFile,
                              String agentArguments)

Dynamically load an agent from the supplied jar file.

Parameters:

agentJarFile - a Path object.

agentArguments - a String object.

Returns:

a AgentRule object.

agent

public static AgentRule agent(Class<?> agentClass,
                              String agentArguments)

Dynamically load an agent from the supplied class (created a JAR behind the scenes).

Parameters:

agentClass - a Class object.

agentArguments - a String object.

Returns:

a AgentRule object.

apply

public org.junit.runners.model.Statement apply(org.junit.runners.model.Statement base,
                                               org.junit.runner.Description description)

Specified by:

apply in interface org.junit.rules.TestRule