storybook-addon-performance 🚀

A storybook addon to help better understand and debug performance for React components

🚧 This addon is experimental and a work in progress. We are not on stable versions yet 🚧

Highlights 🌟

Zero config (except for interactions): Generate performance information relating to server-side rendering and client-side mounting without any configuration
Pin results: You can run some tasks, pin the result, make some changes, rerun the tasks and see what changed
Interactions: Add your own custom user interactions to run as a parameter to your story. This lets you time how long interactions take. The API for this is super flexible and powerful!
Control: Run all tasks for an overview, or run individual tasks to drill down on specific problems
Marked: All tasks are marked with the User Timing API to allow for easy debugging of individual tasks in your browser's performance profiler

Installation

Install storybook-addon-performance

# yarn
yarn add storybook-addon-performance --dev

# npm
npm install storybook-addon-performance --save-dev

module.exports = {
  addons: ['storybook-addon-performance/register'],
};

Add the decorator

You can either add the decorator globally to every story in .storybook/preview.js (recommended)

import { addDecorator } from '@storybook/react';
import { withPerformance } from 'storybook-addon-performance';

addDecorator(withPerformance);

Or you can add it to individual stories:

Using Component Story Format (CSF)

import MyComponent from './MyComponent';
import { withPerformance } from 'storybook-addon-performance';

export default {
  title: 'MyComponent',
  component: MyComponent,
  decorators: [withPerformance],
};

Using StoriesOf API

import MyComponent from './MyComponent';
import { withPerformance } from 'storybook-addon-performance';

storiesOf('MyComponent', module)
  .addDecorator(withPerformance)
  .add('MyComponent', () => <MyComponent />);

Usage: Interactions

Interaction tasks are a task type that can be defined and run on a story-by-story basis. They are useful for timing the interactive performance of your components.

To define your interaction tasks, first create an array of objects, each containing the name and description (optional) of the task, and a run function that performs whatever tasks you'd like to measure:

import { InteractionTaskArgs, PublicInteractionTask } from 'storybook-addon-performance';
import { findByText, fireEvent } from '@testing-library/dom';

// ...

const interactionTasks: PublicInteractionTask[] = [
  {
    name: 'Display dropdown',
    description: 'Open the dropdown and wait for Option 5 to load',
    run: async ({ container }: InteractionTaskArgs): Promise<void> => {
      const element: HTMLElement | null = container.querySelector('.addon__dropdown-indicator');
      invariant(element);
      fireEvent.mouseDown(element);
      await findByText(container, 'Option 5', undefined, { timeout: 20000 });
    },
  },
];

The run function in each task object takes two arguments:

container: an HTMLElement container that contains a rendered instance of the story component
controls: contains an async timing function that can be optionally called to specify when to start and finish measurements; otherwise the time taken to complete the entire run function is measured. Useful when a task involves some set-up work.

To use, wrap the operations in question with controls.time as shown below:
```
run: async ({ container }: InteractionTaskArgs): Promise<void> => {
  // setup
  await controls.time(async () => {
    // interaction task you'd like to measure
  });
};
```

Note that you can use whatever libraries you'd like to perform these interaction tests – the example above uses @testing-library/dom to open the select in the example and wait for a specific item.

You can then include the array of interaction tasks inside the performance parameters of your story, with the key interactions:

select.story = {
  name: 'React select',
  parameters: {
    performance: {
      interactions: interactionTasks,
    },
  },
};

Supplied types

As seen above, the plugin exports two type definitions to assist with creating your own interaction tasks:

PublicInteractionTask: defines the object structure for an interaction task; pass an array of these tasks as a parameter to storybook, as shown above.
InteractionTaskArgs: the arguments for an interaction task's run function

Local addon development

# Start the typescript watcher and a local storybook:
yarn dev

# Start just the typescript watcher
# This is needed as storybook does not compile addons
yarn typescript:watch

# Start the local storybook
yarn storybook:dev

Thanks

Made with ❤️ by your friends at Atlassian

Alex Reardon @alexandereardon
Andrew Campbell @andrewcampb_ll
Daniel Del Core @danieldelcore

dmngu9 / storybook-addon-performance Goto Github PK