0
# File Management
1

2
Story-to-snapshot file conversion system with configurable naming conventions and directory structures. The `Stories2SnapsConverter` class handles the mapping between story files and their corresponding snapshot files.
3

4
## Capabilities
5

6
### Stories2SnapsConverter Class
7

8
Handles conversion between story files and snapshot files with configurable options.
9

10
```javascript { .api }
11
/**
12
 * Converts between story files and snapshot files
13
 * @param options - Configuration options for file conversion
14
 */
15
class Stories2SnapsConverter {
16
  constructor(options?: Partial<Stories2SnapsConverterOptions>);
17
  
18
  /** Get the snapshot file extension */
19
  getSnapshotExtension(): string;
20
  
21
  /** Convert story file path to snapshot file path */
22
  getStoryshotFile(fileName: string): string;
23
  
24
  /** Get snapshot filename from story context */
25
  getSnapshotFileName(context: { fileName?: string; kind: any }): string | undefined;
26
  
27
  /** Get possible story files from snapshot file path */
28
  getPossibleStoriesFiles(storyshotFile: string): string[];
29
}
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
import { Stories2SnapsConverter } from "@storybook/addon-storyshots";
36

37
// Default configuration
38
const converter = new Stories2SnapsConverter();
39

40
// Custom configuration
41
const customConverter = new Stories2SnapsConverter({
42
  snapshotExtension: ".snap",
43
  snapshotsDirName: "snapshots",
44
  storiesExtensions: [".js", ".jsx", ".ts", ".tsx"]
45
});
46

47
// Use with initStoryshots
48
import initStoryshots from "@storybook/addon-storyshots";
49

50
initStoryshots({
51
  stories2snapsConverter: customConverter
52
});
53
```
54

55
### Configuration Options
56

57
Configure file naming and directory conventions.
58

59
```javascript { .api }
60
interface Stories2SnapsConverterOptions {
61
  /** Supported story file extensions */
62
  storiesExtensions: string[]; // Default: ['.js', '.jsx', '.ts', '.tsx', '.mdx']
63
  
64
  /** Snapshot file extension */
65
  snapshotExtension: string;   // Default: '.storyshot'
66
  
67
  /** Snapshot directory name */
68
  snapshotsDirName: string;    // Default: '__snapshots__'
69
}
70
```
71

72
**Default Options:**
73

74
```javascript
75
const defaultOptions = {
76
  snapshotsDirName: "__snapshots__",
77
  snapshotExtension: ".storyshot", 
78
  storiesExtensions: [".js", ".jsx", ".ts", ".tsx", ".mdx"]
79
};
80
```
81

82
### Get Snapshot Extension
83

84
Returns the configured snapshot file extension.
85

86
```javascript { .api }
87
/**
88
 * Get the snapshot file extension
89
 * @returns Snapshot extension string
90
 */
91
getSnapshotExtension(): string;
92
```
93

94
**Usage Example:**
95

96
```javascript
97
const converter = new Stories2SnapsConverter({
98
  snapshotExtension: ".snap"
99
});
100

101
console.log(converter.getSnapshotExtension()); // ".snap"
102
```
103

104
### Convert Story to Snapshot File
105

106
Converts a story file path to its corresponding snapshot file path.
107

108
```javascript { .api }
109
/**
110
 * Convert story file path to snapshot file path
111
 * @param fileName - Path to the story file
112
 * @returns Path to the corresponding snapshot file
113
 */
114
getStoryshotFile(fileName: string): string;
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
const converter = new Stories2SnapsConverter();
121

122
// Convert relative path
123
const snapshotPath = converter.getStoryshotFile("components/Button.stories.js");
124
// Returns: "components/__snapshots__/Button.storyshot"
125

126
// Convert absolute path
127
const absolutePath = converter.getStoryshotFile("/project/src/Button.stories.tsx");
128
// Returns: "/project/src/__snapshots__/Button.storyshot"
129
```
130

131
### Get Snapshot Filename from Context
132

133
Gets snapshot filename from story context, used for multi-snapshot testing.
134

135
```javascript { .api }
136
/**
137
 * Get snapshot filename from story context
138
 * @param context - Story context containing fileName and kind
139
 * @returns Snapshot filename or undefined if no fileName available
140
 */
141
getSnapshotFileName(context: { fileName?: string; kind: any }): string | undefined;
142
```
143

144
**Usage Examples:**
145

146
```javascript
147
const converter = new Stories2SnapsConverter();
148

149
// With filename in context
150
const context1 = {
151
  fileName: "/project/src/Button.stories.js",
152
  kind: "Button"
153
};
154
const filename1 = converter.getSnapshotFileName(context1);
155
// Returns: "/project/src/__snapshots__/Button.storyshot"
156

157
// Without filename (will log warning)
158
const context2 = {
159
  kind: "Button"
160
};
161
const filename2 = converter.getSnapshotFileName(context2);
162
// Returns: undefined
163
// Logs warning about missing filename
164
```
165

166
### Get Possible Story Files
167

168
Gets possible story file paths from a snapshot file path.
169

170
```javascript { .api }
171
/**
172
 * Get possible story files from snapshot file path
173
 * @param storyshotFile - Path to snapshot file
174
 * @returns Array of possible story file paths
175
 */
176
getPossibleStoriesFiles(storyshotFile: string): string[];
177
```
178

179
**Usage Example:**
180

181
```javascript
182
const converter = new Stories2SnapsConverter();
183

184
const snapshotFile = "/project/src/__snapshots__/Button.storyshot";
185
const possibleStories = converter.getPossibleStoriesFiles(snapshotFile);
186

187
// Returns:
188
// [
189
//   "/project/src/Button.js",
190
//   "/project/src/Button.jsx", 
191
//   "/project/src/Button.ts",
192
//   "/project/src/Button.tsx",
193
//   "/project/src/Button.mdx"
194
// ]
195
```
196

197
### File Structure Examples
198

199
Different configurations produce different file structures:
200

201
**Default Configuration:**
202

203
```
204
src/
205
├── components/
206
│   ├── Button.stories.js
207
│   └── __snapshots__/
208
│       └── Button.storyshot
209
```
210

211
**Custom Configuration:**
212

213
```javascript
214
new Stories2SnapsConverter({
215
  snapshotsDirName: "tests/snapshots",
216
  snapshotExtension: ".snap"
217
});
218
```
219

220
```
221
src/
222
├── components/
223
│   ├── Button.stories.js
224
│   └── tests/
225
│       └── snapshots/
226
│           └── Button.snap
227
```
228

229
### Jest Transform Integration
230

231
For proper filename detection, configure Jest transform:
232

233
```javascript
234
// jest.config.js
235
module.exports = {
236
  transform: {
237
    // Must be before other JS transforms
238
    "^.+\\.stories\\.(js|jsx|ts|tsx)$": "@storybook/addon-storyshots/injectFileName",
239
    "^.+\\.(js|jsx|ts|tsx)$": "babel-jest",
240
  },
241
};
242
```
243

244
The `injectFileName` transform adds filename metadata to story exports:
245

246
```javascript
247
// Automatically injected by transform
248
exports.default.parameters = exports.default.parameters || {};
249
exports.default.parameters.fileName = '/absolute/path/to/Story.stories.js';
250
```
251

252
### Integrity Testing
253

254
File converter supports integrity testing to ensure snapshot-story consistency:
255

256
```javascript
257
import initStoryshots, { multiSnapshotWithOptions } from "@storybook/addon-storyshots";
258

259
initStoryshots({
260
  test: multiSnapshotWithOptions(),
261
  integrityOptions: { 
262
    cwd: __dirname,
263
    ignore: ["**/deprecated/**"]
264
  },
265
  stories2snapsConverter: new Stories2SnapsConverter({
266
    snapshotExtension: ".snap"
267
  })
268
});
269
```
270

271
This verifies that:
272
- All snapshot files have corresponding story files
273
- No orphaned snapshots exist
274
- File naming conventions are consistent