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
```