Skip to main content

Test Agent

The Drill4J Test Agent allows you to map tests to code coverage and vice versa. Key Features:

  • Test context propagation
  • Control over test execution

General integration steps are:

  1. Download Drill4J agent files
  2. Set path to agent when running tests
  3. Set agent parameters

Due to the diverse tools used in software development — such as CI/CD providers, deployment methods, testing stages — the exact process will depend on the environment.

How to download#

Download agent files manually#

Note: This is not the most convenient way to get agent files. If you are using Maven or Gradle, there is a primary way, see next section.

The most basic way to get agent files is to download release .zip manually.

  1. Download release appropriate for your platform at https://github.com/Drill4J/autotest-agent/releases/tag/v0.23.1.

    mingwX64 is for Windows, Linux and Mac releases are called respectively.

  2. Unzip the file. Rename unzipped folder to agent.

  3. Inside you'll find the following files:

    • libdrill_agent.so (on Windows - .dll, on Mac - .dylib)
    • drill-runtime.jar
    • drill.properties

Refer to next section for further steps.

Use Drill4J CI/CD Integration Plugin for Maven and Gradle#

Use cases: when application (or certain classes of application) is launched with Maven or Gradle. That's most often the case with Unit tests.

Drill4J CI/CD Integration Plugin automatically downloads agent files and passes required parameters to Java when running tests.

Because of that, the next sections of this page are irrelevant in this scenario. Instead, please refer to CI/CD Integration Plugin page for more info.

How to set path to agent when running tests#

Test agent use -agentpath JVM command line argument to loading when starting java process.

# Linux
java -agentpath:/agent/libdrill_agent.so
# Windows
java -agentpath:/agent/drill_agent.dll
# macOS
java -agentpath:/agent/libdrill_agent.dylib

In order to pass -agentpath command-line argument when running tests, you can configure the argLine for Maven or jvmArgs for Gradle parameters.

There are two way to pass -agentpath parameter:

  • In command line for running tests
  • Inside the build configuration file

Pass -agentpath in command line for running tests#

Gradle#

Add -DjvmArgs parameter to gradle command line:

./gradlew test -DjvmArgs=-agentpath:/path/to/agent
Maven#

Add -DargLine parameter to Maven command line:

./mvn test -DargLine=-agentpath:/path/to/agent

Set -agentpath in the build configuration file#

Gradle#

Add jvmArgs to Gradle test configuration:

test {
jvmArgs = '-agentpath:/path/to/agent'
}
Maven#

Add argLine to maven-surefire-plugin in pom.xml:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>-agentpath:/path/to/agent</argLine>
</configuration>
</plugin>

How to set agent parameters#

Drill4J Test Agent has the same ways to set agent parameters that Application Agent. To know how to use it see the Application Agent reference.

Agent parameters reference#

ParameterRequiredExample ValueDescription
apiUrlyeshttp://localhost/apiURL to Drill4J Admin /api endpoint.
apiKeyyes1_01cdf51ff20544ee...Drill4J Backend API key. Generate it using Drill4J UI. Please make sure to read the apiKey security section
groupIdyesmy-cool-appUnique arbitrary string identifying your application group.
withJsCoveragenotrueEnables collecting JS coverage by Chrome DevTools
devToolsProxyAddressnohttp://localhost:8092URL address of Drill4J DevToolsProxy

API key security#

❗ Please avoid hardcoding apiKey and exposing it in plain text. Instead, use environment variables. ❗

Bad example:

-agentpath:/agent/libdrill_agent.so=drillApiKey=123

Good example:

# Set DRILL_API_KEY variable prior to application launch
DRILL_API_KEY=123
# exact syntax for env variables will depend on your environment

Troubleshooting#

How to confirm agent is loaded#

Once loaded Drill4J agent prints the following ASCII logo:

____ ____ _ _ _ _ _
| _"\U | _"\ u ___ |"| |"| | ||"| U |"| u
/| | | |\| |_) |/ |_"_| U | | u U | | u | || |_ _ \| |/
U| |_| |\| _ < | | \| |/__ \| |/__ |__ _| | |_| |_,-.
|____/ u|_| \_\ U/| |\u |_____| |_____| /|_|\ \___/-(_/
|||_ // \\_.-,_|___|_,-.// \\ // \\ u_|||_u _//
(__)_) (__) (__)\_)-' '-(_/(_")("_)(_")("_) (__)__) (__)
Test Agent (v0.23.1)

It indicates that you have configured agent path correctly and Java picked up and loaded agent files.

Cannot load the agent because some agent parameters are set incorrectly#

If below Drill4J ASCII logo you see the following message:

ERROR [com.epam.drill.agent.configuration.ValidatedParametersProvider] Cannot load the agent because some agent parameters are set incorrectly. Please
check the following parameters:

It indicates that you are missing some required parameters. Refer to the agent parameters section.

Error "Could not create an Appender of type ..."#

|-ERROR in com.epam.drill.autotest.shadow.ch.qos.logback.core.joran.action.AppenderAction - Could not create an Appender of type [ch.qos.logback.core.ConsoleAppender].
|-ERROR in com.epam.drill.autotest.shadow.ch.qos.logback.core.joran.spi.Interpreter@5:73 - ActionException in Action for tag [appender]

The following error can be safely ignored as it doesn’t impact the functionality of the application or agent. It simply indicates that Logback is being used with a logback.xml file, which conflicts with the Drill4J logging configuration. However, logging will still function as expected.

Limitations and Known Issues#

  1. The Drill4J is not compatible with the JaCoCo code coverage tool. JaCoCo conflicts with the Drill4J Test Agent and Application Agent, so it needs to be removed. This should’t be a concern, as Drill4J includes the same functionality along with additional features.