Documentation driven tests for UI development
At jtendo we strive for reusable and reliable solutions when it comes to frontend development. With these two key ideas in mind we came up with our own UI “blocks” library.
In this article, I would like to present how we handle two tasks that are not very popular among developers but crucial for UI creation – maintaining proper component documentation and a test base. You will see how both of these tasks may support each other.
As an appetizer, let’s talk about technology stack. In most cases our frontend products are created/built using React, a framework that is great for our clients and us developers.
Tests are based on React Testing Library and run by Jest. We agree that React Testing Library is the best solution as stated on its website:
“The more your tests resemble the way your software is used, the more confidence they can give you.”
It means we do not have to worry about component implementation affecting our test cases.
When choosing documentation tools, our main goals were reliability, usage examples and a proper description of thecomponent API, ideally with graphical and interactive UI. All these requirements were met with Storybook.
Storybook is a great tool for UI development that generates component-based documentation, where multiple use cases and variants (so called stories) can be presented in an interactive way.
The Storybook approach of presenting components goes hand in hand with atomic UI design and results in improved overall code architecture. For example, it indicates too much complexity in state management or too much responsibility given to a single UI component. In addition, Storybook infers metadata values based on source code, types and JSDoc comments, resulting in fewer zombies or misleading comments compared to typical comment-based documentation.
We decided to work with the two tools independently, so it was even cooler when we found that stories created for documentation can be reused as test cases for our tests! Storybook’s approach of presenting multiple component variants resulted in a better understanding of what actually should be tested from a business perspective. This combined with coverage reports makes testing a way better experience for developer.
Using both tools results in faster analysis of UI component use cases and gives us an excellent reason to prepare documentation, which now is an input for our unit tests.
Quality assurance, testing, documenting and maintaining a library is a huge topic to cover in one article, but hopefully our brief presentation of our experience at jtendo will inspire you to dig further into the topic.