Jenkins shared library for 1C:Enterprise 8

Цель

Создание библиотеки (или плагина) для Jenkins, позволяющей:

• максимально упростить написание Jenkinsfile для процесса CI в условиях платформы 1С:Предприятие 8
• иметь схожий и контролируемый пайплайн для всех проектов
• дать пользователю в руки простой декларативный конфигурационный файл, вместо требования описывать всю сложную логику по работе с 1С

Общие положения

• в активной разработке и поиске "своего пути" по разработке библиотеки;
• формат конфигурационного файла не стабилизирован;
• обратная совместимость пока не гарантируется, внимательно читайте changelog;
• количество stage будет со временем увеличиваться;
• использовать на свой страх и риск;
• любая помощь приветствуется.

Ограничения

1. Хранение исходников в корне репозитория или в каталоге первого уровня (например, в src) не рекомендуется.
2. Для шага подготовки требуется любой агент с меткой agent.
3. Для запуска шага анализа SonarQube требуется агент с меткой sonar.
4. Для запуска шагов, работающих с EDT (валидация, трансформация формата исходников) требуется агент с меткой edt (если используется несколько версий EDT необходимо к метке добавить версию, например edt@2021.3.4:x86_64) и агент с меткой oscript, на котором глобально установлена библиотека stebi версии 1.11.1 и выше или edt-ripper.
5. При использовании EDT версии 2024.1.0 и выше вместо ring используется 1cedtcli, который должен быть прописан в PATH на агенте.
6. Для запуска шагов, работающих с 1С (подготовка, синтаксический контроль и т.д.) требуется агент с меткой, совпадающей со значением в поле v8version файла конфигурации.
7. В качестве ИБ используется файловая база, создаваемая в каталоге ./build/ib. При необходимости вы можете создать пользователей на фазе инициализации ИБ.
8. На данный момент ошибка в vanessa-add не позволяет собирать замеры производительности в дымовых тестах по открытию всех форм на клиенте тестирования.
9. Для параллельного выполнения шагов bdd и smoke с включенными замерами покрытия на одной ноде необходимо, чтобы в jobConfiguration.json были указаны разные порты сервера отладки для каждого шага. Параллельные билды с замерами покрытия на одной ноде не поддерживаются.
10. Для сборов замеров покрытия в ОС Windows на мастер-ноде Jenkins, который запущен как служба под учетной записью LOCAL SYSTEM, необходимо использовать версию Coverage41C >= 2.7.3. Другие варианты обхода проблемы:
    1. запустить службу Jenkins под обычной учетной записью
    2. запретить выполнение сборок на мастер-ноде и настроить их выполнение на агенте, который запущен интерактивно под обычной учетной записью (рекомендуется).

Возможности

1. Все шаги можно запустить на базе docker-образов из https://github.com/firstBitMarksistskaya/onec-docker. См. памятку по слоям и последовательности сборки.
2. Поддержка как формата выгрузки из Конфигуратора, так и формата EDT.
3. Подготовка информационной базы по версии из хранилища конфигурации, из исходных файлов конфигурации, комбинированный режим (основная ветка - из хранилища, остальные - из исходников).
4. Подготовка и загрузка расширений конфигурации из исходных файлов расширения, из cfe-файлов.
5. Запуск ИБ в режиме выполнения обработчиков обновления БСП.
6. Дополнительные шаги инициализации данных в ИБ.
7. Трансформация кода из формата конфигуратора в формат EDT.
8. Трансформация кода из формата EDT в формат конфигуратора.
9. Запуск BDD сценариев с сохранением результатов в формате Allure.
10. Запуск юнит-тестов с помощью фреймворка YAXUnit с сохранением результатов в формате jUnit и Allure.
11. Запуск синтаксического контроля средствами конфигуратора и сохранение результатов в виде отчета jUnit.
12. Валидация проекта средствами EDT и трансформация отчета EDT в формат BSL LS с помощью edt-ripper или Generic Issue с помощью stebi.
13. Запуск статического анализа для SonarQube.
14. Публикация результатов junit и Allure в интерфейс Jenkins.
15. Рассылка результатов сборки на почту и в Telegram.
16. Конфигурирование логгера запускаемых oscript-приложений.
17. Замер покрытия при выполнении тестов.
18. Возможность сохранить информационную базу в виде артефакта сборки после выполнения шагов инициализации и\или после выполнения сценарных тестов.

Подключение

Инструкция по подключению библиотеки: https://jenkins.io/doc/book/pipeline/shared-libraries/#using-libraries

Примеры Jenkinsfile

Если в настройках подключения shared-library включен флаг "Load implicitly":

pipeline1C()

В обратном случае:

@Library('jenkins-lib') _

pipeline1C()

Да, вот и весь пайплайн. Конфигурирование через json.

Внешний вид пайплайна в интерфейсе Blue Ocean

Конфигурирование

По умолчанию применяется файл конфигурации из ресурсов библиотеки

Поверх него накладывается конфигурация из файла jobConfiguration.json в корне проекта, если он присутствует.

Пример переопределения:

• указывается точная версия платформы (и соответственно метка агента, см. ограничения)
• указывается точная версия модуля EDT (и соответственно метка агента, см. ограничения)
• идентификаторы credentials для пути к хранилищу и к паре логин/пароль для авторизации в хранилище (необходимы, если применяются шаги, работающие с информационной базой)
• включаются шаги запуска статического анализа SonarQube, валидации средствами EDT и синтаксического контроля

{
    "$schema": "https://raw.githubusercontent.com/firstBitMarksistskaya/jenkins-lib/master/resources/schema.json",
    "v8version": "8.3.14.1976",
    "edtVersion": "2021.3.4:x86_64",
    "secrets": {
        "storagePath": "f7b21c02-711a-4883-81c5-d429454e3f8b",
        "storage" : "c1fc5f33-67d4-493f-a2a4-97d3040e4b8c"
    },
    "stages": {
        "sonarqube": true,
        "edtValidate": true,
        "syntaxCheck": true
    }
}

Параметры по умолчанию

В библиотеке применяется принцип "соглашения по конфигурации" (convention over configuration): конфигурационный файл содержит ряд настроек "по умолчанию". При соблюдении определенных правил структуры репозитория можно сократить количество переопределений конфигурационного файла до минимума. Ниже представлены имеющиеся соглашения и способы их переопределения.

• Общее:
  • В качестве маски версии платформы используется строка "8.3" (v8version).
  • По умолчанию версия модуля EDT не заполнена, т.к. в случае единственной версии для утилиты ring дополнительного указания не требуется (edtVersion).
  • Исходники конфигурации ожидаются в каталоге src/cf (srcDir).
  • Формат исходников - выгрузка из Конфигуратора (sourceFormat).
  • Ветка по умолчанию (для комбинированного режима загрузки конфигурации) - "main" (defaultBranch).
  • Имена большинства "секретов" (jenkins credentials, secrets) по умолчанию высчитываются из пути к git-репозиторию (без учета домена, с заменой / на _) с прибавлением ключа секрета. Например, для репозитория https://github.com/firstBitSemenovskaya/jenkins-lib секрет с адресом хранилища будет выглядеть как firstBitSemenovskaya_jenkins-lib_STORAGE_PATH. Ключи секретов:
    • STORAGE_PATH - путь к хранилищу конфигурации (для secrets -> storagePath);
    • STORAGE_USER - параметры авторизации в хранилище вида "username with password" (для secrets -> storage).
    • TELEGRAM_CHAT_ID - идентификатор чата Telegram для рассылки уведомлений и результате сборки вида "secret text" (для secrets -> telegramChatId).
  • Секрет TELEGRAM_BOT_TOKEN задается глобально на весь сервер Jenkins, либо может быть переопределен (secrets -> telegramBotToken)
  • Все "шаги" по умолчанию выключены (stages).
  • Если в корне репозитория существует файл packagedef, то в шагах, работающих с информационной базой, будет выполнена попытка установки локальных зависимостей средствами opm.
  • Если после установки локальных зависимостей в каталоге oscript_modules/bin существует файл vrunner, то для выполнения команд работы с информационной базой будет использоваться он, а не глобально установленный vrunner из PATH.
  • Результаты в формате allure ожидаются в каталоге build/out/allure или его подкаталогах.
  • Каждый шаг имеет свой таймаут в минутах (от 10 до 240 в зависимости от "тяжёлости" шага сборки), но может быть переопределен в секции настроек timeout.
• Инициализация:
  • Информационная база инициализируется только в том случае, если в сборочной линии включены шаги, работающие с базой (например, bdd или syntaxCheck).
  • Информационная база инициализируется конфигурацией из хранилища конфигурации (initInfobase -> initMethod).
  • Если выбран метод инициализации ИБ из хранилища конфигурации и в каталоге исходников есть файл VERSION (артефакт от работы утилиты gitsync), то из хранилища будет загружена версия конфигурации с номером из файла VERSION.
• Первичный запуск информационной базы:
  • Если информационная база нужна для запуска в режиме "Предприятие" (например, для шагов bdd или smoke), то будет запущен шаг "Миграция ИБ".
  • После загрузки конфигурации в ИБ будет выполняться запуск ИБ с целью запуска обработчиков обновления из БСП (initInfobase -> runMigration).
  • Если в настройках шага инициализации не заполнен массив дополнительных шагов миграции (initInfobase -> additionalInitializationSteps), но в каталоге tools присутствуют файлы с именами, удовлетворяющими шаблону vrunner.init*.json, то автоматически выполняется запуск vrunner vanessa с передачей найденных файлов в качестве значения настроек (параметр --settings) в порядке лексикографической сортировки имен файлов.
• BDD:
  • Если в конфигурационном файле проекта не заполнена настройка bdd -> vrunnerSteps, то автоматически выполняется запуск vrunner vanessa --settings tools/vrunner.json.
  • Инструмент, который вызывается на шаге bdd с помощью команды vrunner vanessa, должен сохранять код возврата в файл build/out/bdd-exit-code.log. Например, в конфигурационном файле для Vanessa Automation нужно установить значение параметров:

...
"ВыгружатьСтатусВыполненияСценариевВФайл": true,
"ПутьКФайлуДляВыгрузкиСтатусаВыполненияСценариев": "build/out/bdd-exit-code.log",
...

Если файл не будет найден, то пайплайн будет считать, что шаг выполнился успешно.

• YAXUnit:
  • Если в репозитории существует файл tools/yaxunit.json, то он будет передан в качестве параметра для YAXUnit при запуске тестов. Если файла с таким именем нет, то в YAXUnit будет передан файл из текущей библиотеки resources/yaxunit.json. Он содержит минимально необходимые параметры и настроен на поиск сценариев в расширении с именем YAXUnit.
• Дымовые тесты:
  • Если в репозитории существует файл tools/vrunner.json, то запуск дымовых тестов будет выполняться с передачей файла в параметры запуска vrunner xunit --settings tools/vrunner.json (smoke -> vrunnerSettings).
  • Если установка локальных зависимостей opm установит пакет add, то будет использоваться обработка xddTestRunner.epf из локальных зависимостей.
  • Если в репозитории существует файл tools/xUnitParams.json, то этот путь к файлу будет передан в параметр запуска vrunner xunit --xddConfig ./tools/xUnitParams.json (smoke -> xUnitParams).
  • Если используемый конфигурационный файл (vrunner.json) не содержит настройку testsPath, то запускается полный комплект дымовых тестов, расположенных в $addRoot/tests/smoke.
  • По умолчанию включено формирование отчета в формате jUnit (smoke -> publishToJUnitReport) и выключено формирование отчета в формате Allure (smoke -> publishToAllureReport).
• Синтаксический контроль:
  • Если в репозитории существует файл tools/vrunner.json, то синтаксический контроль конфигурации с помощью конфигуратора будет выполняться с передачей файла в параметры запуска vrunner syntax-check --settings tools/vrunner.json (syntaxCheck -> vrunnerSettings).
  • Применяется группировка ошибок по метаданным (syntaxCheck -> groupErrorsByMetadata).
  • Выгрузка результатов в формат jUnit осуществляется в файл ./build/out/jUnit/syntax.xml (syntaxCheck -> pathToJUnitReport).
  • Если в репозитории существует файл ./tools/syntax-check-exception-file.txt, то команде запуска синтаксического контроля конфигурации данный файл будет передаваться как файл с исключениями сообщений об ошибках (параметр --exception-file) (syntaxCheck -> exceptionFile).
  • Конфигурационный файл по умолчанию уже содержит ряд "режимов проверки" для синтаксического контроля конфигурации (syntaxCheck -> checkModes).
• Трансформация результатов валидации EDT:
  • Используется stebi (параметр resultsTransform -> transformer)
  • Формат файла - generic issues для SonarQube 10.3+ (параметр resultsTransform -> genericIssueFormat)
  • stebi исключает из результатов анализа замечания, сработавшие на модулях с включенным запретом редактирования (желтый куб с замком) (параметры resultsTransform -> removeSupport и resultsTransform -> supportLevel).
• Анализ SonarQube:
  • Предполагается наличие единственной настройки SonarQube installation (sonarqube -> sonarQubeInstallation).
  • Используется sonar-scanner из переменной окружения PATH (sonarqube -> useSonarScannerFromPath).
  • Если использование sonar-scanner из переменной окружения PATH выключено, предполагается наличие настроенного глобального инструмента SonarQube Scanner с идентификатором инструмента sonar-scanner (sonarqube -> sonarScannerToolName).
  • Применяется расчет аргументов командной строки для работы branch plugin или коммерческих версий SonarQube (sonarqube -> branchAnalysisConfiguration).
  • Если разработка ведется с использованием подсистемы БСП "Обновление версии ИБ", то в значение параметра sonar.projectVersion=$configurationVersion утилиты sonar-scanner можно передавать версию из созданного общего модуля. Для этого необходимо заполнить параметр (sonarqube -> infoBaseUpdateModuleName). Если параметр не заполнен, версия передается из корня конфигурации.
  • По умолчанию шаг анализа не дожидается окончания фонового задания на сервере SonarQube и не анализирует результат прохождения Порога качества (sonarqube -> waitForQualityGate).
  • Если выполнялась валидация EDT, результаты валидации передаются утилите sonar-scanner как значение параметра sonar.externalIssuesReportPaths при использовании stebi или как значение параметра sonar.bsl.languageserver.reportPaths при использовании edt-ripper.
• Информационная база по умолчанию не сохраняется в виде артефакта сборки.
• Рассылка уведомлений:
  • Электронная почта:
    • Для отправки используется плагин email-ext. Шаблоны сообщений конфигурируются в настройках плагина.
    • Уведомления о результатах сборки по умолчанию рассылаются только при полном падении сборочной линии (notifications -> email -> onAlways, onFailure, onUnstable, onSuccess).
    • Лог сборки прикладывается к письму при полном падении сборочной линии и при отправке в режиме "всегда отправлять" (notifications -> email -> *options -> attachLog).
    • В качестве получателей писем (notifications -> email -> *options -> recipientProviders) в различных режимах отправки используются:
      • всегда - разработчики и запустивший сборку;
      • при падении - разработчики, запустивший сборку и подозреваемый в причине падения сборки;
      • при успехе - разработчики и запустивший сборку;
      • при нестабильной сборке (упавшие тесты) - разработчики и запустивший сборку.
    • Прямые получатели уведомлений не заполнены (notifications -> email -> *options -> directRecipients).
  • Telegram:
    • Уведомления о результатах сборки по умолчанию рассылаются всегда (notifications -> telegram -> onAlways, onFailure, onUnstable, onSuccess).

Настройка загрузки расширений

Если у вас есть расширения, которые необходимо загрузить в базу для проведения тестов и проверок, это можно сделать на этапе подготовки базы.

• При загрузке из исходников расширения должны быть в том же формате (edt или конфигуратора), что и основная конфигурация.
• Для загрузки расширений необходимо описать каждое из них в массиве (initInfobase -> extensions).

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

1. Укажите имя расширения(extensions -> name).
2. Определите метод загрузки для каждого расширения(extensions -> initMethod). Поддерживаются два метода загрузки:

• fromSource - загрузка из исходников;
• fromFile - загрузка cfe-файла.

1. Укажите путь до расширения или URL для скачивания cfe-файла(extensions -> path).

• В случае загрузки из исходников - необходимо указать путь к исходникам расширения
• В случае загрузки cfe - Укажите путь по которому будет скачан cfe. На данный момент можно указывать как локальный путь, так и url для скачивания cfe(Прим.: https://github.com/bia-technologies/yaxunit/releases/download/23.05/YAXUNIT-23.05.cfe)

1. Укажите этапы сборки, на которых должно быть загружено расширение (initInfobase -> extensions -> stages). Если оставить это поле пустым, то расширение будет загружено на этапе initInfobase и будет активно на всех последующих этапах. В противном случае расширение будет использоваться только на перечисленных этапах.

Пример конфигурации для загрузки расширений:

"initInfobase": {
    "extensions": [
        {
            "name": "ИмяРасширения1",
            "initMethod": "fromSource",
            "path": "путь/до/исходников/расширения",
            "stages": ["bdd", "yaxunit"]
        },
        {
            "name": "ИмяРасширения2",
            "initMethod": "fromFile",
            "path": "https://example.com/path/to/extension.cfe"
        }
    ]
}

Загрузка эталонной базы

Реализована возможность загрузки эталонной базы на этапе инициализации информационной базы. Для этого необходимо указать в конфигурационном файле параметр initInfobase -> templateDBPath:

"initInfobase": {
    "templateDBPath": "путь/до/файла/базы.dt"
}

• Поддерживается загрузка файлов формата .dt и .1CD.
• Путь к файлу базы может быть как локальным, так и удаленным (URL).
• После загрузки базы для инициализации будет использоваться файл настроек vanessa-runner (включая логин и пароль от ИБ), указанный в параметре initInfobase -> vrunnerSettings. По умолчанию используется файл tools/vrunner.json.

"initInfobase": {
    "templateDBPath": "путь/до/файла/базы.dt",
    "vrunnerSettings": "tools/vrunner.json"
}

Настройка шага YAXUnit

• Добавить расширение YAXUnit и дополнительные расширения с тестами можно в jobConfiguration.json -> initInfobase -> extensions. Они будут загружены при инициализации ИБ.
• Если ваши тесты размещены в отдельных расширениях, скопируйте файл ./resources/yaxunit.json из текущей библиотеки в свой репозиторий (./tools/yaxunit.json) и перечислите в нем имена ваших расширений.
• Если используется собственный файл tools/yaxunit.json, то значение параметра reportPath в нем должно быть равно ./build/out/yaxunit/junit.xml

Настройка трансформации результата валидации EDT

• При использовании SonarQube версии <10.3 и stebi формат отчета должен быть Generic_Issue (параметр resultsTransform -> genericIssueFormat)
• Трансформацию результатов может выполнять edt-ripper (параметр resultsTransform -> transformer). В этом случае замечания будут загружены в SonarQube в формате BSL LS, что позволяет полноценно управлять ими в SonarQube.

Сбор замеров покрытия

• Для сбора замеров покрытия на агентах требуется:
  • oscript с библиотекой v8find, которая по умолчанию есть в составе дистрибутива oscript
  • сервер отладки dbgs, который есть в составе дистрибутива платформы 1С:Предприятие
  • Coverage41C, его необходимо установить на агент отдельно
  • EDT нужной версии или отдельные jar-файлы из его каталога установки, подробнее см. в Coverage41C/README.md
• Если на агенте Coverage41C не включен в PATH, необходимо указать полный путь к нему в параметре coverage41CPath
• Сбор замеров покрытия активируется для каждого этапа отдельно с помощью установки параметра "coverage": true
• поддерживаются bdd и yaxunit, для использования замеров на этапе smoke ожидается исправление vanessa-add в этом PR
• Чтобы замеры в bdd, yaxunit, smoke могли выполняться параллельно на одном агенте, необходимо указывать для них разные порты отладки в параметре dbgsPort.
• Не забудьте настроить подключение клиентов тестирования к серверу отладки.

Пример настройки подключения для bdd:

jobConfiguration.json

"bdd": {
    "vrunnerSteps": [
      "vanessa --settings ./tools/vrunner.json"
    ],
    "coverage": true,
    "dbgsPort": 1550
  },

./tools/vrunner.json

  "vanessa": {
    "--vanessasettings": "tools/VAParams.json",
  }

./tools/VAParams.json

"КлиентТестирования": {
  "ЗапускатьТестКлиентВРежимеОтладки": true,
  "КлючиОтладки": "-http",
  "АдресОтладчика": "http://127.0.0.1:1550",

Для yaxunit:

./tools/vrunner.json

"default": {
  "--additional": "/debug -http -attach /debuggerURL http://localhost:1550"
}

Для smoke (после исправления ошибки в vanessa-add):

./tools/vrunner.json

"xunit": {
  "--testclient-additional": "/debug -http -attach /debuggerURL http://localhost:1550"
}

• При изменении портов отладки в jobConfiguration.json не забывайте менять порты в настройках соответствующих шагов (и наоборот)
• Настоятельно рекомендуется использовать не "постоянные" агенты Jenkins, а контейнеры docker. При выполнении билдов в контейнерах можно использовать исключительно стандартный порт 1550.

Сохранение ИБ в виде артефакта сборки

Параметры initInfobase -> archiveInfobase и bdd -> archiveInfobase отвечают за сохранение информационной базы в виде артефакта сборки после выполнения соответствующих этапов. Можно управлять тем, при каких статусах сборки ИБ будет сохранена, см. onAlways, onFailure, onUnstable, onSuccess.

Имя файла формируется следующим образом:

• для шага initInfoBase: '1Cv8.1CD.zip'
• для шага bdd: '1Cv8.1CD.bdd.zip'