The symbiosis of test and documentation

  • Blog
  • >
  • The symbiosis of test and documentation

30 Day Free Trial

Bring together legacy systems, RPA bots, microservices and more with Camunda

Sign Up for Camunda Content

Get the latest on Camunda features, events, top trends, and more.

We want to build a library of reusable widgets, which are tested and documented. The components of the Tasklist search are examples for such widgets:

tasklist search

This blog entry describes how we document and test widgets and make sure that tests and documentation stay in sync.


With E2E tests we specify and test the desired behavior of the widgets. For our angular widgets, we use Protractor. E2E tests interact with a webpage, e.g. by clicking on links and buttons or typing text. This simulates the user behavior. To run these tests, we have to create the webpages the tests use. These webpages display the widget in the environment we want to test.


For the documentation, we describe the interface of the widget and show scenarios where this widget can be used. We also include code samples. This allows developers to copy the code into their application and get an instance of the widget. We also have to create a webpage for this documentation.

Bringing Both Together

Creating separate webpages for documentation and tests creates some problems: When we change the interface or implementation of a widget, we have to adapt both pages. There is a much higher risk of inconsistency between tests and documentation. Therefore documentation and tests should be close together.

To solve this problem, we create a single webpage, which serves as documentation page, but is also used for automated testing. This page contains three parts:

  1. Interface description: Very useful for the developers, but ignored by Protractor
  2. Example codes: Also useful for the developers, ignored by Protractor
  3. Functional Sample Widgets: Useful for the developers. They can play around with the widget before using it in the app. This is also the part where Protractor performs its tests.
By having documentation and test on the same page, we ensure that both stay in sync and consistent.

documentation and test on the same page

Try It Out!

  1. Check out the camunda-commons-ui project
  2. To execute the tests:
    1. In the root directory, execute grunt
  3. To access the documentation:
    1. In the root directory, execute grunt connect:widgetTests:keepalive
    2. Navigate to the .spec.html file of the widget (e.g. https://localhost:8070/lib/widgets/search-pill/test/search-pill.spec.html)

Try All Features of Camunda

Related Content

An integral part of process orchestration is process automation—get those repeatable, well-understood tasks that don't require complex decision-making on autopilot!
Enhance your business's operational efficiency with business process management, and streamline your workflows to reduce cost and minimize risk.
Transition smoothly from design to implementation with an end-to-end business process. We'll show you how!