0
# Storybook Jest Addon
1

2
The Storybook Jest addon displays Jest unit test results directly within Storybook's addon panel. It integrates with Jest test output by consuming JSON test results files and presenting them alongside component stories for enhanced development workflow.
3

4
## Package Information
5

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

11
## Storybook Configuration
12

13
Add the addon to your `.storybook/main.js`:
14

15
```javascript
16
export default {
17
  addons: ['@storybook/addon-jest'],
18
};
19
```
20

21
## Core Imports
22

23
```typescript
24
import { withTests } from "@storybook/addon-jest";
25
```
26

27
For CommonJS:
28

29
```javascript
30
const { withTests } = require("@storybook/addon-jest");
31
```
32

33
## Basic Usage
34

35
```typescript
36
import { withTests } from "@storybook/addon-jest";
37
import results from "../.jest-test-results.json";
38

39
// Story-level configuration
40
export default {
41
  component: MyComponent,
42
  title: "MyComponent",
43
  decorators: [withTests({ results })],
44
};
45

46
export const Default = Template.bind({});
47
Default.parameters = {
48
  jest: ["MyComponent.test.js"],
49
};
50
```
51

52
Global configuration in `.storybook/preview.js`:
53

54
```javascript
55
import { withTests } from "@storybook/addon-jest";
56
import results from "../.jest-test-results.json";
57

58
export const decorators = [
59
  withTests({
60
    results,
61
  }),
62
];
63
```
64

65
## Capabilities
66

67
### Jest Test Integration
68

69
The `withTests` decorator provides the core functionality for integrating Jest test results with Storybook stories.
70

71
```typescript { .api }
72
/**
73
 * Creates a Storybook decorator that attaches Jest test results to stories
74
 * @param userOptions Configuration options for test integration
75
 * @returns Storybook decorator function
76
 */
77
function withTests(userOptions: WithTestsOptions): (...args: any[]) => any;
78

79
interface WithTestsOptions {
80
  /** Jest test results object (required) */
81
  results: any;
82
  /** Test file extension regex pattern (optional, defaults to '((\\.specs?)|(\\.tests?))?(\\.[jt]sx?)?$') */
83
  filesExt?: string;
84
}
85

86
interface JestTestResults {
87
  testResults: Array<{
88
    name: string;
89
    status: string;
90
    startTime?: number;
91
    endTime?: number;
92
    assertionResults: AssertionResult[];
93
  }>;
94
}
95

96
interface AssertionResult {
97
  status: string;
98
  fullName: string;
99
  title: string;
100
  failureMessages: string[];
101
}
102
```
103

104
### Jest Parameter Configuration
105

106
Configure which test files should be displayed for specific stories using the `jest` parameter.
107

108
```typescript { .api }
109
interface JestParameters {
110
  /**
111
   * Jest configuration for stories
112
   * - string: Single test file name
113
   * - string[]: Array of test file names  
114
   * - {disabled: true}: Disable tests for this story
115
   * - undefined: Auto-infer from story file name
116
   */
117
  jest?: string | string[] | { disabled: true };
118
}
119
```
120

121
**Usage in story parameters:**
122

123
```javascript
124
// Single test file
125
Default.parameters = {
126
  jest: "MyComponent.test.js"
127
};
128

129
// Multiple test files
130
Default.parameters = {
131
  jest: ["MyComponent.test.js", "MyOtherComponent.test.js"]
132
};
133

134
// Disable tests
135
Default.parameters = {
136
  jest: { disabled: true }
137
};
138

139
// Auto-infer from story file name (no parameter needed)
140
```
141

142

143
## Configuration Options
144

145
### File Extension Patterns
146

147
Customize which test files are matched using the `filesExt` option:
148

149
```javascript
150
// Default pattern matches multiple extensions
151
const defaultPattern = '((\\.specs?)|(\\.tests?))?(\\.[jt]sx?)?$';
152

153
// Custom pattern for Angular projects
154
export const decorators = [
155
  withTests({
156
    results,
157
    filesExt: '((\\.specs?)|(\\.tests?))?(\\.ts)?$',
158
  }),
159
];
160
```
161

162
### Jest Configuration
163

164
Generate test results JSON file by running Jest with specific flags:
165

166
```bash
167
# Generate test results for the addon
168
jest --json --outputFile=.jest-test-results.json
169

170
# Watch mode for development
171
jest --json --outputFile=.jest-test-results.json --watch
172
```
173

174
Add to `jest.config.js` to prevent infinite loops:
175

176
```javascript
177
module.exports = {
178
  modulePathIgnorePatterns: ['node_modules', '.jest-test-results.json'],
179
};
180
```
181

182
## Types
183

184
```typescript { .api }
185
// Core types for test integration
186
interface WithTestsOptions {
187
  results: any;
188
  filesExt?: string;
189
}
190

191
interface JestParameters {
192
  /**
193
   * Jest configuration
194
   * - string: Single test file name
195
   * - string[]: Array of test file names  
196
   * - {disabled: true}: Disable tests for this story
197
   * - undefined: Auto-infer from story file name
198
   */
199
  jest?: string | string[] | { disabled: true };
200
}
201

202
// Test result interfaces (from Jest output format)
203
interface AssertionResult {
204
  status: string;
205
  fullName: string;
206
  title: string;
207
  failureMessages: string[];
208
}
209

210
interface TestResult {
211
  name: string;
212
  status: string;
213
  startTime?: number;  
214
  endTime?: number;
215
  assertionResults: AssertionResult[];
216
}
217

218
interface Test {
219
  name: string;
220
  result: TestResult;
221
}
222
```
223

224
## Error Handling
225

226
The addon handles various edge cases gracefully:
227

228
- **Missing test files**: Displays placeholder message when configured tests aren't found
229
- **Invalid jest parameter**: Ignores malformed parameters and falls back to auto-inference
230
- **Empty test results**: Shows "No tests found" message in panel
231
- **Failed tests**: Displays expandable failure messages with syntax highlighting
232
- **Network/file issues**: Gracefully handles missing or malformed test result files
233

234
## Framework Support
235

236
The addon supports all Storybook-compatible frameworks except React Native:
237

238
- React
239
- Angular  
240
- Vue
241
- Web Components
242
- HTML
243
- Svelte
244
- And other frameworks supported by Storybook
245

246
For Angular projects, use the custom `filesExt` pattern shown in the configuration section above.