Skip to content

Commit 01bb6d3

Browse files
mcousmcous
authored
docs(svelte-testing-library): update vitest and jest setup instructions (#1360)
1 parent 09696f9 commit 01bb6d3

File tree

2 files changed

+138
-144
lines changed

2 files changed

+138
-144
lines changed

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

+10-7
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

+128-137
Original file line numberDiff line numberDiff line change
@@ -4,83 +4,87 @@ 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][vitest dom]
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 optionally set up automatic post-test cleanup
41+
and [`@testing-library/jest-dom`][@testing-library/jest-dom] expect matchers.
4442

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

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.
48+
3. Add `vitest.config.js`, or update your existing `vite.config.js`, to process
49+
Svelte files, resolve browser exports during tests, use the [jsdom][] (or
50+
[happy-dom][]) environment, and run your setup file.
5151

52-
```js
52+
```js title="vitest.config.js"
5353
import {defineConfig} from 'vitest/config'
5454
import {svelte} from '@sveltejs/vite-plugin-svelte'
5555

56-
export default defineConfig({
57-
plugins: [svelte({hot: !process.env.VITEST})],
56+
export default defineConfig(({mode}) => ({
57+
plugins: [svelte()],
58+
resolve: {
59+
conditions: mode === 'test' ? ['browser'] : [],
60+
},
5861
test: {
59-
globals: true,
6062
environment: 'jsdom',
63+
setupFiles: ['./vitest-setup.js'],
6164
},
62-
})
65+
}))
6366
```
6467

65-
4. Optionally install [vitest-dom](https://github.com/chaance/vitest-dom) to add
66-
handy assertions to Vitest
67-
68-
4.1 Install `vitest-dom`
68+
:::note
6969

70-
```bash npm2yarn
71-
npm install --save-dev vitest-dom
72-
```
70+
Prepending the `browser` resolve condition to Vite's default conditions may
71+
cause issues if you have a complex Vite configuration or dependencies that
72+
cannot be loaded into Node.js
7373

74-
4.2 import `vitest-dom` at within the vitest setup file (usually
75-
`vitest-setup.(js|ts)`)
74+
See [testing-library/svelte-testing-library#222][] for more information and
75+
alternative configuration options to ensure Svelte's browser bundle is used.
76+
:::
7677

77-
```js
78-
import * as matchers from 'vitest-dom/matchers'
79-
import {expect} from 'vitest'
80-
expect.extend(matchers)
78+
4. Add test scripts to your `package.json` to run the tests with Vitest
8179

82-
// or:
83-
import 'vitest-dom/extend-expect'
80+
```json title="package.json"
81+
{
82+
"scripts": {
83+
"test": "vitest run",
84+
"test:ui": "vitest --ui",
85+
"test:watch": "vitest"
86+
}
87+
}
8488
```
8589

8690
5. Create your component and a test file (checkout the rest of the docs to see
@@ -90,108 +94,95 @@ npm install --save-dev @vitest/ui
9094
npm test
9195
```
9296

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)
97+
[@testing-library/svelte]:
98+
https://github.com/testing-library/svelte-testing-library
99+
[@testing-library/jest-dom]: https://github.com/testing-library/jest-dom
100+
[@sveltejs/vite-plugin-svelte]: https://github.com/sveltejs/vite-plugin-svelte
101+
[jsdom]: https://github.com/jsdom/jsdom
102+
[happy-dom]: https://github.com/capricorn86/happy-dom
103+
[@vitest/ui]: https://vitest.dev/guide/ui.html
104+
[vitest dom]: https://vitest.dev/guide/environment.html
105+
[testing-library/svelte-testing-library#222]:
106+
https://github.com/testing-library/svelte-testing-library/issues/222
115107

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)
108+
## Jest
137109

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

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

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

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

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

154-
```json
155-
"transform": {
156-
"^.+\\.js$": "babel-jest",
157-
"^.+\\.svelte$": "svelte-jester"
158-
},
159-
```
134+
```ts title="jest-setup.js"
135+
import '@testing-library/jest-dom'
136+
```
160137

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
138+
3. Configure Jest to use jsdom, transform Svelte files, and use your setup file
164139

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

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

171-
6.2 Add the following to your Jest configuration in `package.json`
154+
```json title="package.json"
155+
{
156+
"scripts": {
157+
"test": "npx --node-options=\"--experimental-vm-modules\" jest src",
158+
"test:watch": "npx --node-options=\"--experimental-vm-modules\" jest src --watch"
159+
}
160+
}
161+
```
172162

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

179-
7. Create your component + test file (checkout the rest of the docs to see how)
180-
and run it
166+
```bash npm2yarn
167+
npm test
168+
```
181169

182-
```bash npm2yarn
183-
npm test
184-
```
170+
[jest esm mode]: https://jestjs.io/docs/ecmascript-modules
171+
[svelte-jester]: https://github.com/svelteness/svelte-jester
172+
[jest-environment-jsdom]:
173+
https://jestjs.io/docs/configuration#testenvironment-string
185174

186-
### TypeScript
175+
### TypeScript and preprocessors
187176

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

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

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).
184+
[svelte-preprocess]: https://github.com/sveltejs/svelte-preprocess
185+
[svelte-jester typescript]:
186+
https://github.com/svelteness/svelte-jester#typescript
187+
[svelte-jester preprocess]:
188+
https://github.com/svelteness/svelte-jester#preprocess

0 commit comments

Comments
 (0)