Делаем документацию правильно

Меня зовут Андрей Полетаев. Я расскажу, что такое живая документация, и как в ее создании может помочь Vanessa Automation. И еще я расскажу про функцию Onboarding, которую также предоставляет Vanessa Automation.

Живую документацию еще называют «интерактивная справка» или «интерактивные уроки». В 2011 году Гойко Аджич дал определение этому термину:

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

Это динамически изменяемая документация, максимально понятная пользователю.

Подход с живой документацией обычно используется при разработке на основе поведения (BDD) – согласно этой методике, автоматические приемочные тесты нужно писать таким образом, чтобы их можно было использовать в качестве документации.

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

Как итог, живая документация – это динамический метод системной документации, который предоставляет актуальную, точную и легкую для понимания информацию.

Многие знают о том, что в мире 1С есть фреймворк для автоматизированного тестирования Vanessa Automation, который позволяет писать тесты на дружелюбном для пользователя языке Gherkin и выполнять тестирование – как самостоятельно, так и в контурах CI/CD.

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

Список уроков

С недавнего времени на форме Vanessa Automation появилась кнопка «Открыть список уроков» – при ее нажатии Vanessa выдает список уроков.

Если нажать «Запустить урок», рядом с формой Vanessa откроется еще одна форма Vanessa. Туда подгрузится типовой сценарий, и Vanessa начнет его выполнять. Мы услышим голосовое сопровождение и увидим, что на форме происходят интерактивные действия. Vanessa нам расскажет, как взаимодействовать с тем или иным элементом, как работает та или иная функциональность.

Если ориентироваться на версию 1.2.039, то для фреймворка написано более 140 интерактивных уроков, позволяющих изучить Vanessa Automation. Недавно эти уроки были переведены на английский язык и дозалиты на YouTube.

Хочу заметить, что если мы наведем курсор на любую кнопку Vanessa и нажмем Alt+H, то нам откроется тот же самый список уроков, но они будут отфильтрованы по справке, где встречается этот элемент. Получается, мы выводим не весь список, а только тот список уроков, где этот элемент встречается.

Принципы VA для создания живой документации

Какие принципы Vanessa закладывает для создания живой документации? Они все наследуются от принципов BDD:

• Обучиться писать сценарий может каждый. Несколько дней, и вы умеете писать документацию к своему продукту. Не надо писать какие-то большие трактаты. Все это можно сделать компактно.

• Писать сценарий легко. Так как мы используем язык Gherkin, то нужно несколько минут и сценарий к документации готов. Также нам помогают типовые шаги.

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

Хочу отметить, что для людей, уже владеющих навыками написания сценарных тестов Vanessa, порог вхождения в создание живой документации практически отсутствует, так как и в первом, и во втором случае используются одни и те же шаги и механизмы отладки.

Необязательно собирать видео с документацией вручную. Vanessa Automation может запускаться в сборочных контурах CI/CD – видео с документацией может собираться в тех же самых сборочных линиях.

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

Наш штатный тестировщик в команде записал видео, чтобы показать, какие возможности есть у Vanessa Automation для построения интерактивной документации.

Мы сделали видео немного замедленным – скоростью воспроизведения также можно управлять в Vanessa Automation.

Еще раз повторюсь: штатный тестировщик, который занимается сценарным тестированием у нас в команде, в течение недели написал сценарий, используя только типовые шаги. Это заняло 220 строк кода – мы только придумали текст.

В видео можно заметить, что были некие технические огрехи в произношении. Мы не стали их убирать, чтобы показать, что эта проблема существует. Мы использовали озвучку от Яндекса, а Яндекс позволяет делать паузы и ставить правильное ударение в словах. Перспективы у технологии хорошие.

Также могу сказать, что для новых аккаунтов Яндекс дает два месяца бесплатного использования их озвучки. Можно зарегистрироваться и два месяца бесплатно тренироваться, писать живую документацию.

Синтаксис языка сценария

Синтаксис языка Gherkin, используемый при создании интерактивной документации – стандартный, такой же как для сценарных тестов.

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

До версии 1.2.039.11 была ошибка парсера – он не умел правильно разбирать озвучание без действия. В версии 1.2.039.12 ошибка была исправлена.

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

Озвучание диктором происходит параллельно. Vanessa передает озвучание и сразу переходит к действию.

Если вспомнить интерфейс Vanessa Automation, там наверху есть кнопка с динамиком. Она позволяет в режиме реального времени производить отладку озвучания.

Взаимодействие с элементами

Взаимодействовать с элементами можно двумя способами.

• Использовать простые типовые шаги от сценарных тестов.

• И появился новый тип шагов, использующий технологию UI Automation.

Новых шагов UI Automation намного меньше, чем типовых шагов. Они позволяют полностью удовлетворить потребности по взаимодействию с интерфейсом. Основной подход этих шагов – это поиск элементов по их заголовкам.

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

На видео показано различие между стандартными типовыми шагами и новыми шагами.

Обратите внимание, что при использовании обычных шагов курсор мышки плавно перемещается от элемента к элементу, а в UI Automation он телепортируется с места на место. Кому как удобней. Нужно просто помнить эту специфику.

Инспектор форм UI Automation

На слайде показано, как выглядит инспектор форм, применяемый в технологии UI Automation.

Инспектор UI Automation не входит в состав Vanessa Automation, он даже не входит в состав Windows, его нужно установить отдельно при помощи Windows SDK. И пока эта технология применима только для Windows.

Окно инспектора форм UI Automation поделено на две части:

• С левой стороны показано дерево доступных элементов – сюда входят все элементы окон операционной системы: здесь не только 1С, но и все открытые программы.

• А с правой стороны – свойства этих элементов.

Хочу обратить внимание, что для всех шагов UI Automation нужно будет указать идентификатор процесса (PID). Для его определения в Vanessa Automation есть два способа: специальный шаг, который запишет PID в переменную, или имя «ЭтотСеанс».

Подсветка объектов

Первое видео уже показывало все доступные варианты подсветки – мы можем подсвечивать элемент рамкой, баллуном и затенять.

Мы в своей работе в большинстве случаев используем подсветку затенением – такую, как на слайде.

Но у Vanessa есть некая особенность: если мы хотим просто затенить какую-то область, Vanessa этого делать не умеет – она в обязательном порядке рисует к этому элементу стрелку. Кроме того, если вы не подпишете к стрелке комментарий, при выполнении этого шага будет ошибка. Но из этого есть выход: можно в качестве комментария передать просто пустую строку, тогда у нас нарисуется просто стрелка – от стрелки пока отказаться нельзя. Возможно, в дальнейшем шаги будут доработаны, и мы сможем просто подсвечивать элементы без стрелочек.

Когда вы будете разбираться, как написаны шаги с подсветками, не используйте служебные шаги из документации к самой Vanessa Automation. Например, когда мы разбирались, мы открыли каталог со сценариями для документации Vanessa Automation, и начали смотреть, как все это устроено. А там во всех сценариях используются служебные шаги, в которых присутствует слово VA:

• И я делаю подсветку текста в редакторе VA…

• И я делаю подсветку фрагмента текста в редакторе VA…

Эти шаги специально убраны от пользователя в группу «Служебные», ими пользоваться нельзя. Вы можете в них подсматривать, но в ваших сценариях они работать не будут.

Onboarding

Что такое onboarding? Onboarding – процесс ознакомления пользователя с функциональностью. Он очень похож на интерактивную справку, но если интерактивная справка воспроизводится как видео – мы можем только нажать на паузу, то в onboarding мы можем управлять: вперед, назад, завершить.

Onboarding в современном мире – это уже обыденная вещь. В вебе он встречается сплошь и рядом. В десктопных приложениях – намного реже. Но если вспомнить тот же самый Word 97 – там была всплывающая скрепочка, которая все показывала и рассказывала. Это тоже был onboarding. Ему уже, можно сказать, сто лет в обед.

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

А дальше можно развивать технологию onboarding от простого к сложному, чтобы прийти к интерактивному курсу по продукту. Это финальная стадия развития onboarding. Также в финальной стадии наши текстовые описания заменятся озвучанием.

Если говорить проще, то с помощью onboarding мы подсвечиваем какие-то элементы, говорим: «Нажмите сюда», пользователь нажимает, система проверяет – правильно или неправильно, и предоставляет последовательность дальнейших действий по какому-то алгоритму. Сейчас это в Vanessa Automation еще не реализовано.

У меня есть видео, где я показываю, каким образом при повышении версии продукта Onboarding помогает рассказать про новые элементы, появившиеся на форме.

Обратите внимание, здесь онбординг автоматически запускается только при первичном открытии формы после повышения версии. Когда мы открыли форму повторно, уже ничего не происходит.

Важно – серый фон не блокирует форму, это сделано специально. Если кликнуть на любое место серого фона, onboarding остановится.

Чтобы использовать onboarding в своей конфигурации, в нее нужно установить расширение VanessaInteractive. Исходники этого расширения опубликованы в проекте Vanessa Automation в папке /lib/. Его можно загрузить себе в конфигурацию и посмотреть, как все это устроено.

Из чего состоит Onboarding

На слайде – самый простой пример, как сделать onboarding для своей конфигурации.

Onboarding в конфигурацию встраивается в виде расширения. Это некая основная идея, что в конфигурации ничего не нужно менять, нужно создать расширение и при помощи этого расширения создавать onboarding.

• Создаем расширение для конфигурации.

• В это расширение мы вносим из Vanessa Interactive два общих модуля – они стандартные, их изменять нельзя, просто копируем, вставляем.

• В обработки расширения вставляем VanessaSingle – ее можно взять из релизов проекта или скомпилировать из исходников самостоятельно, документация по этому есть.

• Каждую форму конфигурации, в которой планируется запускать сценарий Onboarding, нужно добавить в расширение.

• И на форме в расширении добавляем кнопку для вызова Onboarding. Где ее разместить, каждый разработчик выбирает сам – это можно сделать в командной панели, во «Всех действиях» или где-то еще на форме.

В обработчике этой кнопки нам нужно написать 4 блока кода:

&НаКлиенте
Процедура Расш1_OnboardingПосле(Команда)

	Ванесса = VanessaInteractiveКлиент.ПолучитьФормуVanessaAutomation();

	СтруктураНастроек = Новый Структура;
	СтруктураНастроек.Вставить("ИспользоватьКомпонентуVanessaExt", Истина);
	Ванесса.УстановитьНастройкиПриЗапускеБезОткрытияФормы(СтруктураНастроек);

	Ванесса.УстановитьТекстФичаФайла(ТекстФичаФайла());

	Ванесса.ВыполнитьСценарииБезОткрытияФормы();

КонецПроцедуры

• В первом блоке мы получаем саму форму Vanessa Automation.

• Вторым блоком мы в Vanessa Automation передаем параметры в виде структуры – это те же самые параметры, которые мы передаем в VAParams.json, доступные для него параметры все наверняка знают.

• Третьим шагом нам нужно установить текст фича файла. Это такой же фича файл, как те, что пишутся для сценарных тестов. Но в нем есть небольшое ограничение – в нем нужно написать только один сценарий. Если вы напишете в этом несколько сценариев или попытаетесь скормить Vanessa что-то большое, будет ошибка.

• После того как мы текст фича файла установили, мы выполняем сценарий без открытия формы – Vanessa подгружается и запускается onboarding.

Также на форму нужно добавить две обязательные функции:

&НаКлиенте
Функция ДанныеРеквизитовФормыOnboarding() Экспорт
	Возврат ДанныеРеквизитовФормыOnboardingСервер();
КонецФункции
&НаСервере
Функция ДанныеРеквизитовФормыOnboardingСервер()
	Возврат VanessaInteractive.ДанныеРеквизитовФормыOnboarding(ЭтаФорма);
КонецФункции

Они стандартные, их изменять не нужно.

Файл фичи можно загрузить из любого места. Например, мы у себя создаем макет, называем «OnboardingЧтоTо» или «OnboardingВерсияТакаяТо», получаем текст и этот текст скармливаем Vanessa.

&НаСервере
Функция ТекстФичаФайла()
	Возврат Документы.ПересчетТовара.ПолучитьМакет(“Onboarding”).ПолучитьТекст();
КонецФункции

По структуре самого сценария, как это выглядит:

A279;#language: ru
Функционал: Onboarding Пересчет товаров
Сценарий: Onboarding
		И я создаю состояние Onboarding
			| 'Имя'                | 'Номер'           |
			| 'ИмяЭлемента'        | 'Номер'           |
			| 'Текст'              | 'Номер документа' |
			| 'НачальноеСостояние' | 'Да'              |
			| 'Окно'               | 'Пересчет товаров*'  |
			| 'Переход'            | 'Дата'            |
		И я создаю состояние Onboarding
			| 'Имя'         | 'Дата'   |
			| 'ИмяЭлемента' | 'Дата'   |
			| 'Текст'       | 'Дата'   |
			| 'Переход'     | 'ТорговаяТочка' |
		И я создаю состояние Onboarding
			| 'Имя'               | 'ТорговаяТочка'    |
			| 'ИмяЭлемента'       | 'ТорговаяТочка' |
			| 'Текст'             | 'Торговая точка нужна для указания торговой точки. Возможно выбрать из справочника' |
			| 'Переход'           | 'Комментарий' |
		И я создаю состояние Onboarding
			| 'Имя'               | 'Комментарий' |
			| 'Переход'           | 'Записать'          |
			| 'ИмяЭлемента'       | 'Комментарий' |
			| 'Текст'             | 'Служит для указания комментария по документу' |
			| 'КонечноеСостояние' | 'Да'        |
		И я создаю состояние Onboarding
			| 'Имя'               | 'Записать' |
			| 'Переход'           | ''          |
			| 'ИмяЭлемента'       | 'ФормаЗаписать' |
			| 'Текст'             | 'По окончании заполнения полей требуется записать документ |
			| 'КонечноеСостояние' | 'Да'        |
	И я запускаю Onboarding

В onboarding вообще все просто. Существует пока что два шага.

• И я создаю состояние Onboarding

• И я запускаю Onboarding

Все, больше шагов для Onboarding нет.

С помощью шага “И я создаю состояние Onboarding” мы определяем элемент, который у нас будет подсвечиваться:

• указываем имя элемента;

• пишем текст;

• говорим, куда мы дальше переходим.

Набираем эти элементы в некий массив состояний, и дальше просто их передаем уже в Vanessa для запуска onboarding с помощью шага “И я запускаю Onboarding”.

Хочу обратить внимание, что чем больше будет элементов в этом массиве состояний, тем дольше этот Onboarding подгружаться. Не советую делать длинные пути Onboarding – Несколько элементов и загружается все практически молниеносно.

Развитие Vanessa Automation в плане документации и onboarding не стоит на месте. Проект open source. Надеюсь, что в ближайшее время мы увидим от него что-то новое и интересное.

Вопросы и ответы

Кто и на каком этапе пишет фича-файлы?

Фича-файлы могут писать как тестировщики, так и аналитики – ничего сложного в этом нет.

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

Инструкции для тестов, для onboarding и для всего остального у вас в разных файлах разложены или все вместе? Различаются ли фича-файлы для тестирования и для документации?

Для документации можно использовать стандартные шаги, которые используются для сценарного тестирования. Как раз методология BDD подразумевает, что мы не пишем документацию как документацию отдельно. Мы пишем приемочный тест, и этот тест является документацией.

А если говорить по onboarding, то он встраивается или в расширение, или может использоваться из какого-то отдельного файла, но этот файл немного ограничен одним сценарием.

А так все стандартно: один и тот же язык Gherkin, никаких существенных изменений в этом нет.

*************

Статья написана по итогам доклада (видео), прочитанного на конференции Infostart Event 2022 Saint Petersburg.