0
# Storybook Testing React
1

2
Storybook Testing React provides testing utilities that allow you to reuse your existing Storybook stories directly in unit tests. It enables developers to leverage their story scenarios as test cases, automatically applying all decorators, parameters, and global configurations from story-level, meta-level, and global-level contexts.
3

4
## Package Information
5

6
- **Package Name**: @storybook/testing-react
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @storybook/testing-react`
10

11
## Core Imports
12

13
```typescript
14
import { composeStory, composeStories, setProjectAnnotations } from "@storybook/testing-react";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { composeStory, composeStories, setProjectAnnotations } = require("@storybook/testing-react");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { render, screen } from "@testing-library/react";
27
import { composeStories } from "@storybook/testing-react";
28
import * as stories from "./Button.stories";
29

30
// Compose all stories from the stories file
31
const { Primary, Secondary } = composeStories(stories);
32

33
test("renders primary button with default args", () => {
34
  render(<Primary />);
35
  const buttonElement = screen.getByRole("button");
36
  expect(buttonElement).toBeInTheDocument();
37
});
38

39
test("renders primary button with custom props", () => {
40
  render(<Primary onClick={jest.fn()}>Custom Text</Primary>);
41
  const buttonElement = screen.getByText("Custom Text");
42
  expect(buttonElement).toBeInTheDocument();
43
});
44
```
45

46
## Architecture
47

48
Storybook Testing React is built around several key concepts:
49

50
- **Story Composition**: Combines story definitions with meta configurations and global settings
51
- **Decorator Application**: Automatically applies decorators from story, meta, and global levels
52
- **Type Preservation**: Maintains TypeScript type safety while making story props optional
53
- **Play Function Integration**: Provides access to story play functions for interaction testing
54
- **CSF Compatibility**: Supports Component Story Format v3 with object-style and function-style stories
55

56
## Capabilities
57

58
### Story Composition
59

60
Core functionality for converting individual stories or entire story files into testable React components with all configurations applied.
61

62
```typescript { .api }
63
function composeStory<GenericArgs extends Args>(
64
  story: TestingStory<GenericArgs>,
65
  meta: ComponentAnnotations<ReactRenderer>,
66
  globalConfig?: ProjectAnnotations<ReactRenderer>
67
): ComposedStory<GenericArgs>;
68

69
function composeStories<TModule extends StoryFile>(
70
  storiesImport: TModule,
71
  globalConfig?: ProjectAnnotations<ReactRenderer>
72
): StoriesWithPartialProps<TModule>;
73
```
74

75
[Story Composition](./composition.md)
76

77
### Global Configuration
78

79
Setup functions for applying global Storybook configuration (decorators, parameters, etc.) to all composed stories.
80

81
```typescript { .api }
82
function setProjectAnnotations(
83
  projectAnnotations: ProjectAnnotations<ReactRenderer> | ProjectAnnotations<ReactRenderer>[]
84
): void;
85

86
function setGlobalConfig(
87
  projectAnnotations: ProjectAnnotations<ReactRenderer> | ProjectAnnotations<ReactRenderer>[]
88
): void;
89
```
90

91
Note: `setGlobalConfig` is deprecated - use `setProjectAnnotations` instead.
92

93
[Global Configuration](./composition.md#global-configuration)
94

95
## Types
96

97
### Core Types
98

99
```typescript { .api }
100
type TestingStory<TArgs = Args> = StoryAnnotations<ReactRenderer, TArgs>;
101

102
type StoryFile = Store_CSFExports<ReactRenderer, any>;
103

104
type StoriesWithPartialProps<T> = {
105
  [K in keyof T]: T[K] extends StoryAnnotations<ReactRenderer, infer P> 
106
    ? ComposedStory<Partial<P>> 
107
    : number;
108
};
109

110
type ComposedStory<TArgs = Args> = {
111
  /** Render the story component with optional prop overrides */
112
  (extraArgs?: Partial<TArgs>): JSX.Element;
113
  /** Story name from storyName property or function name */
114
  storyName?: string;
115
  /** Combined args from meta and story levels */
116
  args: TArgs;
117
  /** Play function for interaction testing */
118
  play: (context: TestingStoryPlayContext<TArgs>) => Promise<void>;
119
  /** Combined decorators from all levels */
120
  decorators: DecoratorFunction<ReactRenderer, TArgs>[];
121
  /** Combined parameters from all levels */
122
  parameters: Parameters;
123
};
124

125
type TestingStoryPlayContext<TArgs = Args> = Partial<PlayFunctionContext<ReactRenderer, TArgs>> & {
126
  canvasElement: HTMLElement;
127
};
128
```
129

130
### Storybook Integration Types
131

132
These types are from the Storybook ecosystem and used throughout the API:
133

134
```typescript { .api }
135
// From @storybook/types
136
type Args = Record<string, any>;
137
type ComponentAnnotations<TRenderer> = Meta<TRenderer>;
138
type ProjectAnnotations<TRenderer> = Parameters & GlobalTypes & Decorators;
139
type DecoratorFunction<TRenderer, TArgs> = (story: StoryFn<TArgs>, context: StoryContext<TRenderer, TArgs>) => any;
140

141
// From @storybook/react  
142
type ReactRenderer = {
143
  component: ComponentType<any>;
144
  storyResult: ReactElement<any, any>;
145
};
146
```