How to revive the documentation?
Probably every team is familiar with this pain - irrelevant documentation. No matter how hard the team tries, in modern projects we are released so often that it’s almost impossible to describe all the changes. Our testing team, together with system analysts, decided to try to revitalize our project documentation.
Alfa-Bank's web-projects use the Akita testing framework, which is used for BDD scripts. To date, the framework has gained great popularity due to the low threshold of entry, ease of use and the ability to test the layout. But we decided to go further - on the basis of the described test scenarios to generate documentation, thereby greatly reducing the time that analysts spend on the perennial problem of updating the documentation.
')
In fact, along with Akita, a plugin for generating documentation was used, which went through the steps in the scripts and unloaded them into the html format, but in order to make this document in demand, we needed to add:
We looked at our existing plugin, which was, in fact, a static analyzer and formed the documentation based on the scripts described in the .feature-files. We decided to add speakers, and in order not to fence the plugin above the plugin, we decided to write our own.
To begin with, we decided to find out how we can collect screenshots and values of variables used in test scenarios from feature files. Everything turned out to be quite simple. Cucumber, when running tests for each feature file, creates a separate cucumber.json.
Inside this file are the following objects:
Test case name and keyword:
Arrays of elements - scripts and steps themselves:
The output field contains additional information, such as variables - addresses, links, user accounts, etc .:
Embeddings contains screenshots that selenium makes during the tests:
Thus, we just need to go through the cucumber.json files, collect the names of test cases, test scenarios, pull out the steps, collect additional information and screenshots.
In order for the documentation to display requests that occur in the background or for a specific action, we had to ask our front developers for help. With the help of proxy, we were able to catch traceId, which is generated by front-end requests to services. The same traceId logs are written in elastic, from where we pull up all the necessary query parameters in the testing report and documentation.
As a result, we got a file in Asciidoc format - a convenient file format, a bit more complicated than the markdown analog, but it has much more formatting capabilities (you can insert an image or a table, which you cannot do in markdown).
To convert the resulting Asciidoc to other formats, use Ascii doctorj, which is the official version for the AsciiDoctor Java tool. As a result, we get ready-made documentation in html format, which can be loaded into confluence, sent to a colleague or put in a repository.
Now, to generate front-line documentation for your project, you just need to connect the documentation plugin to it and after running all the tests, run the
Alfa-Bank's web-projects use the Akita testing framework, which is used for BDD scripts. To date, the framework has gained great popularity due to the low threshold of entry, ease of use and the ability to test the layout. But we decided to go further - on the basis of the described test scenarios to generate documentation, thereby greatly reducing the time that analysts spend on the perennial problem of updating the documentation.
')
In fact, along with Akita, a plugin for generating documentation was used, which went through the steps in the scripts and unloaded them into the html format, but in order to make this document in demand, we needed to add:
- screenshots;
- variable values (config File, user accounts, etc.);
- request statuses and parameters.
We looked at our existing plugin, which was, in fact, a static analyzer and formed the documentation based on the scripts described in the .feature-files. We decided to add speakers, and in order not to fence the plugin above the plugin, we decided to write our own.
To begin with, we decided to find out how we can collect screenshots and values of variables used in test scenarios from feature files. Everything turned out to be quite simple. Cucumber, when running tests for each feature file, creates a separate cucumber.json.
Inside this file are the following objects:
Test case name and keyword:
Arrays of elements - scripts and steps themselves:
The output field contains additional information, such as variables - addresses, links, user accounts, etc .:
Embeddings contains screenshots that selenium makes during the tests:
Thus, we just need to go through the cucumber.json files, collect the names of test cases, test scenarios, pull out the steps, collect additional information and screenshots.
In order for the documentation to display requests that occur in the background or for a specific action, we had to ask our front developers for help. With the help of proxy, we were able to catch traceId, which is generated by front-end requests to services. The same traceId logs are written in elastic, from where we pull up all the necessary query parameters in the testing report and documentation.
As a result, we got a file in Asciidoc format - a convenient file format, a bit more complicated than the markdown analog, but it has much more formatting capabilities (you can insert an image or a table, which you cannot do in markdown).
To convert the resulting Asciidoc to other formats, use Ascii doctorj, which is the official version for the AsciiDoctor Java tool. As a result, we get ready-made documentation in html format, which can be loaded into confluence, sent to a colleague or put in a repository.
How to connect?
Now, to generate front-line documentation for your project, you just need to connect the documentation plugin to it and after running all the tests, run the
adoc command.What do we want to improve?
- Add configurable technical steps.
In the current version of the plugin there are steps "And a screenshot is made ...". Such steps do not carry meaning for the documentation, and we want to hide them. Now we have stitched them inside the plug-in, and they are skipped, but there is a drawback - each addition of such a step leads to the fact that we need to build a new version of the plug-in. To get away from this, we plan to put such steps into the configuration file and prescribe those steps that we don’t want to see in the scripts. - Make open sourse plugin.
Which teams will suit our implementation?
- use Cucumber (or a similar framework);
- want to have relevant documentation for the front and knowledge base;
- They want to involve analysts in testing.
Result:
The pilot on several teams showed that with the help of the plugin we manage to keep the documentation up to date, analysts do not need to spend their time more on maintaining it. In addition, the realization of this opportunity made us think about continuing to implement a full-fledged BDD within teams. At present, we are experimenting - analysts formulate a positive way for the client, indicate business restrictions using Akita BDD steps, testers, in turn, write custom steps and additional checks to these scenarios.By the way, about holivar, whether BDD is needed or not, on Monday we will hold a special mitap .
Source: https://habr.com/ru/post/454720/
All Articles