Allure notifications

Allure notifications - это библиотека, позволяющая выполнять автоматическое оповещение о результатах прохождения автотестов, которое направляется в нужный вам мессенджер (Telegram, Slack, Skype, Email, Mattermost, Discord, Loop, Rocket.Chat).

Languages: 🇬🇧 🇫🇷 🇷🇺 🇺🇦 🇧🇾 🇨🇳

Содержание

• Принцип работы
• Как выглядят оповещения
• Как использовать в своем проекте:
  • для запуска локально
  • для запуска из Jenkins
• Особенности заполнения файла config.json в зависимости от выбранного мессенджера

Принцип работы

По итогам выполнения автотестов генерируется файл summary.json в папке allure-report/widgets. Этот файл содержит общую статистику о результатах прохождения тестов, на основании которой как раз и формируется уведомление, которое отправляет бот (отрисовывается диаграмма и добавляется соответствующий текст).

Пример файла summary.json

{
  "reportName" : "Allure Report",
  "testRuns" : [ ],
  "statistic" : {
    "failed" : 182,
    "broken" : 70,
    "skipped" : 118,
    "passed" : 439,
    "unknown" : 42,
    "total" : 851
  },
  "time" : {
    "start" : 1590795193703,
    "stop" : 1590932641296,
    "duration" : 11311,
    "minDuration" : 7901,
    "maxDuration" : 109870,
    "sumDuration" : 150125
  }
}

Кроме этого, если подключен Allure Summary плагин также будет сгенерирован файл suites.json данные из которого также будут включены в статистику.

Как выглядят оповещения

Пример оповещения в Telegram

Как использовать в своем проекте

Для запуска локально

1. Для локальной отладки нужно установить java (для запуска в Jenkins она не понадобится)
2. Создать в корне проекта папку notifications.
3. Скачать актуальную версию файла allure-notifications-version.jar, и разместить его в папке notifications в своем проекте.
4. В папке notifications создать файл config.json со следующей структурой (оставить раздел base и тот мессенджер, на который требуется отправлять оповещения):

{
  "base": {
    "logo": "",
    "project": "",
    "environment": "",
    "comment": "",
    "reportLink": "",
    "language": "ru",
    "allureFolder": "",
    "enableChart": false,
    "enableSuitesPublishing": false,
    "customData": {}
  },
  "telegram": {
    "token": "",
    "chat": "",
    "replyTo": "",
    "templatePath": "/templates/telegram.ftl"
  },
  "slack": {
    "token": "",
    "chat": "",
    "replyTo": "",
    "templatePath": "/templates/markdown.ftl"
  },
  "mattermost": {
    "url": "",
    "token": "",
    "chat": "",
    "templatePath": "/templates/markdown.ftl"
  },
  "rocketChat" : {
    "url": "",
    "auth_token": "",
    "user_id": "",
    "channel": "",
    "templatePath": "/templates/rocket.ftl"
   },
  "skype": {
    "appId": "",
    "appSecret": "",
    "serviceUrl": "",
    "conversationId": "",
    "botId": "",
    "botName": "",
    "templatePath": "/templates/markdown.ftl"
  },
  "mail": {
    "host": "",
    "port": "",
    "username": "",
    "password": "",
    "securityProtocol": null,
    "from": "",
    "to": "",
    "cc": "",
    "bcc": "",
    "templatePath": "/templates/html.ftl"
  },
  "discord": {
    "botToken": "",
    "channelId": "",
    "templatePath": "/templates/markdown.ftl"
  },
  "loop": {
    "webhookUrl": "",
    "templatePath": "/templates/markdown.ftl"
  },
  "proxy": {
    "host": "",
    "port": 0,
    "username": "",
    "password": ""
  }
}

Блок proxy используется если нужно указать дополнительную конфигурацию proxy.
Параметр templatePath является опциональным и позволяет установить путь к собственному Freemarker шаблону для сообщения. Пример:

{
  "base": {
    ...
  },
  "mail": {
    "host": "smtp.gmail.com",
    "port": "465",
    "username": "username",
    "password": "password",
    "securityProtocol": "SSL",
    "from": "test@gmail.com",
    "to": "test1@gmail.com",
    "cc": "testCC1@gmail.com, testCC2@gmail.com",
    "bcc": "testBCC1@gmail.com, testBCC2@gmail.com",
    "templatePath": "/templates/html_custom.ftl"
  }
}

5. Заполнить в файле config.json блок base:

Пример заполнения блока base:

"base": {
    "project": "some project",
    "environment": "some env",
    "comment": "some comment",
    "reportLink": "",
    "language": "en",
    "allureFolder": "build/allure-report/",
    "enableChart": true,
    "enableSuitesPublishing": true,
    "logo": "logo.png",
    "durationFormat": "HH:mm:ss.SSS",
    "customData": {
      "variable1": "value1",
      "variable2": "value2"
    }
}

Порядок заполнения:

• project, environment, comment - имя проекта, название окружения и произвольный комментарий.
• reportLink - ссылка на Allure report с результатами прохождения автотестов (целесообразно заполнять при запуске автотестов из Jenkins - об этом ниже).
• language - язык, на котором будет сформирован текст для оповещения (варианты: en / fr / ru / ua / by / cn).
• allureFolder - путь к папке с результатами работы Allure.
• enableChart - требуется ли отображать диаграмму (варианты: true / false).
• enableSuitesPublishing - требуется ли публиковать отдельно статистику каждого тестового набора (варианты: true / false, по-умолчанию false). Перед включением данной опции убедитесь, что папка <allureFolder>/widgets содержит JSON файл suites.json
• logo - путь к файлу с логотипом (если заполнено, то в левом верхнем углу диаграммы будет отображаться соответствующий логотип).
• durationFormat (optional, default value is HH:mm:ss.SSS) - specifies the desired output format for tests duration.
• customData - дополнительные данные, которые могут быть переиспользованы в собственных Freemarker шаблонах (опциональное поле).

6. Заполнить в файле config.json блок с информацией о выбранном мессенджере: особенности заполнения файла config.json в зависимости от выбранного мессенджера

7. Выполнить в терминале следующую команду:

java "-DconfigFile=notifications/config.json" -jar notifications/allure-notifications-4.2.1.jar

Примечание:

• на момент запуска уже должен быть сформирован файл summary.json
• в тексте команды нужно указать ту версию файла jar, которую вы скачали на предыдущих шагах

В результате будет сформировано оповещение с результатами прохождения автотестов и направлено в выбранный мессенджер.

Для запуска из Jenkins

1. Перейти в настройки сборки в Jenkins
2. В разделе Сборка нажать кнопку Добавить шаг собрки, в появившемся меню выбрать Create/Update Text File

Заполнить следующим образом:

Примечание:

• Общая информация о заполнении блока base описана в этом разделе
• В следующих параметрах в качестве значений указываем переменные: "project": "${JOB_BASE_NAME}" и "reportLink": "${BUILD_URL}". При формировании уведомления в данных полях будут указаны название JOB и ссылка на BUILD в Jenkins.
• Особенности заполнения файла config.json в зависимости от выбранного мессенджера описаны в этом разделе

3. В разделе Послесборочные операции нажать кнопку Добавить шаг после собрки, в появившемся меню выбрать Post build task

• В поле Script указываем следующее:

cd ..
FILE=allure-notifications-4.2.1.jar
if [ ! -f "$FILE" ]; then
   wget https://github.com/qa-guru/allure-notifications/releases/download/4.2.1/allure-notifications-4.2.1.jar
fi

Примечание: В этом скрипте мы переходим на папку выше, если там нет jar файла, то скачиваем его. Необходимо указать актуальную версию файла jar

• Нажимаем Add another task и во втором поле Script указываем следующее:

java "-DconfigFile=notifications/config.json" -jar ../allure-notifications-4.2.1.jar

4. Сохраняем изменения настроек и запускаем автотесты. По завершении в мессенджер будет направлено уведомление о результатах.

Особенности заполнения файла config.json в зависимости от выбранного мессенджера

• Telegram config
• Slack config
• Email config
• Skype config
• Mattermost config
• Discord config

  To enable Discord notifications it's required to provide 2 configuration parameters: botToken and channelId.

  • To create your own Discord bot and get its token follow these steps.
    1. Turn on “Developer mode” in your Discord account.
    2. Click on “Discord API”.
    3. In the Developer portal, click on “Applications”. Log in again and then, back in the “Applications” menu, click on “New Application”.
    4. Name the bot and then click “Create”.
    5. Go to the “Bot” menu and generate a token using “Add Bot”.
    6. Copy the bot’s token and paste it into the JSON config
    7. Define other details for your bot under “General Information”.
    8. Click on “OAuth2”, activate “bot”, set the permissions, and then click on “Copy”.
    9. Select your server to add your bot to it.
  • To get a Channel ID right click the channel and click on "Copy ID" then paste it into the JSON config. Alternatively type the channel as a mention and place a backslash \ in front of the mention.
• Loop config

  To create your own Loop webhook URL follow these steps.

  • Go to main menu of Loop application.
  • Click "Integrations".
  • Choose "Incoming Webhooks".
  • Click "Add Incoming Webhook".
  • Fill out the form fields on your choice, make sure to select a channel for messages.
  • Click "Save".
  • Copy URL of webhook.
• Rocket.Chat config

  To enable Rocket.Chat notifications it's required to provide 4 configuration parameters: url, auth_token,user_id,channel

  • 1. First of all you need to generate auth_token from user setting.
    2. After generation you can get auth_token and user_id.
    3. You can get the channel parameter using previously generated tokens and following the documentation.