Проблема

Основным средством для командной работы с репозиторием компании, в которой я работаю, является Gitlab. На первый взгляд, он хорош: и бесплатной версии хватает сполна, и CI/CD - пайплайн имеется, и хранить артефакты тоже можно (долой Nexus). Однако, и у GitLab есть свои минусы.

Так, например, разработчики до сих пор не смогли реализовать визуализацию покрытия тестов. Да, она у них есть, но для её реализации нужно сгенерировать и загрузить в GitLab отчет о покрытии в устаревшем формате Cobertura, а не в актуальном Jacoco. Основная же проблема в том, что Cobertura plugin последний раз обновлялся в далеком 2015 году. 

То есть этот плагин уже не поддерживается Java 8. Прикрепляю ссылки на официальные источники, чтобы вы могли понять, насколько там все запущено))

И что же нам предлагает сделать GitLab? Он сделал все «по-человечески»? Нет))) он предложил использовать скрипт на Python для перевода отчета в формате Jacoco в отчет в формате Cobertura.

Выглядит это так:

test-jdk11:
  stage: test
  image: maven:3.6.3-jdk-11
  script:
    - mvn $MAVEN_CLI_OPTS clean org.jacoco:jacoco-maven-plugin:prepare-agent test jacoco:report
  artifacts:
    paths:
      - target/site/jacoco/jacoco.xml

coverage-jdk11:
  # Must be in a stage later than test-jdk11's stage.
  # The `visualize` stage does not exist by default.
  # Please define it first, or choose an existing stage like `deploy`.
  stage: visualize
  image: registry.gitlab.com/haynes/jacoco2cobertura:1.0.7
  script:
    # convert report from jacoco to cobertura, using relative project path
    - python /opt/cover2cover.py target/site/jacoco/jacoco.xml $CI_PROJECT_DIR/src/main/java/ > target/site/cobertura.xml
  needs: ["test-jdk11"]
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: target/site/cobertura.xml

Подробнее об этом решении по ссылке.

Громоздко, правда? Даже приходится подключать дополнительный образ, чтобы скрипт заработал.

Наша компания не единственная, кто заметил эту проблему. Так в 2020 году Markus Schuch создал запрос разработчикам GitLab о добавлении поддержки отчетов о покрытии в формате Jacoco. Но решение данной проблемы так и не сдвинулось с места. Поэтому руководством нашей компании мне было поручено написать плагин, который будет переводить отчет jacoco.xml в cobertura.xml. Таким образом, в компании решили сразу 2 задачи: и получили необходимый функционал, и заняли делом джуна.

Решение

Было решено написать плагин, который упростит создание отчета в формате Cobertura. Принцип работы плагина: перевести отчет формата Jacoco в Cobertura.

Проблемы написания плагина

Подбор библиотек

Сначала для парсинга файла формата XML необходимо было подобрать библиотеку. Так как существует множество разновидностей библиотек со своими плюсами и минусами выбор оказался непростым.

Например, DOM парсер – это древовидный синтаксический анализатор. Таким парсером очень удобно искать элементы в файле, но у него есть недостаток – скорость.

SAX парсер работает иначе, он не создает никакой доменной структуры, а последовательно читает/записывает XML файл. Поэтому SAX парсер работает гораздо быстрее чем DOM, но он не умеет так же хорошо искать элементы файла. Поэтому мной была выбрана библиотека JDOM2 для чтения jacoco.xml и SAX для записи в cobertura.xml.

Написание алгоритма преобразования Jacoco в Cobertura

Основная идея алгоритма была позаимствована из питоновского скрипта cover2cover.py. Однако, немного изменить логику алгоритма всё же пришлось. Например, различная работа XML библиотек в Python и Java, различный результат при математических вычислениях чисел с плавающей запятой.

После того как стало понятно, что алгоритм, написанный на Java, выдает такие же отчеты, что и cover2cover.py необходимо было реализовать удобство применения в сторонних java приложениях. Очевидно, что для этого необходимо написать плагин. О том как написать плагин есть хорошая статья.

Всего в мой плагин можно передать 3 переменные:

• source - путь к файлу формата Jacoco (дефолтное значение: target/site/jacoco/jacoco.xml);

• result - путь, куда файл cobertura.xml будет размещен после работы плагина (дефолтное значение: target/site/cobertura/cobertura.xml);

• pathsToProject - список путей к классам относительно корня проекта (дефолтное значение: /src/main/java/).

Важно, чтобы по пути, указанному в source, лежал jacoco.xml, иначе перевод не отработает. Также в pathsToProject можно передавать как один путь к пакетам, так и несколько путей, если проект мультимодульный.

Например, для проекта со структурой:

pet-parent/
    +- pet/
        +- src/
            +- main/
                +- java/
                    +- pom.xml
                    ...
    +- pet-api/
        +- src/
            +- main/
                +- java/
                    +- pom.xml
                    ...
    +- pet-test/
        +- pom.xml
    +- pom.xml

Необходимо передать пути /pet-api/src/main/java/ и /pet/src/main/java/. Теперь покрытия тестами обоих модулей будут видны!

Как пользоваться

В pom.xml

Плагин очень просто добавить в pom.xml, и он будет генерировать отчет cobertura.xml туда, куда Вам потребуется. В общем, работает он также, как и Jacoco плагин, а главное условие выполнения - правильно указать параметры и поставить его в pom.xml после Jacoco плагина.

Вот фрагмент pom.xml, в котором наглядно показано, как настраивать плагин:

<project>
    ...
    <build>
        <!-- To use the plugin goals in your POM or parent POM -->
        <plugins>
            ...
            <plugin>
              <groupId>ru.siblion.lab</groupId>
              <artifactId>jacocoToCobertura-maven-plugin</artifactId>
              <version>0.0.2</version>
              <executions>
                <execution>
                  <goals>
                    <goal>convert</goal>
                  </goals>
                <phase>test</phase>
              </execution>
            </executions>
            <configuration>
              <source>path to jacoco.xml</source>
              <result>path to cobertura.xml</result>
              <pathsToProject>path to project files</pathsToProject>       
            </configuration>
          </plugin>
            ...
        </plugins>
    </build>
    ...
</project>

А для мультимодульного проекта (возьмем пример из прошлой главы) параметр pathsToProject будет выглядеть так:

<pathsToProject>/pet/src/main/java/,/pet-api/src/main/java/</pathsToProject>

То есть просто перечисляем через запятую. Теперь каждый раз после запуска тестов будет появляться отчет в формате Cobertura)))

В .gitlab-ci.yml необходимо будет добавить, чтобы GitLab увидел отчет:

artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: target/cobertura/cobertura.xml

В CI/CD пайплайне

Иногда не хочется лишний раз изменять pom.xml, чтобы ничего не поломалось. Поэтому работу jacocoToCobertura плагина можно настроить в файле .gitlab-ci.yml:

mvn-test:
  stage: test
  script:
    - "./mvnw -ntp -s .m2/settings.xml --batch-mode clean test"
  artifacts:
    paths:
      - target/site/jacoco/jacoco.xml

  only:
    - merge_requests
    - main

coverage:
  stage: visualize
  script:
    - "./mvnw $MAVEN_CLI_OPTS dependency:get -Dartifact=ru.siblion.lab:jacocoToCobertura-maven-plugin:0.0.2"
    - "./mvnw $MAVEN_CLI_OPTS ru.siblion.lab:jacocoToCobertura-maven-plugin:0.0.2:convert
        -Dsource="target/site/jacoco/jacoco.xml"
        -Dresult="target/site/cobertura/cobertura.xml"
        -DpathesToProject="${CI_PROJECT_DIR}/src/main/java/""
  coverage: "/Total.*?([0-9]{1,3})%/"
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: target/site/cobertura/cobertura.xml

  only:
    - merge_requests
    - main

Результат

Теперь после успешного выполнения пайплайна в изменениях в merge request появится красивая подсветка, которая показывает какой код покрыт тестами, а какой нет.

Кроме того, после выполнения пайплайна итоговое покрытие проекта будет отображаться в Jobs пайплайна.

Технические ограничения

Плагин написан на Java 17. Требуется наличие Jacoco plugin, стоящий в файле pom.xml выше, чем jacocoToCobertura-plugin. Визуализация покрытия сохраняется неделю, но затем пропадает.

Ограничения от GitLab: не более 100 источников source в отчете, то есть не более 100 модулей в проекте. Размер одного XML-файла Cobertura не может превышать 10 МБ. Подробнее про ограничения от GitLab тут.

Заключение

Этот плагин выложен на Maven Central, я надеюсь что он сможет сделать ваш merge request чуточку ярче))) Если есть идеи и предложения по улучшению, пишите. Исходники прикреплены.

Авторы

• Дмитриев Егор

• Митрофанов Сергей

Ссылки

• GitHub

• Ссылка на плагин

• Siblion