Storybook - Quality and Evolution

Storybook is the addition to your web front-end project, which allows you to easily build reusable UI components. In the previous essays¹², we have already discussed some of the key qualities of Storybook that makes it the convenient, unmissable, and easy to use tool it is today. We will re-visit some of the key qualities and see to what extent they are currently satisfied by the system.

Qualities & processes

First of all, the main key quality of Storybook is of course reusability. We could break this quality attribute down to a couple of applications in the Storybook system.

• Firstly, the architecture and logic allow the developer to define a UI component (including all of its states and actions) in a standardized way which can then be used to generate a framework-dependent (e.g. Angular, React) component. This component can be used anywhere in the front-end application, depending on the developer’s preference.
• Secondly, the package Storybook also meets the requirements of reusability. The source code itself is highly modular. Furthermore, by being a node module that can be easily added to your project, Storybook fits the reference reuse mechanism by acting as a dependency. The package itself also uses the reference structure for the dependencies it builds upon. Storybook uses trusted quality components, standardizes its main usages, and has documented interfaces.
• Developers can also easily build on top of Storybook. There are quite some plugin extensions for Storybook (for example, a plugin³ that allows you to add Google Analytics⁴ to your UI components) called add-ons. These add-ons can be installed using the Storybook CLI or marketplace, which also supports the reference reuse mechanism.

Another key quality we want to mention here is simplicity. Storybook’s main mission is to make the workflow of creating UI components as simple as possible⁵. This key quality is satisfied within the current system by the clear and concise interface provided to edit your components. Storybook provides one single solution for this problem and leaves out the irrelevant details, which further supports simplicity.

Some main processes ensure these key qualities. First of all, for all contributions and pull requests (PRs), there is a pipeline in place that looks at code quality, code conventions/rules, and the (unit) tests (this pipeline does not fully work currently for some PRs). But the main process that ensures the key qualities are satisfied is, of course, human feedback. The maintainers are very precise, whilst being friendly, in checking code submissions. There is also an active developer community⁶, with weekly triage meetings⁶, to maintain the key qualities of the system and to further improve the system. Code reviews are of paramount importance to maintain the quality and core spirit of Storybook.

Continuous Integration

Storybook has 1467 contributors and already nearly 8 thousand closed PRs, which is about 3 PRs per day, this makes continuous integration (CI) an important part of the development cycle. Storybook takes its CI very seriously, and therefore uses a lot of advanced tools to ensure quality. We have listed and explained these in Figure 1.

Figure 1: The 6 advanced CI tools used by Storybook.

Test processes

The three main test types are unit testing, end-to-end testing, and visual UI testing.

Unit tests

Unit testing is a method to test individual parts of the source. The main objective of unit testing is to make sure that each isolated part works as expected. It is preferred to test all files as well as possible and at least the core functionalities of the project. Unit testing catches many bugs early on and helps to improve the code quality.

Storybooks unit test coverage of the three main code directories:

The test coverage is very low, especially for a large project with nearly 70.000 stars on GitHub⁷. Storybook has an advanced CI workflow but this isn’t visible in their unit tests. Even some important core files, do not have any unit tests. Storybook supports 10 different UI frameworks, which makes writing tests harder because it requires some domain knowledge. But for such completely different systems and core functionalities you need many tests, at least much higher than 20% for the app directory. So, Storybook still can, and has to, improve their unit test coverage a lot!

Visual testing

Storybook has a built-in pixel-perfect UI testing tool. They use this visual UI testing also in their codebase. For every framework, they have some UI stories that can be tested on visual changes. These regression tests make sure that code changes do not have unwanted UI changes in any of the frameworks. This is very helpful for developers because it catches UI bugs much earlier and the UI does not have to be reviewed manually for every code review. Storybook has visual testing enabled for nearly all of its UI components which is awesome to see.

End-to-end testing

End-to-end (E2E) tests have the purpose of testing real-world user scenarios in a live production environment. For example, the use case of logging in requires a certain amount of steps to function correctly (this list is not exhaustive):

1. The UI should render correctly
2. The user should be able to fill in his credentials
3. The log-in button should authenticate the user when pressed

All these parts also need to be tested individually as seen in unit testing, but end-to-end testing ensures that a piece of functionality works as expected. Storybook end-to-end tests are made with Cypress. Cypress is a testing tool to navigate, input, and click things in a UI. While doing so you can test if certain components are visible and if the UI with underlying components works as expected. One cool feature of Cypress is that it records every step it does, so if a test fails you get a video with all steps it did and where it went wrong.

Storybook has tests for:

• Logging in and out
• Check if some of the main UI components rendered
• Check if a small and a large story loaded
• Tests if addons works

This is not bad, but could be improved a lot by adding more core real-world user scenarios. For example, changing a component in the UI is an important use case but there is no end-to-end test for it.

Test coverage conclusion

Hotspots in Storybook

Storybook is being developed very actively, with major updates coming out every year. Some parts of Storybook, however, see more changes than others. These so-called hotspot components go through many evolutions, and therefore errors are more likely to sneak through peer reviews and testing. This is why extra attention should be paid to these components. Furthermore, contributors to Storybook should be familiar with these components, as many contributions they’d like to make might require them to touch and change these components.

We will now discuss some of the components in Storybook that have seen a lot of changes in the past, and we will also look at some components that are very likely to become or remain hotspot components in the (near) future.

Hotspots up until now

Because Storybook is organized as a monorepo[reference link], finding the hotspot components in the system is fairly trivial. We can list the 100 files with the most changes by running the following command:

git log --pretty=format: --name-only | grep .ts$ | sed '/^\s*$/d' | sort | uniq -c | sort -rg | head -100

Note: We didn’t post the entire list here because of its length

When looking at Table 1, we can immediately notice the first hotspot, with 3 files in the top-5, the Client API. The client API, at the moment, is basically a facade for the story store. This is the structure that holds the information on the different stories in Storybook and manages all the different features of stories. As for other hotspot components, we can take a look at the (manager) API. This API is responsible for handling user interactions in the manager UI, such as navigating between stories, changing the layout, etc. Lastly, the webpack builders for webpack 4 & 5 have also seen a lot of changes, very much related to the push to increase speed & stability with the release of Storybook 6⁸.

Table 1: Top-5 changed files (excluding irrelevant files)

Potential hotspots in the future

As discussed in the previous section, there are still many changes happening to the client API. This is because many functions of the API will be removed in version 7.0 of Storybook. Instead, the functionalities, such as adding decorators, will now be specified in the preview.js file and handled by the core-server upon loading and generating the stories in the store. That is why we are fairly certain that the client API, and also the core-server will be or become hotspot components shortly. A major core update is planned for version 7.0⁹. Furthermore, we have been told by the maintainer team that there will be a major UI overhaul of Storybook coming in version 7.0. This is a large job and will therefore require many changes in the (manager) UI component.

Code Quality

Overall, code quality is very solid. Most classes we have seen adhere well to the single-purpose principle, and only use complex logic and functions where necessary. We like the choice of using TypeScript, to catch type errors earlier. Furthermore, we are happy to see that design patterns, such as the facade pattern in the Client API , are used when necessary.

There is not a specific coding style guide specified for contributors as far as we know. We would suggest Storybook to write one as soon as possible to maintain a homogenous codebase. Still, we are pleasantly surprised to find that most code, at least in the core of Storybook, and especially the hotspot components, is of good quality. There is one large code-smell that can be found even in the core: duplication of large amounts of code. This had been done for short-term convenience and will be removed and/or cleaned up in the future as stated in the readme¹⁰. We suggest, however, to do this as soon as possible, such that it will not become a stumbling block later on.

On the other hand, Storybook also has a lot of third-party add-ons, which are not under the purview of any Storybook maintainers. Therefore, the code quality between these add-ons likely differs a lot.

Quality Culture

Creating a culture for a software project which emphasizes high-quality code can be done in a variety of ways. We suggest five rules for creating a high-quality (open source) software culture, see Figure 2.

Figure 2: Quality culture rules

We have compared the Storybook project to each of these rules, by analyzing architecturally significant issues, PRs, and the documentation of Storybook itself.

1. A contribution guideline can be found on the Storybook documentation ¹¹. However, the guideline does not mention coding standards, such as indenting size, class size, complexity etcetera.
2. In the documentation, they mention that tests should be added as appropriate. However, this still leaves room for interpretation of what is being meant by appropriate.

• For the last three rules, we have investigated a variety of PRs and issues. Contributors are only allowed to merge when the PR is approved by a maintainer. Maintainers have a lot of domain knowledge and try to make sure that the contributions are adhering to the coding standards. We notice that PRs are thoroughly reviewed by these maintainers and that they are very constructive in their feedback. Issues have different templates for the different types of issue tickets (bug tickets, feature requests, and so on). When created, they will receive a needs triage label, which means that the issues will be discussed during the weekly triage meeting held by the maintainers. During triage, the maintainers add questions necessary to make the issue clear and the corresponding labels are being added.

All in all, there seems to be a certain quality culture within the group of maintainers of the Storybook repository. However, these rules on coding standards and quality have not been fully documented, but are shown during PR reviews and issue triages.

Technical debt

When analyzing the quality and evolution of a project, technical debt is something that should be taken into account. As Martin Fowler put it, technical debt is a metaphor for ‘deficiencies in internal quality that make it harder than it would ideally be to modify and extend the system further’¹².

Figure 3: Technical Debt Assessment ¹³.

Technical debt is something that slowly builds up over the years. Storybook’s first commit was back in December 2015 ¹⁴, which means that there have been more than 6 years in which technical debt had the time to make its way into the project. Unfortunately, technical debt does not seem of high importance to the contributors of the project. There is no overview of technical debt by the maintainers, and there are no discussions on the discord channel or the GitHub page about technical debt. Therefore, we had to do our own assessment of the technical debt present in the system, which is displayed in Figure 3.

In this article, we have discussed Storybook’s quality and evolution. While we do believe that things are heading in the right direction, some parts need to change for the quality to improve.

References