How we automatically keep our Documentation Screenshots up to date

When you open the Camunda User Guide, you’ll see that there are many screenshots explaining the different functions and options the product offers. We hope that you, as a user, find those screenshots helpful. But for us as developers, creating and keeping those screenshots up to date has always been a pain.

Camera

https://unsplash.com/photos/dDppsuM_UpE

At the time of writing, the user guide for Camunda Optimize contained 94 screenshots. And with every release we add more functionality, which means the number of screenshots continuously grows. When we change the look of buttons or add a new section to the header, we need to update every screenshot that has a button or header in it. In practice, this meant we were manually recreating every screenshot for every release. With almost 100 screenshots, most of which show quite complex situations, simply updating the user guide would take us a day or two.

As developers, and especially as developers of workflow automation tools, we were eager to automate this time-consuming task.

End-to-end Tests to the Rescue

As part of our commitment to deliver high-quality and stable software, all our products are automatically tested. In Optimize, in addition to unit and integration tests, we also use end-to-end testing to ensure that the functionality we describe in the user guide works.

End-to-end testing means that an automated program interacts with the browser in the way a normal user would interact with the site. Clicking on buttons, entering text, navigating around, making sure everything works as expected.

To run those automated tests, we use a library called testcafe. If you look at the “Interact with the Page” section of their documentation, you’ll find all the actions you would expect from such a testing framework. Beside clicking, pressing keys, entering text, there is also a “Take Screenshot” action. This is often used to get a snapshot of the page in case any test fails, so you can see what was going on.

But we were wondering: Could we use this screenshot functionality to escape the realm of testing and help us with the documentation too?

Screenshot

Forming a Plan

We figured out that we can make screenshots of the page while we run the end-to-end tests. But that does not mean that those screenshots are useful for the user guide documentation.

In the user guide, the screenshots have to fit the scenario described in the text. So if we want to automatically create them, we must make sure that the test that produces them is related to the text on the user guide. Our end-to-end tests need to serve two purposes: Testing that the product works as expected, while at the same time creating scenarios that can be used to take screenshots for the user guide.

At this point we pragmatically thought: “Well, by writing features in the documentation we guarantee that these work, so we should have those features covered in end-to-end tests anyway”.

So we took the existing documentation as a guide to go over our existing end-to-end tests and adjust and extend them so they reflect the features described in the user guide documentation. After that, the only thing left to do was to take screenshots at the right moment in the test and put them in the documentation.

Custom Annotations

Sometimes you need more than just a screenshot. You might have UI elements that need more explanation, like in this example:

Invoive Pipeline

We wanted to have a way to add annotations to the screenshot.

The first idea we had was to just create a transparent png and put it above the generated screenshot. This, however, would cause problems if an update changes the position of the elements we want to annotate.

We needed a way to create the annotations with the contextual information of the page. Ideally, the annotation is there when the screenshot is being taken, so it has to be part of the tested code.

Testcafe offers the ability to run a function on the “client-side”, which means in the browser that is running the test. This is meant to get information from the browser, such as the window location or the document URI. But this is just some Javascript that is injected into the tested page and can be triggered by the test code.

So we wrote a snippet that takes an annotation text and css selector for the element to annotate. It then creates a div container and puts it on the page. In the test code it would look like this:

Snippet

With that, we are able to dynamically add annotations wherever we want and can put the resulting screenshots directly into our documentation without any manual adjustments.

What are the limitations?

While we were able to automate the generation of a majority of the screenshots, some still need to be updated manually. For Optimize this affects primarily dashboards, as the drag and drop operation is poorly supported by testcafe. There is an open issue to improve that.

If the testcafe team implements this, we might come back to this topic once more. For now we enjoy the time we save every release not having to worry about screenshots as much.

Photo

https://unsplash.com/photos/Ncj5R2Wdlh4

  • Camunda Halloween

    It’s a very Camunda Halloween, and this project should keep you safe from the Trick-or-Treaters! It’s more than just a BPM process, of course. It’s an IoT project that uses Camunda BPM to deliver the goods. I’ll break this post up into several sections, but you will need (or at least need access to) a 3-D printer to fully realize the awesomness here. It uses a modified Dog Treat Dispenser because I didn’t have the time (or the skills) to design a whole new Candy Dispenser from scratch. Overview This is both a hardware and a software, as well as a BPMN, project, so there are a lot of moving parts — literally and figuratively. The first thing I had...

    Read more
  • Testing Entire Process Paths

    Why should I test my process models? The short answer is: From a technical point of view, BPMN is a programming language. Therefore, diagrams should be treated like code.

    Read more
  • Three hidden threats of RPA technical debt...

    If you’re looking to selectively automate the work of individual components in legacy systems, and help automate processes without a significant time investment — RPA should be on your radar.  Global companies like Deutsche Telekom have already introduced and automated 2,500 individual bots, resulting in savings of more than 100 million Euros. However, relying too heavily on RPA can land you in hot water. Paul Jones, Business Automation Services at NatWest even classifies RPA as technical debt.  So what can you do to avoid this debt? Prevention is the best cure and before jumping on the RPA bandwagon, think carefully about whether you need an RPA solution, or a workflow engine. Losing control of long-running processes The ability to automate...

    Read more