Skip to content

Commit c1ed85b

Browse files
mcousmcous
committed
docs(svelte-testing-library): update vitest and jest setup instructions
1 parent 50ad2d2 commit c1ed85b

File tree

2 files changed

+141
-143
lines changed

2 files changed

+141
-143
lines changed

‎docs/svelte-testing-library/intro.mdx‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,10 @@ sidebar_label: Introduction
1212
npm install --save-dev @testing-library/svelte
1313
```
1414

15-
> This library is built on top of
16-
> [`DOM Testing Library`](dom-testing-library/intro.mdx) which is where most of
17-
> the logic behind the queries is.
15+
> This library is built on top of [`dom-testing-library`][dom-testing-library]
16+
> which is where most of the logic behind the queries is.
17+
18+
[dom-testing-library]: ../dom-testing-library/intro.mdx
1819

1920
## The Problem
2021

@@ -27,14 +28,16 @@ The Svelte Testing Library is a very lightweight solution for testing Svelte
2728
components. It provides light utility functions on top of `svelte`, in a way
2829
that encourages better testing practices. Its primary guiding principle is:
2930

30-
> [The more your tests resemble the way your software is used, the more confidence they can give you.](https://twitter.com/kentcdodds/status/977018512689455106)
31+
> [The more your tests resemble the way your software is used, the more
32+
> confidence they can give you.][testing-library-blurb]
3133
3234
So rather than dealing with instances of rendered Svelte components, your tests
33-
will work with actual DOM nodes. See the [Dom
34-
Introduction][dom-solution-explainer] for a more in-depth explanation.
35+
will work with actual DOM nodes. See the
36+
[`dom-testing-library`][dom-solution-explainer] for a more in-depth explanation.
3537

38+
[testing-library-blurb]:
39+
https://twitter.com/kentcdodds/status/977018512689455106
3640
[dom-solution-explainer]: ../dom-testing-library/intro.mdx#this-solution
37-
[react-solution-explainer]: ../react-testing-library/intro.mdx#this-solution
3841

3942
**What this library is not**:
4043

‎docs/svelte-testing-library/setup.mdx‎

Lines changed: 131 additions & 136 deletions
Original file line numberDiff line numberDiff line change
@@ -4,83 +4,89 @@ title: Setup
44
sidebar_label: Setup
55
---
66

7-
We recommend using [Vitest](https://vitest.dev/) but you're free to use the
8-
library with any testing framework and runner you're comfortable with.
7+
We recommend using [Vitest][], but you're free to use the library with any test
8+
runner that's ESM compatible.
99

10-
## Vitest
11-
12-
1. Install Vitest and jsdom
10+
[vitest]: https://vitest.dev/
1311

14-
We're using `jsdom` here as the test environment, but you can use any other
15-
options e.g `happy-dom`.
12+
## Vitest
1613

17-
```bash npm2yarn
18-
npm install --save-dev vitest jsdom
19-
```
14+
1. Add development dependencies
2015

21-
Optionally install `@vitest/ui`, which opens a UI within a browser window to
22-
follow the progress and interact with your tests.
16+
- [`@testing-library/svelte`][@testing-library/svelte]
17+
- [`@testing-library/jest-dom`][@testing-library/jest-dom] (Optional, but
18+
highly recommended)
19+
- [`@sveltejs/vite-plugin-svelte`][@sveltejs/vite-plugin-svelte]
20+
- [`vitest`][vitest]
21+
- [`jsdom`][jsdom], [`happy-dom`][happy-dom], or other [Vitest DOM
22+
environment][]
2323

24-
```bash npm2yarn
25-
npm install --save-dev @vitest/ui
26-
```
24+
```bash npm2yarn
25+
npm install --save-dev \
26+
@testing-library/svelte \
27+
@testing-library/jest-dom \
28+
@sveltejs/vite-plugin-svelte \
29+
vitest \
30+
jsdom
31+
```
2732

28-
1. Add the test scipts to your `package.json` to run the tests with Vitest
33+
Optionally install [`@vitest/ui`][@vitest/ui], which opens a UI within a
34+
browser window to follow the progress and interact with your tests.
2935

30-
```json
31-
{
32-
"scripts": {
33-
"test": "vitest run",
34-
"test:ui": "vitest --ui",
35-
"test:watch": "vitest"
36-
}
37-
}
36+
```bash npm2yarn
37+
npm install --save-dev @vitest/ui
3838
```
3939

40-
2. To compile the Svelte components before using them in Vitest, you need to
41-
install
42-
[@sveltejs/vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte)
43-
and Vite
40+
2. Add a `vitest-setup.js` file to configure cleanup and
41+
[`@testing-library/jest-dom`][@testing-library/jest-dom], if using.
4442

45-
```bash npm2yarn
46-
npm install --save-dev @sveltejs/vite-plugin-svelte vite
43+
```ts
44+
// vitest-setup.js
45+
import '@testing-library/svelte/vitest'
46+
import '@testing-library/jest-dom/vitest'
4747
```
4848

49-
3. Add a `vitest.config.ts` configuration file to the root of your project. Add
50-
`globals: true` so `cleanup()` runs after each test.
49+
3. Add `vitest.config.js`, or update your existing `vite.config.js`, to process
50+
Svelte files, resolve browser exports during tests, use the [jsdom][] (or
51+
[happy-dom][]) environment, and run your setup file.
5152

5253
```js
54+
// vitest.config.js
5355
import {defineConfig} from 'vitest/config'
5456
import {svelte} from '@sveltejs/vite-plugin-svelte'
5557

56-
export default defineConfig({
57-
plugins: [svelte({hot: !process.env.VITEST})],
58+
export default defineConfig(({mode}) => ({
59+
plugins: [svelte()],
60+
resolve: {
61+
conditions: mode === 'test' ? ['browser'] : [],
62+
},
5863
test: {
59-
globals: true,
6064
environment: 'jsdom',
65+
setupFiles: ['./vitest-setup.js'],
6166
},
62-
})
67+
}))
6368
```
6469

65-
4. Optionally install [vitest-dom](https://github.com/chaance/vitest-dom) to add
66-
handy assertions to Vitest
70+
:::note
6771

68-
4.1 Install `vitest-dom`
72+
Prepending the `browser` resolve condition to Vite's default conditions may
73+
cause issues if you have a complex Vite configuration or dependencies that
74+
cannot be loaded into Node.js
6975

70-
```bash npm2yarn
71-
npm install --save-dev vitest-dom
72-
```
76+
See [testing-library/svelte-testing-library#222][] for more information and
77+
alternative configuration options to ensure Svelte's browser bundle is used.
78+
:::
7379

74-
4.2 import `vitest-dom` at within the vitest setup file (usually
75-
`vitest-setup.(js|ts)`)
80+
4. Add test scipts to your `package.json` to run the tests with Vitest
7681

77-
```js
78-
import * as matchers from 'vitest-dom/matchers'
79-
import {expect} from 'vitest'
80-
expect.extend(matchers)
81-
82-
// or:
83-
import 'vitest-dom/extend-expect'
82+
```json
83+
{
84+
"scripts": {
85+
"test": "vitest run",
86+
"test:ui": "vitest --ui",
87+
"test:watch": "vitest"
88+
}
89+
}
8490
```
8591

8692
5. Create your component and a test file (checkout the rest of the docs to see
@@ -90,108 +96,97 @@ npm install --save-dev @vitest/ui
9096
npm test
9197
```
9298

93-
## Jest
94-
95-
1. Install Jest & jest-environment-jsdom
96-
97-
```bash npm2yarn
98-
npm install --save-dev jest jest-environment-jsdom
99-
```
100-
101-
2. Add the following to your `package.json`
102-
103-
```json
104-
{
105-
"scripts": {
106-
"test": "jest src",
107-
"test:watch": "jest src --watch"
108-
}
109-
}
110-
```
111-
112-
3. You'll need to compile the Svelte components before using them in Jest, so
113-
we need to install
114-
[svelte-jester](https://github.com/mihar-22/svelte-jester)
99+
[@testing-library/svelte]:
100+
https://github.com/testing-library/svelte-testing-library
101+
[@testing-library/jest-dom]: https://github.com/testing-library/jest-dom
102+
[@sveltejs/vite-plugin-svelte]: https://github.com/sveltejs/vite-plugin-svelte
103+
[jsdom]: https://github.com/jsdom/jsdom
104+
[happy-dom]: https://github.com/capricorn86/happy-dom
105+
[@vitest/ui]: https://vitest.dev/guide/ui.html
106+
[vitest dom environment]: https://vitest.dev/guide/environment.html
107+
[testing-library/svelte-testing-library#222]:
108+
https://github.com/testing-library/svelte-testing-library/issues/222
115109

116-
```bash npm2yarn
117-
npm install --save-dev svelte-jester
118-
```
119-
120-
4. Add the following Jest configuration to your `package.json`
121-
122-
```json
123-
{
124-
"jest": {
125-
"transform": {
126-
"^.+\\.svelte$": "svelte-jester"
127-
},
128-
"moduleFileExtensions": ["js", "svelte"],
129-
"testEnvironment": "jsdom"
130-
}
131-
}
132-
```
133-
134-
5. If you are using ES6 modules in your project you have to add Jest's babel
135-
transform setting (it is set by default, but since we are overriding the
136-
transform config, we have to add it explicitly)
110+
## Jest
137111

138-
5.1 Install `babel-jest`
112+
[`@testing-library/svelte`][@testing-library/svelte] is ESM-only, which means
113+
you must use Jest in [ESM mode][jest esm mode].
139114

140-
```bash npm2yarn
141-
npm install --save-dev babel-jest
142-
```
115+
1. Add development dependencies
143116

144-
5.2. Add a basic `.babelrc` configuration
117+
- [`@testing-library/svelte`][@testing-library/svelte]
118+
- [`@testing-library/jest-dom`][@testing-library/jest-dom] (Optional, but
119+
highly recommended)
120+
- [`svelte-jester`][svelte-jester]
121+
- [`jest`][vitest]
122+
- [`jest-environment-jsdom`][jest-environment-jsdom]
145123

146-
```json
147-
{
148-
"presets": [["@babel/preset-env", {"targets": {"node": "current"}}]]
149-
}
150-
```
124+
```bash npm2yarn
125+
npm install --save-dev \
126+
@testing-library/svelte \
127+
@testing-library/jest-dom \
128+
svelte-jester \
129+
jest \
130+
jest-environment-jsdom
131+
```
151132

152-
5.3. Update the Jest transform configuration
133+
2. Add a `jest-setup.js` file to configure
134+
[`@testing-library/jest-dom`][@testing-library/jest-dom], if using.
153135

154-
```json
155-
"transform": {
156-
"^.+\\.js$": "babel-jest",
157-
"^.+\\.svelte$": "svelte-jester"
158-
},
159-
```
136+
```ts
137+
// jest-setup.js
138+
import '@testing-library/jest-dom'
139+
```
160140

161-
6. This is optional but it is recommended, you can install
162-
[jest-dom](https://github.com/testing-library/jest-dom) to add handy
163-
assertions to Jest
141+
3. Configure Jest to use jsdom, transform Svelte files, and use your setup file
164142

165-
6.1 Install `jest-dom`
143+
```js
144+
// jest.config.js
145+
module.exports = {
146+
"transform": {
147+
"^.+\\.svelte$": "svelte-jester"
148+
},
149+
"moduleFileExtensions": ["js", "svelte"],
150+
"extensionsToTreatAsEsm": ["svelte"]
151+
"testEnvironment": "jsdom",
152+
"setupFilesAfterEnv": ["<rootDir>/jest-setup.js"]
153+
}
154+
```
166155

167-
```bash npm2yarn
168-
npm install --save-dev @testing-library/jest-dom
169-
```
156+
4. Add the following to your `package.json`
170157

171-
6.2 Add the following to your Jest configuration in `package.json`
158+
```json
159+
{
160+
"scripts": {
161+
"test": "npx --node-options=\"--experimental-vm-modules\" jest src",
162+
"test:watch": "npx --node-options=\"--experimental-vm-modules\" jest src --watch"
163+
}
164+
}
165+
```
172166

173-
```json
174-
{
175-
"setupFilesAfterEnv": ["@testing-library/jest-dom/extend-expect"]
176-
}
177-
```
167+
5. Create your component + test file (checkout the rest of the docs to see how)
168+
and run it
178169

179-
7. Create your component + test file (checkout the rest of the docs to see how)
180-
and run it
170+
```bash npm2yarn
171+
npm test
172+
```
181173

182-
```bash npm2yarn
183-
npm test
184-
```
174+
[jest esm mode]: https://jestjs.io/docs/ecmascript-modules
175+
[svelte-jester]: https://github.com/svelteness/svelte-jester
176+
[jest-environment-jsdom]:
177+
https://jestjs.io/docs/configuration#testenvironment-string
185178

186-
### TypeScript
179+
### TypeScript and preprocessors
187180

188181
To use TypeScript with Jest, you'll need to install and configure
189182
`svelte-preprocess` and `ts-jest`. For full instructions, see the
190-
[`svelte-jester`](https://github.com/mihar-22/svelte-jester#typescript) docs.
183+
[`svelte-jester` docs][svelte-jester typescript].
191184

192-
### Preprocessors
185+
If you'd like include any other [Svelte preprocessors][svelte-preprocess], see
186+
the [`svelte-jester` docs][svelte-jester preprocess].
193187

194-
If you'd like to also include any
195-
[Svelte preprocessors](https://github.com/sveltejs/svelte-preprocess) then
196-
simply follow the instructions over at
197-
[svelte-jester](https://github.com/mihar-22/svelte-jester#babel).
188+
[svelte-preprocess]: https://github.com/sveltejs/svelte-preprocess
189+
[svelte-jester typescript]:
190+
https://github.com/svelteness/svelte-jester#typescript
191+
[svelte-jester preprocess]:
192+
https://github.com/svelteness/svelte-jester#preprocess

0 commit comments

Comments
 (0)