Что это и для чего надо
Меня не интересуют истории, которые оставляют зрителя безразличным. Я хочу, чтобы выходя из кинотеатра человек думал: «Черт возьми, мне нужно выпить». (с) Киллиан Мёрфи
Так, что это значит Кино и BDD?! Добро пожаловать под кат.
Я расскажу об инструменте, который из сценария, написанного на Gherkin (есть такой язык сценариев), делает инструкцию, а точнее — актуальную документацию (Living documentation).
Чтобы вас не томить — сразу покажу результат моих (и не только) трудов.
Я расскажу вам как из сценария, написанного ниже, сделать вот такой вот ролик одним кликом. Замечу, что сценарии можно писать не только на русском языке, но и на других языках.
Не секрет — документация со временем устаревает, а поддерживать её в актуальном состоянии затратно, да и “ломает”. Документация уже есть, но постоянно надо что-то дополнять, менять скрины и т.п. Тут из ниоткуда выныривают бородатые дядьки и уверяют, что есть волшебный способ сделать всю вашу разработку по крутому (все эти ваши модные TDD/BDD/и т.д.), с помощью которого весь ваш код пишется сам, сам себя тестирует и документирует.
И вот, движимые ленью и верой в светлое будущее, программисты 1С решили реализовать этот концепт. Я буду показывать как это работает на примере инструмента Vanessa-Automation.
Забыл сказать (на самом деле, конечно не забыл, а сознательно оттягивал :-) — этот инструмент для 1С. Моя цель рассказать вам об инструменте, дополняющем 1С. Да, такие инструменты есть, даже больше — они выложены на github и активно развиваются. Позволю себе небольшое отступление. Многие знают, что сейчас есть много фреймворков для JavaScript, то есть живут настоящим, но почему-то многие в отношения 1С живут прошлым. Я хочу показать, что мир 1С развивается. Есть нормальные Open Source инструменты для 1С.
Итак. Одним пользователем нужна документация в виде текстовой документации (HTML, Markdown), другим в виде скринкаста, третьим в виде автовидео. И для всех "хотелок" есть решение в одном флаконе.
Генерация HTML и Markdown
Для того, чтобы генерировать HTML и текст в markdown, необходимо установить утилиту для снятия скриншотов (IrfanView, nircmd или подобное). Далее включаем данную настройку. (Сервис — Автоинструкции. Ищем раздел HTML и Markdown). Настраиваем папку, в которую будем сохранять автоматически сгенерированные автоинструкции. Пример:
Запускаем нашу feature, если не было ошибок — сохраняется автоинструкция:
Генерация видео
Без всякого труда мы можем сделать видео. Для этого необходимо настроить окружение для записи видео по инструкции и наслаждаться процессом. Не надо нарезать видео, склеивать и накладывать звук. Это всё делается автоматически.
Каждое видео идёт с субтитрами. Можем поставить на паузу и почитать. Не сложно. Делаем максимально удобно для пользователя.
Если скучно читать, можно сделать озвучку голосом. Для этого устанавливаем библиотеку и запускаем наш сценарий. Через пару минут видео с озвучкой будет готово.
Есть функция накладывания водяного знака, подсветки активного элемента на экране (эта фича работает для версий платформы 8.3.11 и ниже) (да, пользователи любят когда им всё разжевывают) и движения мышки туда, где происходит “Экшн”.
Гибкая кастомизация видео
Всё начинается со сценария и на нём же заканчивается. Именно так.
Можно настроить ваш CI сервер так, чтобы он генерировал не для всех сценариев документацию, а только для необходимых. Для этого в сценариях, предназначенных для автодоков добавляем тег, например @tree (далее будет работать отбор по этому тегу) и… наслаждаемся процессом.
По идее, когда вы пишете большой сценарий, вам всё равно придётся его делить на логические блоки, делать в нём комментарии (что вот этот супер важный флажок надо установить, иначе ничего работать не будет).
Идея автовидео в том, чтобы эти комментарии стали частью “истории”, которую мы показываем пользователю.
Для этого, например, можно изменить текст шага, сделать его более “человечным”, так как мы пишем сценарий на Gherkin, но для пользователей не всегда удобно слушать бизнес язык и поэтому есть директива #[autodoc.text]. Для меня это одна из важных фич Vanessa-Automation, так как пользователи разные по компетенции — стараюсь писать максимально понятно.
Некоторые шаги в сценарии хочется объединить в один (часто это касается каких-то очевидных операций). Например, добавить данные в табличную часть. Или когда один шаг бизнес сценария (заполнение шапки какого-нибудь документа) состоит из десятков действий. Тогда используется директива #[autodoc.groupsteps]. Хочу заметить, что директивы автодоков работают как для видео, так и для html и markdown инструкций. Остальные директивы описаны во встроенной справке проекта.
Когда мы смотрим сгенерированное видео, то там изначально будет только видео без звука. Мелькают какие-то скриншоты и текст, становится скучно и перестаёшь вникать. Да и грустно как-то без музыки. Фоном к видео можно поставить “лёгкую” музыку (или какую-нибудь тяжесть, любой каприз), чтобы веселее читалось. Процесс изучения пойдёт быстрее :) Опыт создания таких видео показал, что когда фоном играет музыка, то видео воспринимается проще. Без музыки — сухо как-то.
При записи видео не отображается курсор и не видно куда мы нажимаем, на какой элемент. Для этого есть настройка отображения курсора и подсветка элемента формы.
Все вышеперечисленные настройки показаны в видео и в сценарии, которые сгенерировались после успешного прохождения сценария.
Автообновление видео на ютуб
Для ночной сборки (ну мы же не собираемся заливать ролики на ютуб руками, правда?) можно реализовать автоматическое выкладывание видео на youtube канал.
Натравливаем на папку с нашими feature скрипт, который определяет, что файл изменился, затем делает сборку видео и заливает его куда надо.
Для автовидео я сделал простое приложение на Golang (почему на нём? Изучал go и появилась реальная задача, где можно его применить. Если было бы что-то другое, было бы на чём-то другом), которое отправляет готовый ролик на youtube канал. Это, конечно, просто пример. Видео можно добавлять в ваши Wiki или базу знаний и т.п.
Заключение
Привожу вам тестовый сценарий, по которому сгенерировано видео.
Пример, feature.
#language: ru
@tree
Функциональность: Некоторые возможности автоинструкций.
Контекст:
Дано Я запускаю сценарий открытия TestClient или подключаю уже существующий
#[autodoc.ignore.scenarioslide]
Сценарий: Новые возможности.
#[autodoc.text] Начнём с того, что у шага можно указывать произвольный текст.
И В командном интерфейсе я выбираю "Основная" "Приветы Для Habr"
И текст субтитров "Тут можно писать текст какой нам хочется! А не - в командном интерфейсе я выбираю..."
И обратите внимание "А тут могла быть ваша реклама :-)"
#[autodoc.groupsteps]
Выполняется группа шагов. Но в видео она работает как один шаг, с одним текстом для всей группы.
И я нажимаю на кнопку "Создать"
И в поле с именем "Наименование" я ввожу текст "Привет Habr"
И в поле "Число" я ввожу текст "14,00"
И в поле "Дата" я ввожу текст "14.08.2018"
И в поле с именем "Текст" я ввожу текст "Передаю всем привет!"
И я нажимаю на кнопку "Записать и закрыть"
И обратите внимание "Спасибо за внимание."
Краткая инструкция как настраивать автодокументирование лежит тут.
Инструкция как настраивать автодокументацию.
Спасибо за потраченное время. Как бы дико это не звучало, но 1С сообщество шагнуло вперёд (и в чём-то даже кого-то обогнало), появились opensource инструменты тестирования, CI — интеграция. 1С делает для своих продуктов API — это и позволяет энтузиастам автоматизировать участки, до которых 1С пока не дошла, но потихоньку идёт. А скоро нас ожидает новый дивный мир :) Я в ожидании, когда мы сможем без критических ошибок творить в EDT.
P.S.
Поддержите проект добрым словом, лайком, критикой (чат проекта в Gitter находится здесь) авторам это всегда приятно.