Skip to content

Latest commit

 

History

History
390 lines (275 loc) · 20.7 KB

html-reporter-setup.md

File metadata and controls

390 lines (275 loc) · 20.7 KB
Raw

Подключение плагина

Обзор

Используйте плагин html-reporter, чтобы получить html-отчет о прогоне тестов.

⚠️ Для корректной работы плагина html-reporter требуется hermione версии 4 и выше.

Плагин сохраняет результаты прогона тестов в базу данных SQLite. Поэтому вы не сможете открыть локальный отчет как файл с помощью file:// протокола.

Чтобы посмотреть отчет, запустите гермиону в GUI-режиме:

npx hermione gui

Или запустите http-server в папке с отчетом:

npx http-server -p 8000

Если вы запускаете локальный сервер не из папки с отчетом, то укажите путь к отчету:

npx http-server ./hermione-report -p 8000

После чего откройте страницу http://localhost:8000 в браузере.

Установка

npm install -D html-reporter

Настройка

Необходимо подключить плагин в разделе plugins конфига hermione:

Минимальный конфиг

module.exports = {
    plugins: {
        'html-reporter/hermione': {
            enabled: true
        },

        // другие плагины гермионы...
    },

    // другие настройки гермионы...
};

Максимальный конфиг

module.exports = {
    plugins: {
        'html-reporter/hermione': {
            enabled: true,
            path: 'my/hermione-reports',
            defaultView: 'all',
            baseHost: 'test.com',
            errorPatterns: [
                'Parameter .* must be a string',
                {
                    name: 'Cannot read property of undefined',
                    pattern: 'Cannot read property .* of undefined',
                    hint: '<div>google it, i dont know how to fix it =(</div>'
                }
            ],
            customScripts: [
                function() {
                    // кастомный скрипт
                },

                // другие скрипты...
            ],
            customGui: {
                // DEPRECATED (этот параметр устарел)
                // дополнительные элементы управления для GUI-режима
                // используйте plugins (плагины для отчета) вместо customGui
            },
            pluginsEnabled: true,
            plugins: [
                // плагины для отчета...
            ],
            yandexMetrika: {
                counter: 1234567
            }
        },

        // другие плагины гермионы...
    },

    // другие настройки гермионы...
}

Расшифровка параметров конфигурации

Параметр Тип По умолчанию Описание
enabled Boolean true Включить / отключить плагин.
path String "html-report" Путь к папке для сохранения файлов html-отчета.
saveErrorDetails Boolean false Сохранять / не сохранять подробности ошибок в json-файлах.
defaultView String "all" Режим фильтрации тестов при отображении, который будет установлен по умолчанию.
diffMode String "3-up" Режим просмотра диффов, который будет установлен по умолчанию.
baseHost String N/A Заменяет оригинальный адрес хоста для просмотра в браузере.
errorPatterns Object[] или String[] [ ] Паттерны ошибок с подсказками для улучшения UX отчета.
metaInfoBaseUrls Object { } Базовые URL-адреса для формирования ссылок в разделе Meta на основе мета-информации о прогоне теста.
saveFormat String "sqlite" ПАРАМЕТР УСТАРЕЛ. Позволяет задать формат, в котором будут сохранены результаты прогона тестов.
customGui Object { } ПАРАМЕТР УСТАРЕЛ. Используйте вместо него plugins. Описание собственных элементов управления для GUI-режима.
pluginsEnabled Boolean false Включить плагины для отчета.
plugins Object[] [ ] Список плагинов с их настройками.
customScripts Function[] [ ] Список функций, реализующих кастомные скрипты. Например, скрипты Яндекс.Метрики или Жучка.
yandexMetrika Object { } Яндекс.Метрика.

enabled

Включает или отключает плагин.

path

Путь к папке для сохранения файлов html-отчета. По умолчанию файлы будут сохранены в папку html-report в текущей рабочей папке.

saveErrorDetails

Сохранять или не сохранять подробности ошибок в json-файлах (в папку error-details).

По умолчанию «не сохранять»: false.

Любой плагин гермионы может добавить какие-либо подробности в объект ошибки при её возникновении. Эти подробности могут помочь пользователю в отладке проблем, которые возникли в тесте. Html-reporter сохраняет эти детали в папке error-details в файле с именем: <хэш от полного названия теста>-<браузер>_<номер ретрая>_<временная метка>.json.

Под стектрейсом html-reporter добавляет раздел Error details со ссылкой <title>, указывающей на json-файл. Пользователь может открыть этот файл либо в браузере, либо в любой IDE.

Пример как добавить подробности в объект ошибки из плагина:

const err = new Error('some error');

err.details = {
    title: 'description, will be used as url title',
    data: {} // или [], или String
};

throw err;

defaultView

Режим фильтрации тестов при отображении, который будет установлен по умолчанию. Доступны следующие значения:

Режим Описание
all все тесты
passed только успешные тесты
failed только упавшие тесты
retried только те тесты, в которых были ретраи (повторные запуски)
skipped только отключенные (заскипанные) тесты

По умолчанию: all, то есть если параметр не задан, то будут показываться все тесты.

diffMode

Режим просмотра диффов, который будет установлен по умолчанию. Доступны следующие значения:

Режим Описание
3-up все изображения (expected, actual, diff) в одном столбце, друг под другом
3‑up‑scaled все изображения (expected, actual, diff) в один ряд так, чтобы они помещались на экране
only-diff только дифф (diff)
switch эталонное изображение с возможностью переключаться на актуальное изображение по клику мыши
swipe актуальное изображение поверх эталонного, с разделителем открывающим эталонное изображение
onion-skin актуальное изображение поверх эталонного с возможностью менять прозрачность актуального изображения

По умолчанию: 3-up.

baseHost

Заменяет оригинальный адрес хоста для просмотра в браузере. По умолчанию оригинальный адрес хоста не изменяется.

errorPatterns

Паттерны ошибок используются:

  • чтобы показать более понятную информацию об ошибках, если они соответствуют паттернам, для которых есть подробное описание;
  • в режиме отображения Group by с выбранным ключом error.

Паттерны ошибок можно задавать как в виде объектов, так и в виде строк.

Чтобы задать паттерн ошибки в виде объекта, используйте следующий формат:

{
    name: '<название ошибки>',
    pattern: '<паттерн ошибки>',
    hint: '<подсказка пользователю>'
}

где:

Параметр Тип Описание
name String Название ошибки.
pattern String или RegExp Регулярное выражение или обычная строка, которой должна соответствовать ошибка.
hint String Необязательный параметр. Подсказка, что можно сделать с данной ошибкой: почему она возникла, как её исправить и т. п.

Если паттерн ошибки задан в виде строки, например: <ошибка>, то эта строка автоматически рассматривается как объект вида:

{
    name: '<ошибка>',
    pattern: '<ошибка>'
}

Такой способ задания паттерна удобен для тех ошибок, у которых name и pattern полностью совпадают.

Когда один из шаблонов ошибок совпадает с сообщением об ошибке, то:

  • name шаблона ошибки будет отображаться как заголовок сообщения об ошибке, а исходное сообщение об ошибке будет скрыто под катом;
  • hint для ошибки будет отображаться после поля ошибки stack. Подсказка может быть задана в виде html-строки. Например, <div>some-useful-hint</div>.

В режиме Group by (группировать по) с выбранным ключом error тест будет связан с группой, если ошибка теста совпадает с шаблоном ошибок группы. Если тест не может быть связан с существующими группами, то будет создана новая группа.

metaInfoBaseUrls

Базовые URL-адреса для формирования ссылок в разделе Meta на основе мета-информации о прогоне теста.

Параметр задается в виде объекта:

{
    '<опция-1>': 'значение опции 1',
    '<опция-2>': 'значение опции 2',
    // и т. д.
}

Например:

{
    'file': 'base/path'
}

Когда значение любого ключа установлено на auto, базовый URL будет установлен на базовый хост, указанный в интерфейсе отчета, или останется неизменным, если базовый хост не указан.

Например, если у вас есть следующее значение metaInfoBaseUrls:

{ custom_url: 'auto' }

И вы установите поле meta.custom_url в https://example.com/some/path в ваших тестах, вы увидите в мете:

  • Ссылку на https://example.com/some/path, если базовый хост не установлен в интерфейсе пользователя
  • Ссылку на https://another-host.com/some/path, если базовый хост в интерфейсе пользователя установлен в https://another-host.com

saveFormat

Параметр устарел

Позволяет задать формат, в котором будут сохранены результаты прогона тестов.

Доступным осталось только одно значение, которое используется по умолчанию:

  • sqlite — сохранить результаты прогона тестов в базе данных формата SQLite.

customGui

Параметр устарел

⚠️ Вместо customGui рекомендуется использовать плагины для отчета.

Описание собственных элементов управления для GUI-режима.

Смотрите подробнее в разделе «Кастомизация GUI».

pluginsEnabled

Включить плагины для html-reporter.

plugins

Список плагинов с их настройками.

Смотрите подробнее в разделе «Плагины для отчета».

customScripts

Список кастомных скриптов в виде массива функций. С помощью этого параметра можно добавить любой скрипт на страницу html-отчета. Например, для сбора каких-либо метрик или реализации дополнительной функциональности. Скрипты будут выполнены сразу после рендеринга страницы.

Пример:

customScripts: [
    function() {
        console.info('some logs');
    },
    () => {
        const div = document.createElement('div');
        div.innerHTML = 'hello';
        document.body.prepend(div);
    }
]

yandexMetrika

Данный параметр позволяет добавить в отчет Яндекс.Метрику. Параметр задается в виде объекта с ключом counterNumber (номер счетчика). В качестве значения ключа необходимо указать номер счетчика Яндекс.Метрики (см. «Как создать счетчик»). Номер должен задаваться как число (Number), а не строка.

Также в интерфейсе Яндекс.Метрики необходимо перейти в разделе настроек на вкладку «Счетчик», нажать кнопку «Скопировать» и вставить код счетчика в поле customScripts.

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

Отчет поддерживает следующие цели для метрики:

  • ACCEPT_SCREENSHOT — было нажатие на кнопку Accept для принятия скриншота;
  • ACCEPT_OPENED_SCREENSHOTS — было нажатие на кнопку Accept opened для принятия скриншотов из открытых тестов.

Пример настройки Яндекс.Метрики в одном из проектов:

module.exports = {
    plugins: {
        'html-reporter/hermione': {
            customScripts: [
                function(){(function(m,e,t,r,i,k,a){m[i]=m[i]||function(){(m[i].a=m[i].a||[]).push(arguments)}; m[i].l=1*new Date();k=e.createElement(t),a=e.getElementsByTagName(t)[0],k.async=1,k.src=r,a.parentNode.insertBefore(k,a)}) (window, document, "script", "https://mc.yandex.ru/metrika/tag.js", "ym"); ym(56782912, "init", { clickmap:true, trackLinks:true, accurateTrackBounce:true, webvisor:true })},

                // другие скрипты...
            ],
            yandexMetrika: {
                counterNumber: 1234567
            },

            // другие настройки плагина...
        },

        // другие плагины гермионы...
    },

    // другие настройки гермионы...
};

Передача параметров через CLI

Все параметры плагина, которые можно определить в конфиге, можно также передать в виде опций командной строки или через переменные окружения во время запуска гермионы. Используйте префикс --html-reporter- для опций командной строки и html_reporter_ — для переменных окружения.

Например, параметр настроек path можно передать следующими способами:

hermione path/to/mytest.js --html-reporter-path custom/dir
html_reporter_path=custom/dir hermione path/to/mytest.js

Хранение данных

Как уже было сказано выше, html-reporter сохраняет результаты прогона тестов в базу данных SQLite.

Почему мы используем SQLite? Потому что он:

  • бессерверный, легко подключаемый и не требует настроек
  • кросс-платформенный, запускается на любой операционной системе
  • одно-файловый, легко переиспользовать отчеты и делиться ими
  • быстрее, чем если хранить отчет на файловой системе
  • компактный и имеет полноценный SQL.

Файлы, который создаются во время выполнения тестов:

  • sqlite.db — база данных Sqlite с результатами прогона тестов
  • data.js — конфиг отчета
  • databaseUrls.json — абсолютные или относительные URL-адреса на базы данных SQLite (sqlite.db) и/или URL-адреса других файлов databaseUrls.json (см. команду merge-reports)