[Bug] manual setup required for addon annotations in portable stories

[vanessayuenn]

This is an issue that has existed forever in portable stories (and will likely be fixed by CSF4).

To make it simple:

Storybook composes annotations that might come explicitly from user's files e.g. .storybook/preview or might come implicitly from addons which are registered in main.js. If an addon has entrypoints such as /preview, these annotations are added automatically by Storybook:

// my-addon/preview
export default = {
  decorators: [withRouter],
};

Additionally, some addons/frameworks can have annotations inside of a /preset entrypoint like so:

// my-framework/preset
export default = {
  previewAnnotations: (entries = []) => [...entries, ...yourEntry],
};

That works because Storybook has an async node layer that starts up first, evaluates main.js, and then provide info to the browser.

Previously in portable stories (let's call it raw portable stories), you would go from running Vitest → Portable stories in a test file. That means there is no in-between async node layer that would allow portable stories to figure things out such as these implicit annotations. That's why we ask users to write a setup file e.g.

// vitest.setup.ts
import { beforeAll } from 'vitest';
import { setProjectAnnotations } from '@storybook/react';
import * as projectAnnotations from './preview';

const project = setProjectAnnotations([projectAnnotations]);

beforeAll(project.beforeAll);

The problem with that is that in order for stories to include the annotations from addons, the user would have to know that such addons have these preset annotations, and then manually add these annotations in the setup file:

// .storybook/vitest.setup.ts
import * as projectAnnotations from './preview';
import * as actionsAnnotations from '@storybook/addon-actions/preview';

const project = setProjectAnnotations([projectAnnotations, actionsAnnotations]);

This becomes a bigger problem when we start implementing solutions that solely rely on these annotations, like the accessibility reporting API. If users don't have addon-a11y annotations in their setup file, there is no way to report anything.

As I mentioned, “raw portable stories” don't have a middle layer. However, now with the Storybook test plugin, we do have such middle layer, which can execute async code and evaluate main.js and their presets. So theoretically we could solve this issue in an automated fashion, and in fact we [used to](storybookjs/vitest-plugin@067b607#diff-563b131f99dc0a01a333cef61fa317c5a61a5e6bf9e617b9016ae1cec6207976R30) create the setup file automatically (not taking these annotations into account), in a very early version of the Storybook vitest plugin version. It was later removed in favor of letting users handle it themselves, and have the power to choose which annotations they want.

💡 Solutions/Action items:

• Revisit automating preset handling as part of the Storybook test plugin.
• Acknowledge that this will forever be a problem in raw portable stories.
• Implement CSF4, which would remove the need to have any set up file altogether.
  • however even with CSF4, annotations from the previewAnnotations property coming from /preset annotations won't be taken into account. Hopefully this won't be that common or needed.