Jenkins shared library for 1C:Enterprise 8

Цель

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

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

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

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

Ограничения

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

Возможности

Все шаги можно запустить на базе docker-образов из https://github.com/firstBitMarksistskaya/onec-docker. См. памятку по слоям и последовательности сборки.
Поддержка как формата выгрузки из Конфигуратора, так и формата EDT.
Подготовка информационной базы по версии из хранилища конфигурации, из исходных файлов конфигурации, комбинированный режим (основная ветка - из хранилища, остальные - из исходников).
Подготовка и загрузка расширений конфигурации из исходных файлов расширения, из cfe-файлов.
Запуск ИБ в режиме выполнения обработчиков обновления БСП.
Дополнительные шаги инициализации данных в ИБ.
Трансформация кода из формата конфигуратора в формат EDT.
Трансформация кода из формата EDT в формат конфигуратора.
Запуск BDD сценариев с сохранением результатов в формате Allure.
Запуск юнит-тестов с помощью фреймворка YAXUnit с сохранением результатов в формате jUnit и Allure.
Запуск синтаксического контроля средствами конфигуратора и сохранение результатов в виде отчета jUnit.
Валидация проекта средствами EDT и трансформация отчета EDT в формат BSL LS с помощью edt-ripper или Generic Issue с помощью stebi.
Запуск статического анализа для SonarQube.
Публикация результатов junit и Allure в интерфейс Jenkins.
Рассылка результатов сборки на почту и в Telegram.
Конфигурирование логгера запускаемых oscript-приложений.
Замер покрытия при выполнении тестов.

Подключение

Инструкция по подключению библиотеки: 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.
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).

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

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

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

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

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

Укажите этапы сборки, на которых должно быть загружено расширение (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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Jenkins shared library for 1C:Enterprise 8

Цель

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

Ограничения

Возможности

Подключение

Примеры Jenkinsfile

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

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

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

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

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

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

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

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

Files

README.md

Latest commit

History

README.md

File metadata and controls

Jenkins shared library for 1C:Enterprise 8

Цель

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

Ограничения

Возможности

Подключение

Примеры Jenkinsfile

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

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

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

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

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

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

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

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