@storybook-addon-faker/babel

Storybook addon faker

A storybook addon enabling faker usage in story (CSF) objects with magic seeding powers.

Use faker methods to define randomized and realistic mock data for your stories. Each time you load a story while developing, faker will use a new unique value. This is wonderful for developing robust UI components as static mock data tends to fall short of the dynamic world of real data your components will receive in the wild.

But why do I need an addon? I can just use faker methods directly.

Exactly, and using this addon doesn't change the way you use faker. Just call faker methods as usual when defining stories. But, when you render your stories in a visual testing context (e.g. chromatic) calls to faker will be automatically seeded, per story, ensuring that the data used to render your story is consistent across builds. This ensures the only pixel diffs are due to your code and not varying test data. You get the best of both worlds.

Dynamic while developing, static while testing!

Prerequisites

This project assumes you are using storybook already. It also assumes you are defining stories with CSF v3 story object format. Finally it assumes you have @faker-js/faker installed.

Table of contents

• Storybook addon faker
  • Prerequisites
  • Table of contents
  • Getting Started
  • Installation
  • Usage
    • Using via the addon
      • @storybook-addon-faker/babel
    • Using via the node API
      • seedStory
        • GetStory()
        • Options
      • Examples
  • Contributing
  • Credits
  • Versioning
  • Authors
  • License

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the addon, run:

$ npm install @storybook-addon-faker/addon -D

Or if you prefer using Yarn:

$ yarn add @storybook-addon-faker/addon -D

Usage

This package is shipped with storybook addon and companion babel plugin. You can use the addon for batteries included setup, or import the library yourself and add per story.

Using via the addon

Add @storybook-addon-faker/addon to you storybook addons in `.storybook/main.(js|ts)

module.exports = {
  ... // storybook config
  addons: ["@storybook-addon-faker/addon"],
};

That's it. This will automatically include the babel plugin to your storybook webpack configuration, wrapping all story objects in the seedStory wrapper giving you all the benefits of this addon with zero config.

Define some stories using faker anywhere in the story object definition.

export const Default = {
  args: {
    loading: faker.datatype.boolean(),
  },
};

When you run this story locally, the value of Default.args.loading will randomly switch between true and false each time the story module is loaded. If you refresh the page you will see it switch back and forth. But, if you add

?chromatic=true to the URL of the storybook browser window, the value will lock into either true or false and will always return the same value.

@storybook-addon-faker/babel

TBD: add docs for babel plugin

Using via the node API

seedStory

import {StoryObj} from "@storybook/react";

type GetStory = () => StoryObj;

interface Options {
  faker: Faker;
  seed: number;
}

function seedStory(GetStory, Options);

seedStory accepts two argumentss, a function callback GetStory and a configuration object Options.

GetStory()

Seed story accepts a callback function to define your StoryObj and wrap calls to faker in a seed. This allows each story to have a unique set of seeded values returned from all calls to faker when the seed is enabled.

If you have a story object defined:

export const Default = {
  args: {
    loading: faker.datatype.boolean(),
  },
};

Then you would wrap this story with seedStory like:

export const seedStory(() => ({
  args: {
    loading: faker.datatype.boolean(),
  },
}), {
  faker: myFaker,
  seed: 123,
});

Now, seedStory can delay defining your story object until after the seed has been set. This is the magic.

Options

options.faker

Type	Default value
Faker	undefindd

The faker instance to set a seed on. This should be the same faker instance you are using to define the values for your story.

Example:

import {faker} from '@faker-js/locales/de';
import {Card} from './Card';

export default {component: Card} as Meta<typeof Card>;

export const Default = seedStory(() => ({
  args: {
    loading: faker.datatype.boolean(),
  },
}), {
  faker,
  seed: 123
});

options.seed

Type	Default value	Description
number	0	The seed to set on faker

This is the seed to set on faker before rendering your story.

Example:

import {faker} from '@faker-js/locales/de';
import {Card} from './Card';

export default {component: Card} as Meta<typeof Card>;

export const Default = seedStory(() => ({
  args: {
    loading: faker.datatype.boolean(),
  },
}), {
  faker,
  // Set `faker.seed(123) before calling the internal callback to render `<Card />`
  seed: 123
});

Examples

See the examples folder for specific example implementations

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Add your changes: git add .
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin my-new-feature
6. Submit a pull request 😎

Credits

TBD

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Kevin Mind - Initial work - KevinMind

See also the list of contributors who participated in this project.

License

MIT License © Andrea SonnY