enb-bem-tmpl-specs
Инструмент для сборки и запуска тестов на шаблоны. В процессе сборки генерируются сеты из бандлов с тестами на шаблоны БЭМ-блоков с помощью 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.
В BEMJSON-файле находится пример для БЭМ-сущности, в HTML – эталонный HTML-код, который должен получиться после выполнения шаблонов с данным BEMJSON.
$ tree -a <level>.blocks/<block-name>/<block-name>.tmpl-specs <block-name>/ └── <block-name>.tmpl-specs/ ├── 10-default.bemjson.js ├── 10-default.html ├── 20-advanced.bemjson.js └── 20-advanced.html
Результат сборки
В результате будет построен уровень-сет из примеров, каждый из которых представляет собой обычный бандл (nested
-уровень):
$ tree -a <set-name>.tmpl-specs <set-name>.tmpl-specs/ └── <block-name>/ ├── <block-name>.references.js # Набор из пар эталонов (BEMJSON + HTML). ├── <block-name>.bemhtml.js # Код BEMHTML-шаблонов, необходимый для # выполнения эталонов из `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.
Запуск тестов
После сборки уровней-сетов произойдёт запуск тестов на шаблоны для указанных БЭМ-сущностей.
Собранные tmpl-spec.js
-файлы для каждой БЭМ-сущности подключают необходимые для выполнения шаблоны и наборы эталонов, а так же содержат код тестов в BDD-стиле. Эти файлы подаются на вход для mocha.
Вывод ошибок
Если результат применения шаблона не совпадает с эталонным HTML, то в логе будет ошибка с указанием отличий от эталона.
Для вывода различий используется html-differ.
Формат вывода ошибок
По умолчанию используется консольный отчет - 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
, рядом с исходным кодом блока.
Фильтрация тестов
Чтобы запустить только нужные тесты можно указать в grep
регулярное выражение или строку, фильтрующее тесты по названию,
либо передать его через переменную окружения:
BEM_TMPL_SPECS_GREP='10-'BEM_TMPL_SPECS_GREP='/specs.+rocks/i'
Доступные форматы отчетов
Все генерируемые в файл отчеты сохранятся в директорию - tmpl-specs-reports/
summary
- Генерирует отчет вJSON
формате и сохраняет его в файл (summary.json
).
html
- Генерирует отчет вHTML
формате и сохраняет его в файл (report.html
).
Как использовать?
В make
-файле (.enb/make.js
) нужно подключить модуль enb-bem-tmpl-specs
.
С помощью этого модуля следует создать конфигуратор, указав название таска, в рамках которого будет происходить сборка уровней сетов из тестов на шаблоны.
Конфигуратор имеет единственный метод configure
. Его можно вызывать несколько раз, чтобы задекларировать сборку нескольких уровней-сетов.
module { config; // Подключаем `enb-bem-tmpl-specs` модуль. var examples = config // Создаём конфигуратор сетов ; examples;};
Опции для всех уровней-сетов
- Object
coverage
– собирать информацию о покрытии кода тестами.- String[]
engines
– список шаблонизаторов, которые необходимо учитывать при формировании отчета; - String
reportDirectory
– название папки, в которой необходимо создать отчет. По умолчанию –coverage
; - String[]
exclude
– маски путей, которые необходимо исключить при формировании отчета. По умолчанию —['**/node_modules/**', '**/libs/**']
; - String[]
reporters
– форматы отчетов (env:BEM_TMPL_SPECS_COV_REPORTERS
, названия форматов отчётов передаются через запятую), см. istanbul#report. По умолчанию –['lcov']
.
- String[]
- 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
- String
completeBundle
– имя бандла, в котором будут собраны все БЭМ-сущности из уровнейlevels
. По умолчаниюcompleteBundle
не будет собран. - Boolean
saveHtml
— сохранять результат HTML при успешной отрисовке в файл (env:BEM_TMPL_SPECS_SAVE_HTML
); - Boolean
saveReferenceHtml
— создать/обновить эталон HTML рядом с BEMJSON (env:BEM_TMPL_SPECS_SAVE_REFERENCE_HTML
); - String|Function
depsTech
— технология для раскрытия зависимостей. По умолчанию —deps-old
. - Function
mockI18N
— функция будет использована вместо ядраi18n
, если указана опцияlangs: true
.
Запуск из консоли
В 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.