Setup > Java Agent

This page is mostly for researchers and tool developers.

There are three modes for running Ekstazi as a Java agent: JUnit mode, single mode, and multi mode.

1. JUnit Mode

This mode will automatically start collecting dependencies for each JUnit test class. The only argument that is required is the following:

java -javaagent:org.ekstazi.core-${version}.jar=mode=junit MAIN

If your configuration spawns one JVM per test class (e.g., "fork='true'/forkmode='perTest'" in Ant or "forkCount=1/reuseForks=false" in Maven), you can use "junitFork" to obtain somewhat better performance. However, configuring the most optimal "junitFork" is rather complex. We suggest that you use Ant Task or Maven Plugin, which automatically configure the most optimal mode.

2. Single Mode

This mode should be used to collect dependencies for the entire run in a single JVM. Note that this mode does not require any code change. To collect coverage for a run of a JVM, provide -javaagent argument. Below is an example of how to collect dependencies in this mode, and store them in a file called "NAME.cov":

java -javaagent:org.ekstazi.core-${version}.jar=mode=single,single.name=NAME MAIN

3. Multi Mode

This mode should be used to support other testing frameworks (e.g., TestNG), integrate Ekstazi in a project that runs multiple processes, etc. Ekstazi offers primitives to check whether any dependency is modified, to start collecting dependencies, and to finish collecting dependencies. These primitives can be called from any Java code (e.g., a TestNG listener).

org.ekstazi.Ekstazi.inst().checkIfAffected("name")

checks if dependencies saved under the given "name" are changed/affected. This method returns true if at least one dependency changed; false otherwise.

org.ekstazi.Ekstazi.inst().startCollectingDependencies("name")

starts collecting dependencies under the given "name".

org.ekstazi.Ekstazi.inst().finishCollectingDependencies("name")

finishes collecting dependencies under the given "name". This method will also save collected dependencies to the appropriate file (in .ekstazi directory).

Note that the invocations to start and finish collecting dependencies should not be nested. Here is an example of a correct usage of these primitives:

if (org.ekstazi.Ekstazi.inst().checkIfAffected("name")) {
    org.ekstazi.Ekstazi.inst().startCollectingDependencies("name");
    try {
        // Collecting dependencies for code here.
    } finally {
        org.ekstazi.Ekstazi.inst().finishCollectingDependencies("name");
    }
}

Once when the code is modified (as illustrated above) to collect dependencies at appropriate places, Ekstazi can be run in multi mode as follows:

java -javaagent:org.ekstazi.core-${version}.jar=mode=multi MAIN

4. Updating pom.xml and build.xml to include Java agent

We illustrate how to include Ekstazi agent in Maven and Ant configuration files.

The following box illustrates how to integrate Ekstazi in pom.xml. (Although we show the configuration for "JUnit Mode", the same changes are needed for other modes.)

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>-javaagent:org.ekstazi.core-${version}.jar=mode=junit</argLine>
  </configuration>
</plugin>

The following box illustrates how to integrate Ekstazi in build.xml. (Although we show the configuration for "JUnit Mode", the same changes are needed for other modes.)

<junit ...>
  <jvmarg value="-javaagent:org.ekstazi.core-${version}.jar=mode=junit" />
</junit>

Note that "jvmarg" is valid only if "fork" is on. In case you want to run all tests in a single JVM and to use Ekstazi agent, the following may be an option:

<junit fork="yes" forkmode="once">
  <jvmarg value="-javaagent:org.ekstazi.core-${version}.jar=mode=junit" />
</junit>