1 | # Storybook addon Jest
|
2 |
|
3 | Brings Jest results in storybook.
|
4 |
|
5 | [Framework Support](https://github.com/storybookjs/storybook/blob/master/ADDONS_SUPPORT.md)
|
6 |
|
7 | [![Storybook Jest Addon Demo](https://raw.githubusercontent.com/storybookjs/storybook/next/addons/jest/docs/storybook-addon-jest.gif)](http://storybooks-official.netlify.com/?selectedKind=Addons%7Cjest&selectedStory=withTests&full=0&addons=1&stories=1&panelRight=0&addonPanel=storybook%2Ftests%2Fpanel)
|
8 |
|
9 | > Checkout the above [Live Storybook](http://storybooks-official.netlify.com/?selectedKind=Addons%7Cjest&selectedStory=withTests&full=0&addons=1&stories=1&panelRight=0&addonPanel=storybook%2Ftests%2Fpanel).
|
10 |
|
11 | ## Getting started
|
12 |
|
13 | ### Install
|
14 |
|
15 | `npm install --save-dev @storybook/addon-jest`
|
16 |
|
17 | or
|
18 |
|
19 | `yarn add --dev @storybook/addon-jest`
|
20 |
|
21 | ### Jest Configuration
|
22 |
|
23 | When running **Jest**, be sure to save the results in a json file:
|
24 |
|
25 | `package.json`
|
26 |
|
27 | ```js
|
28 | "scripts": {
|
29 | "test:generate-output": "jest --json --outputFile=.jest-test-results.json"
|
30 | }
|
31 | ```
|
32 |
|
33 | You may want to add it the result file to `.gitignore`, since it's a generated file:
|
34 |
|
35 | ```
|
36 | .jest-test-results.json
|
37 | ```
|
38 |
|
39 | But much like lockfiles and snapshots checking-in generated files can have certain advantages as well. It's up to you.
|
40 | We recommend to **do** check in the test results file so starting storybook from an clean git clone doesn't require running all tests first,
|
41 | but this can mean you'll experience merge conflicts on this file in the future. (_re-generating this file is very similar to re-generating lockfiles and snapshots_)
|
42 |
|
43 | ## Generating the test results
|
44 |
|
45 | You need to make sure the generated test-results file exists before you start storybook.
|
46 | During development you will likely start jest in watch-mode
|
47 | and so the json file will be re-generated every time code or tests change.
|
48 |
|
49 | ```sh
|
50 | npm run test:generate-output -- --watch
|
51 | ```
|
52 |
|
53 | This change will then be HMR (hot module reloaded) using webpack and displayed by this addon.
|
54 |
|
55 | If you want to pre-run jest automatically during development or a static build,
|
56 | you may need to consider that if your tests fail, the script receives a non-0 exit code and will exit.
|
57 | You could create a `prebuild:storybook` npm script, which will never fail by appending `|| true`:
|
58 |
|
59 | ```json
|
60 | "scripts": {
|
61 | "test:generate-output": "jest --json --outputFile=.jest-test-results.json || true",
|
62 | "test": "jest",
|
63 | "prebuild:storybook": "npm run test:generate-output",
|
64 | "build:storybook": "build-storybook -c .storybook -o build/",
|
65 | "predeploy": "npm run build:storybook",
|
66 | "deploy": "gh-pages -d build/",
|
67 | }
|
68 | ```
|
69 |
|
70 | ### Register
|
71 |
|
72 | within `.storybook/main.js`:
|
73 |
|
74 | ```js
|
75 | module.exports = {
|
76 | addons: ['@storybook/addon-jest'],
|
77 | };
|
78 | ```
|
79 |
|
80 | ## Usage
|
81 |
|
82 | Assuming that you have created test files `MyComponent.test.js` and `MyOtherComponent.test.js`
|
83 |
|
84 | In your `story.js`
|
85 |
|
86 | ```js
|
87 | import results from '../.jest-test-results.json';
|
88 | import { withTests } from '@storybook/addon-jest';
|
89 |
|
90 | export default {
|
91 | title: 'MyComponent',
|
92 | decorators: [withTests({ results })],
|
93 | };
|
94 |
|
95 | export const defaultView = () => <div>Jest results in storybook</div>;
|
96 | defaultView.parameters = {
|
97 | jest: ['MyComponent.test.js', 'MyOtherComponent.test.js'],
|
98 | };
|
99 | ```
|
100 |
|
101 | Or in order to avoid importing `.jest-test-results.json` in each story, add the decorator in your `.storybook/preview.js` and results will display for stories that you have set the `jest` parameter on:
|
102 |
|
103 | ```js
|
104 | import { addDecorator } from '@storybook/react'; // <- or your view layer
|
105 | import { withTests } from '@storybook/addon-jest';
|
106 |
|
107 | import results from '../.jest-test-results.json';
|
108 |
|
109 | addDecorator(
|
110 | withTests({
|
111 | results,
|
112 | })
|
113 | );
|
114 | ```
|
115 |
|
116 | Then in your story:
|
117 |
|
118 | ```js
|
119 | import React from 'react';
|
120 |
|
121 | export default {
|
122 | title: 'MyComponent',
|
123 | };
|
124 |
|
125 | export const defaultView = () => <div>Jest results in storybook</div>;
|
126 | defaultView.parameters = {
|
127 | jest: ['MyComponent.test.js', 'MyOtherComponent.test.js'],
|
128 | };
|
129 | ```
|
130 |
|
131 | ### Disabling
|
132 |
|
133 | You can disable the addon for a single story by setting the `jest` parameter to `{disable: true}`:
|
134 |
|
135 | ```js
|
136 | import React from 'react';
|
137 |
|
138 | export default {
|
139 | title: 'MyComponent',
|
140 | };
|
141 |
|
142 | export const defaultView = () => <div>Jest results in storybook</div>;
|
143 | defaultView.parameters = {
|
144 | jest: { disable: true },
|
145 | };
|
146 | ```
|
147 |
|
148 | ### withTests(options)
|
149 |
|
150 | - **options.results**: OBJECT jest output results. _mandatory_
|
151 | - **filesExt**: STRING test file extension. _optional_. This allows you to write "MyComponent" and not "MyComponent.test.js". It will be used as regex to find your file results. Default value is `((\\.specs?)|(\\.tests?))?(\\.js)?$`. That means it will match: MyComponent.js, MyComponent.test.js, MyComponent.tests.js, MyComponent.spec.js, MyComponent.specs.js...
|
152 |
|
153 | ## Usage with Angular
|
154 |
|
155 | Assuming that you have created test files `my.component.spec.ts` and `my-other.component.spec.ts`
|
156 |
|
157 | Configure Jest with [jest-preset-angular](https://www.npmjs.com/package/jest-preset-angular)
|
158 |
|
159 | In project's `typings.d.ts` add
|
160 |
|
161 | ```ts
|
162 | declare module '*.json' {
|
163 | const value: any;
|
164 | export default value;
|
165 | }
|
166 | ```
|
167 |
|
168 | In your `.storybook/preview.ts`:
|
169 |
|
170 | ```ts
|
171 | import { addDecorator } from '@storybook/angular';
|
172 | import { withTests } from '@storybook/addon-jest';
|
173 |
|
174 | import results from '../.jest-test-results.json';
|
175 |
|
176 | addDecorator(
|
177 | withTests({
|
178 | results,
|
179 | filesExt: '((\\.specs?)|(\\.tests?))?(\\.ts)?$',
|
180 | })
|
181 | );
|
182 | ```
|
183 |
|
184 | ##### Example [here](https://github.com/storybookjs/storybook/tree/master/examples/angular-cli)
|
185 |
|
186 | ## TODO
|
187 |
|
188 | - [ ] Add coverage
|
189 | - [ ] Display nested test better (describe)
|
190 | - [ ] Display the date of the test
|
191 | - [ ] Add unit tests
|
192 | - [ ] Add linting
|
193 | - [ ] Split <TestPanel />
|
194 |
|
195 | ## Contributing
|
196 |
|
197 | All ideas and contributions are welcomed.
|
198 |
|
199 | ## Licence
|
200 |
|
201 | MIT © 2017-present Renaud Tertrais
|