Skip to content

enb/enb-bem-tmpl-specs

Repository files navigation

enb-bem-tmpl-specs

NPM version Build Status Dependency Status

Инструмент для сборки и запуска тестов на шаблоны. В процессе сборки генерируются сеты из бандлов с тестами на шаблоны БЭМ-блоков с помощью ENB.

Установка

$ npm install --save-dev enb-bem-tmpl-specs

Для работы модуля требуется зависимость от пакетов enb-magic-factory версии 0.3.x или выше, а также enb версии 0.15.0 или выше.

Как создать тест?

Чтобы добавить тест для БЭМ-сущности, нужно в её директории на требуемом уровне переопределения создать каталог с названием bem-name.tmpl-specs для хранения файлов тестов.

Каждый тест состоит из пары файлов «пример» и «эталон», где каждый файл создаётся в своей технологии, например BEMJSON и HTML. Таких пар файлов у блока может быть несколько. Имена файлов произвольные, но они (не включая расширения) для каждого теста должны совпадать. Например, 10-default.bemjson.js и 10-default.html.

$ tree -a <level>.blocks/<block-name>/<block-name>.tmpl-specs

<block-name>/
 └── <block-name>.tmpl-specs/
      ├── 10-default.bemjson.js  # Эталонный BEMJSON-код сравниваемый с результатом#  обработки BEMTREE, а также пример для BEMHTML
      ├── 10-default.data.js     # Пример в технологии BEMJSON для обработки BEMTREE #  шаблонизатором
      ├── 10-default.html        # Эталонный HTML-код сравниваемый с результатом #  обработки BEMHTML
      ├── 20-advanced.bemjson.js
      └── 20-advanced.html

Результат сборки

В результате будет построен уровень-сет из примеров, каждый из которых представляет собой обычный бандл (nested-уровень):

$ tree -a <set-name>.tmpl-specs

<set-name>.tmpl-specs/
 └── <block-name>/
      ├── <block-name>.references.js  # Набор из пар эталонов (data + bemjson для BEMTREE#  и bemjson + html для BEMHTML).
      ├── <block-name>.bemhtml.js     # Код BEMHTML-шаблонов, необходимый для#  выполнения эталонов из `references.js`.
      ├── <block-name>.bemtree.js     # Код BEMTREE-шаблонов, необходимый для#  выполнения эталонов из `references.js`.
      ├── <block-name>.bh.js          # Код BH-шаблонов, необходимый для#  выполнения эталонов из `references.js`.
      └── <block-name>.tmpl-spec.js   # Код тестов в BDD-стиле.

Поддержка шаблонизаторов

  • BEMHTML на основе XJST. Базовые шаблоны находятся в bem-bl.
  • BEMHTML на основе BEM-XJST. Базовые шаблоны находятся в bem-core.
  • BH.
  • BEMTREE на основе BEM-XJST.

Запуск тестов

После сборки уровней-сетов произойдёт запуск тестов на шаблоны для указанных БЭМ-сущностей.

Собранные tmpl-spec.js-файлы для каждой БЭМ-сущности подключают необходимые для выполнения шаблоны и наборы эталонов, а так же содержат код тестов в BDD-стиле. Эти файлы подаются на вход для mocha.

2014-09-22 12 50 05

Вывод ошибок

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

2014-09-22 13 01 29

Для вывода различий используется:

Формат вывода ошибок

По умолчанию используется консольный отчет - spec. Другие форматы можно использовать, перечислив их в переменной окружения:

BEM_TMPL_SPECS_REPORTERS=html,summary,spec

Сохранение результатов

Для сохранения результатов отрисовки HTML вы можете либо выставить явно флаг saveHtml при конфигурации технологии, либо через переменную окружения — BEM_TMPL_SPECS_SAVE_HTML=1.

Файл будет сохранён в <set-name>.tmpl-specs/<block-name>/*.html, рядом со сгенерированными файлами тестов.

Создание эталонов

Для создания/обновления HTML эталонов вы можете либо выставить явно флаг saveReferenceHtml при конфигурации технологии, либо через переменную окружения — BEM_TMPL_SPECS_SAVE_REFERENCE_HTML=1

Файл будет сохранён в <level>.blocks/<block-name>/<block-name>.tmpl-specs/*.{html,js}, рядом с исходным кодом блока.

Или можно использовать флаг autoAddReference для автоматической генерации недостающего эталона если таковой не найден, при условии что существует входной пример.

Фильтрация тестов

Чтобы запустить только нужные тесты можно указать в grep регулярное выражение или строку, фильтрующее тесты по названию, либо передать его через переменную окружения:

BEM_TMPL_SPECS_GREP='10-'
BEM_TMPL_SPECS_GREP='/specs.+rocks/i'

Доступные форматы отчетов

Все генерируемые в файл отчеты сохранятся в директорию - tmpl-specs-reports/

  • summary - Генерирует отчет в JSON формате и сохраняет его в файл (summary.json).
{
     "suites": 4,
     "tests": 16,
     "passes": 10,
     "pending": 0,
     "failures": 6,
     "start": "2014-10-14T12:02:10.800Z",
     "end": "2014-10-14T12:02:11.207Z",
     "duration": 407,
     "skipped": 0
}
  • html - Генерирует отчет в HTML формате и сохраняет его в файл (report.html).

Как использовать?

В make-файле (.enb/make.js) нужно подключить модуль enb-bem-tmpl-specs. С помощью этого модуля следует создать конфигуратор, указав название таска, в рамках которого будет происходить сборка уровней сетов из тестов на шаблоны.

Конфигуратор имеет единственный метод configure. Его можно вызывать несколько раз, чтобы задекларировать сборку нескольких уровней-сетов.

module.exports = function (config) {
    config.includeConfig('enb-bem-tmpl-specs'); // Подключаем `enb-bem-tmpl-specs` модуль.

    var examples = config.module('enb-bem-tmpl-specs') // Создаём конфигуратор сетов
        .createConfigurator('tmpl-specs', {            // в рамках таска `specs`.
            coverage: {                                // Определяем общие опции для всех уровней-сетов.
                engines: ['bh'],
                reportDirectory: 'coverage',
                exclude: ['**/node_modules/**', '**/libs/**'],
                reporters: ['lcov']
            }
        });

    examples.configure({
        destPath: 'desktop.tmpl-specs',
        levels: ['blocks'],
        langs: ['ru','en'],
        sourceLevels: [
            { path: '../libs/bem-core/common.blocks', check: false },
            { path: 'blocks', check: true }
        ],
        engines: {
            bh: {
                tech: 'enb-bh/techs/bh-server',
                options: {
                    jsAttrName: 'data-bem',
                    jsAttrScheme: 'json'
                }
            },
            'bemhtml-dev': {
                tech: 'enb-bemxjst/techs/bemhtml-old',
                options: {
                    exportName: 'BEMHTML',
                    devMode: true
                }
            },
            'bemhtml-prod': {
                tech: 'enb-bemxjst/techs/bemhtml-old',
                options: {
                    exportName: 'BEMHTML',
                    devMode: false
                }
            },
            bemtree: {
                tech: 'enb-bemxjst/techs/bemtree',
                options: {
                    sourceSuffixes: ['bemtree', 'bemtree.js'],
                    exportName: 'BEMTREE',
                }
            }
        }
    });
};

Опции для всех уровней-сетов

  • Object coverage – собирать информацию о покрытии кода тестами.
    • String[] engines – список шаблонизаторов, которые необходимо учитывать при формировании отчета;
    • String reportDirectory – название папки, в которой необходимо создать отчет. По умолчанию – coverage;
    • String[] exclude – маски путей, которые необходимо исключить при формировании отчета. По умолчанию — ['**/node_modules/**', '**/libs/**'];
    • String[] reporters – форматы отчетов (env: BEM_TMPL_SPECS_COV_REPORTERS, названия форматов отчётов передаются через запятую), см. istanbul#report. По умолчанию – ['lcov'].
  • Object htmlDiffer — настройки сравнения HTML при помощи html-differ. По умолчанию — { preset: 'bem' }.
  • Number timeout — время ожидания тест-кейса в миллисекундах (env: BEM_TMPL_SPECS_TIMEOUT).
  • String|RegExp grep — фильтр тестов по названию (env: BEM_TMPL_SPECS_GREP), см. mocha#grep.

Опции для определенного уровня-сета

  • String destPath — путь относительно корня до нового уровня-сета с тестами на шаблоны, которые нужно собрать. Обязательная опция.
  • String[] | Object[] levels — уровни, в которых следует искать эталоны. Обязательная опция.
  • String[] | Object[] sourceLevels — уровни, в которых следует искать код шаблонов, необходимый для шаблонизации эталонных BEMJSON-файлов.
  • String[] referenceDirSuffixes — суффиксы папок технологий с эталонами. По умолчанию — ['tmpl-specs'].
  • String[] | Boolean langs —  использование BEM.I18N в шаблонах. Если указать массив языков, то необходимо будет создавать эталоны на каждый из перечисленных языков. Например 10-name.ru.bemjson.js , 10-name.en.bemjson.js. Если использовать значение langs: true, то эталоны по языкам писать не нужно. В код собранных шаблонов будет всталенно только ядро BEM.I18N, без кейсетов. По умолчанию — false.
  • String[] prependFiles — опция позволяет указать набор файлов для подмешивания в начало тестируемых шаблонов.
  • String[] appendFiles — опция позволяет указать набор файлов для подмешивания в конец тестируемых шаблонов.
  • Object engines —  опция определяет какие ENB-технологии следует использовать для сборки шаблонов. Обязательная опция.
    • String tech — путь к ENB-технологии;
    • Object options — опции для ENB-технологии;
    • Boolean async — асинхронный шаблонизатор;
  • String completeBundle – имя бандла, в котором будут собраны все БЭМ-сущности из уровней levels. По умолчанию completeBundle не будет собран.
  • Boolean saveHtml — сохранять результат HTML при успешной отрисовке в файл (env: BEM_TMPL_SPECS_SAVE_HTML);
  • Boolean saveReferenceHtml — создать/обновить эталон HTML рядом с BEMJSON (env: BEM_TMPL_SPECS_SAVE_REFERENCE_HTML);
  • Boolean autoAddReference — автоматически создавать недостающие эталоны, при условии что существуют входные примеры;
  • String|Function depsTech — технология для раскрытия зависимостей. По умолчанию — deps-old.
  • Function mockI18N — функция будет использована вместо ядра i18n, если указана опция langs: true.
  • String stringifyIndent — предпочтительный отступ для подсветки различий JSON объектов. По умолчанию два пробела.

Запуск из консоли

В make-файле декларируется таск, в котором будет выполняться сборка уровней-сетов из тестов на шаблоны.

В ENB запуск таска осуществляется с помощью команды make, которой передаётся имя таска:

$ ./node_modules/.bin/enb make <task-name>

Сборка и запуск всех тестов на шаблоны

Если сборка уровней-сетов из тестов была задекларирована в таске tmpl-specs:

$ ./node_modules/.bin/enb make tmpl-specs

Сборка всех тестов на шаблоны для указанной БЭМ-сущности

Чтобы собрать тесты БЭМ-сущности block__elem для уровня-сета desktop.tmpl-specs:

$ ./node_modules/.bin/enb make tmpl-specs desktop.tmpl-specs/block__elem

Лицензия

© 2014 YANDEX LLC. Код лицензирован Mozilla Public License 2.0.