JaCoCo - jacoco:prepare-agent

# jacoco:prepare-agent

Full name:

org.jacoco:jacoco-maven-plugin:0.6.3.201306030806:prepare-agent

Description:

Prepares a property pointing to the JaCoCo runtime agent that can be passed as a VM argument to the application under test. Depending on the project packaging type by default a property with the following name is set:

- tycho.testArgLine for packaging type eclipse-test-plugin and
- argLine otherwise.

Resulting coverage information is collected during execution and by default written to a file when the process terminates.

Attributes:

- Requires a Maven project to be executed.
- Requires dependency resolution of artifacts in scope: `runtime`.
- The goal is thread-safe and supports parallel builds.
- Binds by default to the lifecycle phase: `initialize`.

## Optional Parameters

Name | Type | Since | Description
address | `String` | `-` | IP address or hostname to bind to when the output method is tcpserver or connect to when the output method is tcpclient. In tcpserver mode the value "*" causes the agent to accept connections on any local address.
append | `Boolean` | `-` | If set to true and the execution data file already exists, coverage data is appended to the existing file. If set to false, an existing execution data file will be replaced.
classDumpDir | `File` | `-` | If a directory is specified for this parameter the JaCoCo agent dumps all class files it processes to the given location. This can be useful for debugging purposes or in case of dynamically created classes for example when scripting engines are used.
destFile | `File` | `-` | Path to the output file for execution data. Default value is: `${project.build.directory}/jacoco.exec`.
dumpOnExit | `Boolean` | `-` | If set to true coverage data will be written on VM shutdown.
exclClassLoaders | `String` | `-` | A list of class loader names, that should be excluded from execution analysis. The list entries are separated by a colon (:) and may use wildcard characters (* and ?). This option might be required in case of special frameworks that conflict with JaCoCo code instrumentation, in particular class loaders that do not have access to the Java runtime classes.
excludes | `List` | `-` | A list of class files to exclude from instrumentation/analysis/reports. May use wildcard characters (* and ?). When not specified nothing will be excluded.
includes | `List` | `-` | A list of class files to include in instrumentation/analysis/reports. May use wildcard characters (* and ?). When not specified everything will be included.
jmx | `Boolean` | `-` | If set to true the agent exposes functionality via JMX.
output | `String` | `-` | Output method to use for writing coverage data. Valid options are: file: At VM termination execution data is written to the file specified in the `destfile`. tcpserver: The agent listens for incoming connections on the TCP port specified by the `address` and `port`. Execution data is written to this TCP connection. tcpclient: At startup the agent connects to the TCP port specified by the `address` and `port`. Execution data is written to this TCP connection. none: Do not produce any output.
port | `Integer` | `-` | Port to bind to when the output method is tcpserver or connect to when the output method is tcpclient. In tcpserver mode the port must be available, which means that if multiple JaCoCo agents should run on the same machine, different ports have to be specified.
propertyName | `String` | `-` | Allows to specify property which will contains settings for JaCoCo Agent. If not specified, then "argLine" would be used for "jar" packaging and "tycho.testArgLine" for "eclipse-test-plugin".
sessionId | `String` | `-` | A session identifier that is written with the execution data. Without this parameter a random identifier is created by the agent.
skip | `boolean` | `-` | Flag used to suppress execution. Default value is: `false`.

## Parameter Details

address:

IP address or hostname to bind to when the output method is tcpserver or connect to when the output method is tcpclient. In tcpserver mode the value "*" causes the agent to accept connections on any local address.

- Type: `java.lang.String`
- Required: `No`
- Expression: `${jacoco.address}`

append:

If set to true and the execution data file already exists, coverage data is appended to the existing file. If set to false, an existing execution data file will be replaced.

- Type: `java.lang.Boolean`
- Required: `No`
- Expression: `${jacoco.append}`

classDumpDir:

If a directory is specified for this parameter the JaCoCo agent dumps all class files it processes to the given location. This can be useful for debugging purposes or in case of dynamically created classes for example when scripting engines are used.

- Type: `java.io.File`
- Required: `No`
- Expression: `${jacoco.classDumpDir}`

destFile:

Path to the output file for execution data.

- Type: `java.io.File`
- Required: `No`
- Expression: `${jacoco.destFile}`
- Default: `${project.build.directory}/jacoco.exec`

dumpOnExit:

If set to true coverage data will be written on VM shutdown.

- Type: `java.lang.Boolean`
- Required: `No`
- Expression: `${jacoco.dumpOnExit}`

exclClassLoaders:

A list of class loader names, that should be excluded from execution analysis. The list entries are separated by a colon (:) and may use wildcard characters (* and ?). This option might be required in case of special frameworks that conflict with JaCoCo code instrumentation, in particular class loaders that do not have access to the Java runtime classes.

- Type: `java.lang.String`
- Required: `No`
- Expression: `${jacoco.exclClassLoaders}`

excludes:

A list of class files to exclude from instrumentation/analysis/reports. May use wildcard characters (* and ?). When not specified nothing will be excluded.

- Type: `java.util.List`
- Required: `No`

includes:

A list of class files to include in instrumentation/analysis/reports. May use wildcard characters (* and ?). When not specified everything will be included.

- Type: `java.util.List`
- Required: `No`

jmx:

If set to true the agent exposes functionality via JMX.

- Type: `java.lang.Boolean`
- Required: `No`
- Expression: `${jacoco.jmx}`

output:

Output method to use for writing coverage data. Valid options are:

- file: At VM termination execution data is written to the file specified in the `destfile`.
- tcpserver: The agent listens for incoming connections on the TCP port specified by the `address` and `port`. Execution data is written to this TCP connection.
- tcpclient: At startup the agent connects to the TCP port specified by the `address` and `port`. Execution data is written to this TCP connection.
- none: Do not produce any output.

- Type: `java.lang.String`
- Required: `No`
- Expression: `${jacoco.output}`

port:

Port to bind to when the output method is tcpserver or connect to when the output method is tcpclient. In tcpserver mode the port must be available, which means that if multiple JaCoCo agents should run on the same machine, different ports have to be specified.

- Type: `java.lang.Integer`
- Required: `No`
- Expression: `${jacoco.port}`

propertyName:

Allows to specify property which will contains settings for JaCoCo Agent. If not specified, then "argLine" would be used for "jar" packaging and "tycho.testArgLine" for "eclipse-test-plugin".

- Type: `java.lang.String`
- Required: `No`
- Expression: `${jacoco.propertyName}`

sessionId:

A session identifier that is written with the execution data. Without this parameter a random identifier is created by the agent.

- Type: `java.lang.String`
- Required: `No`
- Expression: `${jacoco.sessionId}`

skip:

Flag used to suppress execution.

- Type: `boolean`
- Required: `No`
- Expression: `${jacoco.skip}`
- Default: `false`