Watch Live! CamundaCon 2023 is Happening Now

Watch for Free

The symbiosis of test and documentation

  • Blog
  • >
  • The symbiosis of test and documentation
TOPICS

30 Day Free Trial

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

Join the Camunda Developer Newsletter

Get the latest events, release notes, and product updates straight to your mailbox.

TRENDING CONTENT
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.

Tests

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.

Documentation

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 Platform

Related Content

Get all the latest updates and recaps of what's happening in this live blog of CamundaCon 2023.
Learn how Connectors from a process orchestration solution like Camunda can pair with RPA tools to make automation easier.
Why Camunda? Learn how real estate invester Heimstaden utilizes Camunda to orchestrate their tenant support ticketing system.