Storybook Driven Development
React Storybooks + Style-guide Driven Development = 💘
Style-guide driven development is a fantastic idea about how to keep a style guide from becoming outdated due to neglect.
Nicole Sullivan developed the idea while working at Pivotal Labs in New York. The idea is simple:
Build your User Interface in your style guide first
What this means is that when building new features or updating existing components, you open up your style guide and write the code you need to make your style guide look right before implementing the new UI in-app.
Something-DD
This workflow mimics the familiar practice of Test Driven Development (the first great Something-DD). The epiphany of TDD is that tests are essential to developing a scalable and flexible code-base, but if written after the fact they are a chore to maintain, and, since a good developer is a lazy developer, they often won’t be. Instead, TDD is all about writing tests that fail first and then writing the code to make them pass.
This workflow is known as the Red-Green-Refactor cycle and it’s the key to building a code-base with good test coverage that grows and is updated alongside the implementation code.
I’ve been looking so long at these pictures of UI
Style guides have had a tough past. Often brought into an organization by designers and developers with a desire to improve collaboration, they easily become neglected by developers and rarely live up to the promise of being an authoritative document of a site’s look and feel.
In fact as a site’s code lives and changes, the style guide becomes outdated and untrustworthy as updates to the code fail to be reflected in the the style guide.
Just like TDD, with Style-guide Driven Development, devs update the style guide as they code. This ensures that the style guide doesn’t go stale due to neglect as it’s no longer a separate concern from the code—it’s how the code gets written.
Can’t test this
TDD works great for testing logic and behaviour, but it’s difficult to write useful tests to cover the way our products look.
There are solutions like Capybara or CasperJS that allow us to write automated UI tests that perform actions and then verify that some DOM node or class-name is present. There are also visual regression tests like PhantomCSS that attempt to find regressions by playing spot-the-difference on screenshots of an entire app.
But these tests can prove to be brittle and often aren’t testing the right things:
- UI tests are brittle as they test assumptions about how the UI should be built; not what it looks like: a change to a class name or rearranging some DOM nodes should not break a UI test!
- Visual regression tests might provide a safety net for catching unintended CSS side-effects, but you can’t work TDD with them as a “green†snapshot can only be taken after the app is looking good.
- Rather than helping to catch regressions that matter, like when text overflows and breaks out of its container, automated UI tests give you a proxy that your UI is rendering correctly:
It can be helpful to write journey tests and acceptance tests for UI, but I’ve seen whole features built where the only time the developer looks at the UI is as it strobes by at seizure-inducing speeds in an automated browser test. Not a great way to see if what’s being built looks right.
All of this is particularly true of React presentational components that are pure functions. When your code just renders the exact same result every time you pass the same props to it, there’s not a lot of logic to test.
Look with your eyes, not with your tests
With Style-guide Driven Development, developers look at the UI as we code it. Instead of a test runner, developers are responsible for visually inspecting what we build and the style guide forms a set of visual expectations for what the UI should look like.
This approach changes the way developers relate to UI as we are actually looking at what we’re building as we build it. At the same time, the trial-and-error, iterative workflow encourages many of the same problem-solving habits that TDD is known for.
Style-guide Driven Development with React Storybook
In React we have a great tool for doing SDD. It’s called React Storybook.
Created by Arunoda Susiripala, Storybook is a tool for writing visual test cases in React. These “visual test cases†are called stories. And each story describes a single state of a React component.
With just a little bit of code, stories make it easy to mount a React components, mock any state, props or other application concerns and render it in isolation in a browser. Thanks to Webpack’s Hot Module Reloading, as you update your story or component code, the story will update automatically in the browser.
This GIF should give you a good idea of what its like:
Storybook makes it easy to iterate on designs while keeping an eye on the rendered output as it updates in the browser.
Write the story before the code
Since we’re working style-guide first that means when it’s time to build a new piece of UI we write out the stories first: we take a look at the design and try to list out all the states our UI will need to represent. Then we write a story for each of those states. These stories form the expectations for the functionality we will build next.
With the stories in place, we now go back and forth from browser to implementation code iterating until we’ve gotten all the stories to render correctly.
Artifact
What we’re left at the end of a Storybook-driven development session are several valuable resources:
- The functioning UI that we can integrate into our app.
- A style guide that we can refer to to see, not only all of the widgets in our app, but all of the possible states or configurations that they support.
- A set of stories that serve as expectations that will have to be met when we re-open this story to make modification to the component.
We can also go back to our storybook and write stories to express new edge cases or breaking points that may be identified by a QA process.
Regressions, I’ve had a few
But what about automation? We write our Redux stores and containers using TDD: we write tests for them in Jest that run automatically whenever we save a file. If we accidentally break something, our automated tests will catch it right away for us.
We want that same coverage for components we develop using SDD. If we make a change to one component that is tested in Storybook, there’s a chance we could break another component somewhere else that depends on it. We want to be able to catch this without having to visually inspect every story.
Given that we’ve already described all the desirable states for our UI and the expected rendered output in our Storybook, wouldn’t it be convenient to take a snapshot of each story’s output and compare it every time any UI code changes?
This is where regression testing using Jest snapshots comes in handy.
And there’s even a Storybook plugin called Storyshots that helps us implement this:
Now as we update existing components, we’ll get instant feedback the moment we break something. It’s this kind of code coverage and automated warning that makes well-tested code so flexible, easy to maintain and worry-free to modify.
Storybook Driven Development
We’ve been doing Style-guide Driven Development using React Storybook at Nulogy for several months. The combination of SDD and Storybook has helped us build great User Experiences for our enterprise users, while delivering better test-coverage for our UI code and a style guide that’s constantly updated as the focus of our development efforts. In fact this combination has proven so powerful that we’ve taken to calling it simply Storybook Driven Development.
If you are working in an Agile team and looking for ways to improve your ability to deliver great design, I hope you give Storybook Driven Development a try.
Video
AllanMaltais and I did a talk about Storybook Driven Development at FITC Spotlight React. Check it out for more on how SDD helps teams collaborate on design and development:
Github sample project
We’ve got a sample project up on GitHub with examples of how we develop using SDD. The repo’s README also has links to the slides from a talk I did about SDD along with other resources.
https://github.com/nulogy/Storybook-Driven-Development
If you’d like to dig deeper please take a look.
