0
# StoryShots
1
2
**⚠️ DEPRECATED**: This addon is deprecated and will not receive further updates. Users should migrate to newer testing solutions as outlined in the [Storybook migration guide](https://storybook.js.org/docs/react/writing-tests/storyshots-migration-guide).
3
4
StoryShots provides automated Jest snapshot testing for Storybook stories across multiple frameworks. It generates snapshot tests from existing stories, enabling visual regression testing and component consistency validation without manual test writing.
5
6
## Package Information
7
8
- **Package Name**: @storybook/addon-storyshots
9
- **Package Type**: npm
10
- **Language**: JavaScript/TypeScript
11
- **Installation**: `npm install @storybook/addon-storyshots --dev`
12
13
## Core Imports
14
15
```javascript
16
import initStoryshots from "@storybook/addon-storyshots";
17
```
18
19
For specific test methods:
20
21
```javascript
22
import initStoryshots, {
23
snapshot,
24
snapshotWithOptions,
25
multiSnapshotWithOptions,
26
renderOnly,
27
renderWithOptions,
28
shallowSnapshot,
29
Stories2SnapsConverter
30
} from "@storybook/addon-storyshots";
31
```
32
33
## Basic Usage
34
35
```javascript
36
// Basic setup - creates snapshots for all stories
37
import initStoryshots from "@storybook/addon-storyshots";
38
39
initStoryshots();
40
```
41
42
```javascript
43
// With configuration options
44
import initStoryshots, { multiSnapshotWithOptions } from "@storybook/addon-storyshots";
45
46
initStoryshots({
47
suite: "Custom Storyshots",
48
storyKindRegex: /^MyComponent$/,
49
test: multiSnapshotWithOptions(),
50
configPath: ".storybook"
51
});
52
```
53
54
## Architecture
55
56
StoryShots is built around several key components:
57
58
- **Initialization Function**: `initStoryshots()` configures and runs snapshot tests for all stories
59
- **Test Methods**: Different strategies for rendering and testing stories (snapshot, shallow, render-only)
60
- **Framework Support**: Auto-detection and custom loaders for React, Angular, Vue, Preact, Svelte, and more
61
- **File Conversion**: Maps story files to snapshot files with configurable naming conventions
62
- **Jest Integration**: Leverages Jest's snapshot testing capabilities with custom serializers
63
64
## Capabilities
65
66
### Core Testing
67
68
Main snapshot testing functionality that automatically converts Storybook stories into Jest snapshot tests.
69
70
```javascript { .api }
71
/**
72
* Initialize snapshot testing for Storybook stories
73
* @param options - Configuration options for snapshot testing
74
*/
75
function initStoryshots(options?: StoryshotsOptions): void;
76
77
interface StoryshotsOptions {
78
asyncJest?: boolean;
79
config?: (options: any) => void;
80
integrityOptions?: GlobOptionsWithFileTypesFalse | false;
81
configPath?: string;
82
suite?: string;
83
storyKindRegex?: RegExp | string;
84
storyNameRegex?: RegExp | string;
85
framework?: SupportedFramework;
86
test?: StoryshotsTestMethod;
87
renderer?: Function;
88
snapshotSerializers?: jest.SnapshotSerializerPlugin[];
89
serializer?: any; // Deprecated
90
stories2snapsConverter?: Stories2SnapsConverter;
91
}
92
```
93
94
[Core Testing](./core-testing.md)
95
96
### Test Methods
97
98
Various testing strategies for different use cases including standard snapshots, shallow rendering, multi-file snapshots, and render-only smoke testing.
99
100
```javascript { .api }
101
/** Standard snapshot test method */
102
declare const snapshot: StoryshotsTestMethod;
103
104
/** Creates snapshot test with custom options */
105
function snapshotWithOptions(options?: SnapshotsWithOptionsArgType): SnapshotsWithOptionsReturnType;
106
107
/** Creates separate snapshot files for each story */
108
function multiSnapshotWithOptions(options?: SnapshotsWithOptionsArgType): StoryshotsTestMethod;
109
110
/** Shallow rendering snapshot test */
111
declare const shallowSnapshot: StoryshotsTestMethod;
112
113
/** Render-only test without snapshots (smoke testing) */
114
declare const renderOnly: StoryshotsTestMethod;
115
116
/** Custom rendering with options */
117
function renderWithOptions(options?: any): StoryshotsTestMethod;
118
119
interface StoryshotsTestMethod {
120
(args: TestMethodOptions): any;
121
beforeAll?: () => void | Promise<void>;
122
beforeEach?: () => void | Promise<void>;
123
afterAll?: () => void | Promise<void>;
124
afterEach?: () => void | Promise<void>;
125
}
126
```
127
128
[Test Methods](./test-methods.md)
129
130
### File Management
131
132
Story-to-snapshot file conversion system with configurable naming conventions and directory structures.
133
134
```javascript { .api }
135
class Stories2SnapsConverter {
136
constructor(options?: Partial<Stories2SnapsConverterOptions>);
137
getSnapshotExtension(): string;
138
getStoryshotFile(fileName: string): string;
139
getSnapshotFileName(context: { fileName?: string; kind: any }): string | undefined;
140
getPossibleStoriesFiles(storyshotFile: string): string[];
141
}
142
143
interface Stories2SnapsConverterOptions {
144
storiesExtensions: string[]; // Default: ['.js', '.jsx', '.ts', '.tsx', '.mdx']
145
snapshotExtension: string; // Default: '.storyshot'
146
snapshotsDirName: string; // Default: '__snapshots__'
147
}
148
```
149
150
[File Management](./file-management.md)
151
152
## Framework Support
153
154
```javascript { .api }
155
type SupportedFramework =
156
| "angular"
157
| "html"
158
| "preact"
159
| "react"
160
| "react-native"
161
| "svelte"
162
| "vue"
163
| "vue3"
164
| "web-components";
165
```
166
167
## Types
168
169
```javascript { .api }
170
interface TestMethodOptions {
171
story: any;
172
context: any;
173
renderTree: RenderTree;
174
renderShallowTree: RenderTree;
175
stories2snapsConverter: Stories2SnapsConverter;
176
snapshotFileName?: string;
177
options: any;
178
done?: () => void;
179
}
180
181
type SnapshotsWithOptionsArgType = Pick<StoryshotsOptions, "renderer" | "serializer"> | Function;
182
183
type SnapshotsWithOptionsReturnType = (
184
options: Pick<TestMethodOptions, "story" | "context" | "renderTree" | "snapshotFileName">
185
) => any;
186
187
type RenderTree = (story: any, context: any, options?: any) => any;
188
```
189
190
## Utilities
191
192
### Jest Transform
193
194
```javascript { .api }
195
// injectFileName.js - Jest transformer for injecting filename into stories
196
module.exports = {
197
process(src: string, fileName: string, config: any, options: any): string;
198
};
199
```
200
201
Used in Jest configuration:
202
203
```javascript
204
// jest.config.js
205
module.exports = {
206
transform: {
207
"^.+\\.stories\\.js$": "@storybook/addon-storyshots/injectFileName",
208
},
209
};
210
```