Использование Offline инструментации JaCoCo в Web приложении на Maven

В статьях написанных ранее мной было рассмотрено использование JaCoCo Java агента различными способами (статья 1 и статья 2)
Однако, может возникнуть ситуация, когда, по каким либо причинам, использование Java агента либо не возможно, либо не удобно.

Для такого случая JaCoCo предоставляет возможность выполнить офлайн инструментацию кода (offline instrumentation).

Оффлайн инструментация может быть полезна в следующих случаях:
- в окружении, где невозможно передать JVM опции при запуске приложения
- в окружении, где невозможно использовать JaCoco агент при запуске приложения
- при наличии конфликтов с другими Java агентами
- при необходимости конвертации байткода для других VM.

Выполнение offline инструментации приведет к тому, что байткод всех классов проекта будет модифицирован, чтобы выполнять подсчеты, требуемые для генерации отчета о покрытии кода.

Для того чтобы получить отчет о покрытии кода с помощью оффлайн инструментации, необходимо выполнить 3 шага:
- провести инструментацию кода
- добавить JaCoCo агент в classpath
- передать параметры конфигурации в JaCoCo агент

Далее будет подробно рассмотрено как выполнить каждый из шагов.

1. Инструментация кода.
Для проведения инструментации кода при сборке проекта необходимо добавить в pom.xml jacoco-maven-plugin с выполнением цели instrument на фазе prepare-package.
Также дополнительно желательно добавить восстановление исходных классов проекта после фазы package при помощи цели restore-instrumented-classes. Это необязательный шаг, однако его желательно делать, т.к. наличие инструментированных классов может привести к проблемам с отображением отчетов по покрытию в IDE, также к невозможности сделать package 2 раза подряд (без выполнения фазы clean).
Полный код jacoco-maven-plugin для добавления оффлайн инструментации будет выглядеть следующим образом:

  
  <plugin>
    <groupid>org.jacoco</groupid>
    <artifactid>jacoco-maven-plugin</artifactid>
    <version>0.8.2</version>
    <executions>
      <execution>
        <id>jacoco-instrument-package</id>
        <phase>prepare-package</phase>
        <goals>
          <goal>instrument</goal>
        </goals>
      </execution>
      <execution>
        <id>jacoco-restore-package</id>
        <phase>package</phase>
        <goals>
          <goal>restore-instrumented-classes</goal>
        </goals>
      </execution>
    </executions>
  </plugin>

2. Добавление JaCoCo агента в classpath.
Для того, чтобы инструментированный код отработал корректно, необходимо чтобы в classpath находился jar файл JaCoCo агента.
Чтобы файл JaCoCo агента автоматически попал в classpath, его необходимо добавить как зависимость проекта. Обратите внимание, что зависимость имеет classifier runtime.
Scope можно установить в runtime, т.к. использование напрямую зависимости из исходного кода не предполагается.

  
  <dependency>
    <groupid>org.jacoco</groupid>
    <artifactid>org.jacoco.agent</artifactid>
    <classifier>runtime</classifier>
    <scope>runtime</scope>
    <version>0.8.2</version>
  </dependency>

3. Конфигурирование JaCoCo агента.
Полный список возможных параметров JaCoCo агента доступен здесь.

Конфигурирование можно быть выполнено одним из двух способов:
- Передать параметры в качестве VM опций при запуске программы. В таком случае к каждому параметру надо добавить префикс jacoco-agent. Например так:

   -Djacoco-agent.output="file" -Djacoco-agent.destfile="D:/jacoco.exec"

- Поместить файл jacoco-agent.properties с параметрами в classpath. К примеру, файл jacoco-agent.properties может выглядеть так:

  
  output=file
  destfile=D:/jacoco.exec

После выполнения всех 3-х шагов необходимо пересобрать проект и запустить приложения.
При конфигурации указанной выше отчет будет сгенерирован после остановки выполнения приложения.

Также JaCoCo предоставляет возможность получать отчет по покрытию во время выполнения приложения (например, через JMX). Для этого нужно соответствующим образом сконфигурировать JaCoCO агент.