Storyflow: Using Storybook to Build a Better... Game Engine?

kamranayub profile image Kamran Ayub Originally published at kamranicus.com ・3 min read

Do you use Storybook? Do you use it to test game engines? Didn't think so! But we do for Excalibur.js and I presented how and why we did it. The genesis for the talk came from a workflow I've been using recently that you can implement in your own projects which I call "Storyflow."

Watch the talk

I gave this talk at MN Dev Con on May 4 and again at React Minneapolis on May 21:

What is Storyflow?

The Storybook workflow (ahem, Storyflow) we follow puts Storybook stories at the center of our workflow. The concept is simple in practice: write your unit and functional tests against Storybook instead of importing directly from component files like other workflows.

Storyflow diagram, write tests against Storybook

The "normal" component-based workflow goes like:

  1. Write my component in MyComponent.js
  2. Write my unit test, MyComponent.test.js and import MyComponent
  3. Write a functional test, against my running app, which may test one aspect of MyComponent in use or maybe a few different behaviors/states

But with Storybook the workflow instead flips the script and centers your testing on isolated components through stories:

  1. Write my component in MyComponent.js
  2. Write my Storybook story DefaultState in MyComponent.stories.js and import MyComponent
  3. Write my unit test, MyComponent.test.js and import DefaultState from stories
  4. Write a functional test against DefaultState story in Storybook

It's comes down to a slight shift in thinking. Without Storybook, normally you'd be putting your component into different states within your unit tests. With Storybook, you're already showcasing your component in different states, which makes your unit tests a lot trimmer. Finally, you can add UI testing on top of it to ensure your component works in the browser (without having to manually verify in Storybook).

There are 3 major benefits we've seen from this:

  1. One source of truth for all our tests (stories)
  2. Incentivizes writing more stories
  3. Promotes more testability

One source of truth

Since your unit and functional tests are run against stories, Storybook becomes the source of truth for any tests. Contrast that to developing without stories, where each test could render components in different states and the only way to know would be to examine each test. Having a published Storybook as a static site makes things a lot more discoverable.

Incentivizes writing more stories

Since tests are written against stories, in order to write more tests... you'll need to write more stories. Having more stories means better documentation (even if it's just code!).

Promotes more testability

In order to write a solid Storybook story, it has to run in isolation. That means that you will likely lift up more heavy concerns like data fetching, state management, and other stuff higher and have more atomic reusable components. We actually still write stories against our "container" components but it requires a lot more mocking using Storybook decorators.


If you're curious to see this in action, I have a GitHub Repository set up you can clone and run and I showcase this workflow within the video above.

GitHub logo kamranayub / example-storyflow

Created with CodeSandbox

Storyflow Example

Companion demo to my talk, Using Storybook to Build a Better... Game Engine?

Showcases using Storybook as the basis for unit and functional tests aka "Storyflow" workflow. Uses Storybook, Jest, and Cypress.

Getting Started


  • Yarn 1.x (or replace yarn with npm)
  • Node 12.x
# Install dependencies

# Start Storybook
yarn start

# Run Jest tests
yarn test

# Run Cypress test runner
yarn cypress open

# Run Cypress tests headless
yarn cypress run

You can view a working demo on CodeSandbox using the repository!

Does this sound interesting to you? If you're using Storybook, are you writing tests against it or not right now?

Originally posted on my blog, Kamranicus.com

Posted on by:

kamranayub profile

Kamran Ayub


Kamran Ayub is a technologist, speaker, and Pluralsight author and specializes in building full-stack solutions with a focus on modern web technology and cloud native architecture.


markdown guide