Vanessa-Automation is a tool for autodocumenting application solutions on the 1C: Enterprise platform. Cinema and BDD
What is it and what is necessary
I am not interested in stories that leave the viewer indifferent. I want to leave the cinema man thought: "Gosh, I need a drink." (c) Killian Murphy
So what does Kino and BDD mean ?! Welcome under cat.
I will talk about the tool, which from the script written on Gherkin (there is such a scripting language), makes the instruction, or rather, the actual documentation (Living documentation).
In order not to torment you, I will immediately show the result of my (and not only) works.
I will tell you how, from the script written below, to make such a video here with one click. I note that scripts can be written not only in Russian, but also in other languages.
It's not a secret - the documentation becomes obsolete with time, but keeping it up to date is expensive, and it “breaks”. The documentation is already there, but it is always necessary to supplement something, change screenshots, etc. Here bearded guys come up out of nowhere and assure that there is a magical way to do all your development in a cool way (all of your trendy TDDs / BDDs, etc.), with which all your code is written by itself, it tests and documents itself.
And so, driven by laziness and faith in a bright future, 1C programmers decided to implement this concept. I will show how this works using the example of the Vanessa-Automation tool .
So. One user needs documentation in the form of textual documentation (HTML, Markdown), another in the form of a screencast, and the third in the form of auto-video. And for all the "hotelok" there is a solution in one bottle.
Generate HTML and Markdown
In order to generate HTML and text in markdown, you need to install a utility for taking screenshots (IrfanView, nircmd or the like). Next, turn on this setting. (Service - Autoinstructions. We are looking for the HTML and Markdown sections). Configure the folder in which we will save the automatically generated auto-instructions. Example:
We start our feature, if there were no errors - the auto-instruction is saved:
Without any difficulty, we can make a video. To do this, you need to set up the environment for recording video according to the instructions and enjoy the process. No need to cut the video, glue and impose sound. This is all done automatically.
Every video comes with subtitles. We can pause and read. Not difficult. We do the most convenient for the user.
If it is boring to read, you can make the voice acting by voice. To do this, install the library and run our script. In a couple of minutes, the voice over video will be ready.
There is a function of overlaying a watermark, highlighting the active element on the screen (this feature works for platform versions 8.3.11 and below) (yes, users like it when they chew on everything) and mouse movements to where the “Action” takes place.
Flexible video customization
It all starts with the script and ends there. Exactly.
You can configure your CI server so that it does not generate documentation for all scripts, but only for the necessary ones. To do this, we add a tag in scenarios intended for auto-lines, for example
@tree(the selection for this tag will work later) and ... enjoy the process.
In theory, when you write a big script, you still have to divide it into logical blocks, make comments in it (that this super important flag must be set, otherwise it will not work).
The idea of avtovideo is that these comments become part of the “story” that we show to the user.
For this, for example, you can change the text of the step, make it more “humane”, as we write the script on Gherkin, but for users it is not always convenient to listen to the business language and therefore there is a directive
#[autodoc.text]. For me, this is one of the important features of Vanessa-Automation, since users have different competencies - I try to write as clearly as possible.
Some steps in the scenario you want to combine into one (often this concerns some obvious operations). For example, add data to the tabular part. Or when one step of a business scenario (filling in the header of a document) consists of dozens of actions. Then the directive is used
#[autodoc.groupsteps]. I want to note that the autodoc directives work for both video and html and markdown instructions. The remaining directives are described in the
When we watch the generated video, there will initially only be video without sound. Some screenshots and text flash, it becomes boring and you stop to delve into it. Yes, and sad somehow without music. The background to the video, you can put the "light" music (or any weight, every whim) to read more fun. The learning process will go faster :) The experience of creating such videos has shown that when the background music is played, the video is easier to understand. Without music - dry somehow.
When recording a video, the cursor is not displayed and you cannot see where we click on which element. For this there is a setting for displaying the cursor and highlighting a form element.
All of the above settings are shown in the video and in the script that was generated after the successful passage of the script.
Auto update video on YouTube
For the nightly assembly (well, we are not going to upload videos on YouTube with our hands, right?), You can implement automatic uploading of the video to the youtube channel.
We set a script on our folder with our feature that determines that the file has changed, then builds the video and uploads it to the right place.
For avtovideo, I made a simple application on
Golang(why on it? I studied go and there was a real task where I could apply it. If there was something else, it would be on something else), which sends the finished video to the youtube channel. This, of course, is just an example. Videos can be added to your wiki or knowledge base, etc.
I give you a test script that generated the video.
или подключаю уже существующий Сценарий: Новые возможности. И В командном интерфейсе я выбираю "Основная""Приветы Для Habr" И текст субтитров "Тут можно писать текст какой нам хочется! А не - в командном интерфейсе я выбираю..." И обратите внимание "А тут могла быть ваша реклама :-)" Выполняется группа шагов. Но в видео она работает как один шаг, с одним текстом для всей группы. И я нажимаю на кнопку "Создать" И в поле с именем "Наименование" я ввожу текст "Привет Habr" И в поле "Число" я ввожу текст "14,00" И в поле "Дата" я ввожу текст "14.08.2018" И в поле с именем "Текст" я ввожу текст "Передаю всем привет!" И я нажимаю на кнопку "Записать и закрыть" И обратите внимание "Спасибо за внимание."@tree Функциональность: Некоторые возможности автоинструкций. Контекст: Дано Я запускаю сценарий открытия TestClient
Thank you for your time. No matter how wild this may sound, the 1C community has stepped forward (
and in some things even overtook someone), opensource testing tools appeared, CI - integration. 1C does API for its products - this allows enthusiasts to automate areas that 1C hasn’t reached yet, but is on the sly. And soon we will have a new brave world :) I’m waiting for us to create in EDT without critical errors.