You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+59-19Lines changed: 59 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,27 +20,52 @@ A Jest transformer which enables importing CSS into Jest's `jsdom`.
20
20
21
21
## Description
22
22
23
-
When you want to do Visual Regression Testing in Jest, it is important that the CSS of components is available to the test setup. So far, CSS was not part of tests as it was mocked away by `identity-obj-proxy`.
23
+
When you want to do Visual Regression Testing in Jest, it is important that the CSS of components is available to the test setup. So far, CSS was not part of tests as it was mocked away by using `moduleNameMapper` like a file-mock or `identity-obj-proxy`.
24
24
25
25
`jest-transform-css` is intended to be used in an `jsdom` environment. When any component imports CSS in the test environment, then the loaded CSS will get added to `jsdom` using [`style-inject`](https://github.com/egoist/style-inject) - just like the Webpack CSS loader would do in a production environment. This means the full styles are added to `jsdom`.
26
26
27
27
This doesn't make much sense at first, as `jsdom` is headless (non-visual). However, we can copy the resulting document markup ("the HTML") of `jsdom` and copy it to a [`puppeteer`](https://github.com/googlechrome/puppeteer/) instance. We can let the markup render there and take a screenshot there. The [`jsdom-screenshot`](https://github.com/dferber90/jsdom-screenshot) package does exactly this.
28
28
29
29
Once we obtained a screenshot, we can compare it to the last version of that screenshot we took, and make tests fail in case they did. The [`jest-image-snapshot`](https://github.com/americanexpress/jest-image-snapshot) plugin does that.
30
30
31
-
## Installation
31
+
## Setup
32
+
33
+
### Installation
32
34
33
35
```bash
34
36
yarn add jest-transform-css --dev
35
37
```
36
38
37
-
## Setup
39
+
The old setup of CSS in jest needs to be removed, and the new setup needs to be added next.
40
+
41
+
### Removing module name mapping
42
+
43
+
If your project is using plain CSS imported in the components, then you're likely using a mock file. You can remove that configuration.
If your project is using CSS Modules, then it's likely that `identity-obj-proxy` is configured. It needs to be removed in order for the styles of the `jest-transform-css` to apply.
53
+
54
+
So, remove these lines from `jest.config.js`:
55
+
56
+
```diff
57
+
// in the Jest config
58
+
"moduleNameMapper": {
59
+
- "\\.(s?css|less)$": "identity-obj-proxy"
60
+
},
61
+
```
38
62
39
-
### Setup - adding`transform`
63
+
### Adding`transform`
40
64
41
65
Open `jest.config.js` and modify the `transform`:
42
66
43
67
```
68
+
// in the Jest config
44
69
transform: {
45
70
"^.+\\.js$": "babel-jest",
46
71
"^.+\\.css$": "jest-transform-css"
@@ -55,32 +80,47 @@ transform: {
55
80
>
56
81
> See https://github.com/facebook/jest/tree/master/packages/babel-jest#setup
57
82
58
-
### Setup - removing `identity-obj-proxy`
83
+
### Enabling CSS modules
59
84
60
-
If your project is using CSS Modules, then it's likely that `identity-obj-proxy` is configured. It needs to be removed in order for the styles of the `jest-transform-css` to apply.
85
+
By default, `jest-transform-css` will treat every file it transforms as a regular CSS file.
61
86
62
-
So, remove these lines from `jest.config.js`:
87
+
You need to opt into css-modules mode by specifying it in the configuration. Create a file called `jesttransformcss.config.js` at your project root and add
63
88
64
-
```diff
65
-
"moduleNameMapper": {
66
-
- "\\.(s?css|less)$": "identity-obj-proxy"
67
-
},
89
+
```js
90
+
// jesttransformcss.config.js
91
+
92
+
module.exports= {
93
+
modules:true
94
+
};
95
+
```
96
+
97
+
This will enable CSS module transformation for all CSS files transformed by `jest-transform-css`.
98
+
99
+
If your setup uses both, CSS modules and regular CSS, then you can determine how to load each file individually by specifying a function:
100
+
101
+
```js
102
+
// jesttransformcss.config.js
103
+
104
+
module.exports= {
105
+
modules:filename=>filename.endsWith(".mod.css")
106
+
};
68
107
```
69
108
109
+
This will load all files with `.mod.css` as CSS modules and load all other files as regular CSS. Notice that the function will only be called for whichever regex you provided in the `transform` option of the Jest config.
110
+
70
111
## Further setup
71
112
72
-
There are many ways to setup styles in a project (CSS modules, global styles, external global styles, local global styles, CSS in JS, LESS, SASS just to name a few). How to continue from here on depends on your project.
113
+
There are many ways to set up styles in a project (CSS modules, global styles, external global styles, local global styles, CSS in JS, LESS, SASS just to name a few). How to continue from here depends on your project.
73
114
74
-
### Further Setup - PostCSS
115
+
### PostCSS
75
116
76
117
If your setup is using `PostCSS` then you should add a `postcss.config.js` at the root of your folder.
77
118
78
-
You can apply certain plugins only when `process.env.NODE_ENV === 'test'`. Ensure that valid CSS can be generated. It might be likely that more functionality (transforms) are required to make certain CSS work (like background-images).
79
-
80
-
### Further Setup - css-loader
119
+
You can apply certain plugins only when `process.env.NODE_ENV === 'test'`. Ensure that valid CSS can be generated.
81
120
82
-
If your setup is using `css-loader` only, without PostCSS then you should be fine. When components import CSS in the test environment, then the CSS is transformed through PostCSS's `cssModules` plugin to generate the classnames. It also injects the styles into `jsdom`.
121
+
> `jest-transform-css`is likley not flexible enough yet to support more sophisticated PostCSS configurations. However, we should be able to add this functionality by extending the configuration file. Feel free to open an issue with your setup and we'll try to support it.
83
122
84
-
##Known Limitations
123
+
### css-loader
85
124
86
-
At the moment I struggled to get CSS from `node_modules` to transpile, due to the `jest` configuration. I might just be missing something obvious.
125
+
If your setup is using `css-loader` only, without PostCSS then you should be fine.
126
+
If you have `modules: true` enabled in `css-loader`, you need to also enable it for `jest-transform-css` (see "Enabling CSS modules"). When components import CSS modules in the test environment, then the CSS is transformed through PostCSS's `cssModules` plugin to generate the classnames. It also injects the styles into `jsdom`.
0 commit comments