Skip to content

Commit

Permalink
docs(svelte-testing-library): update vitest and jest setup instructio…
Browse files Browse the repository at this point in the history 
…ns (#1360)
  • Loading branch information
@mcous
mcous committed Feb 1, 2024
1 parent 09696f9 commit 01bb6d3
Show file tree
Hide file tree
Showing 2 changed files with 138 additions and 144 deletions.
17 changes: 10 additions & 7 deletions docs/svelte-testing-library/intro.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,10 @@ sidebar_label: Introduction
npm install --save-dev @testing-library/svelte
```

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

## The Problem

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

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

[testing-library-blurb]:
https://twitter.com/kentcdodds/status/977018512689455106
[dom-solution-explainer]: ../dom-testing-library/intro.mdx#this-solution
[react-solution-explainer]: ../react-testing-library/intro.mdx#this-solution

**What this library is not**:

Expand Down
265 changes: 128 additions & 137 deletions docs/svelte-testing-library/setup.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,83 +4,87 @@ title: Setup
sidebar_label: Setup
---

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

## Vitest

1. Install Vitest and jsdom
[vitest]: https://vitest.dev/

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

```bash npm2yarn
npm install --save-dev vitest jsdom
```
1. Add development dependencies

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

```bash npm2yarn
npm install --save-dev @vitest/ui
```
```bash npm2yarn
npm install --save-dev \
@testing-library/svelte \
@testing-library/jest-dom \
@sveltejs/vite-plugin-svelte \
vitest \
jsdom
```

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

```json
{
"scripts": {
"test": "vitest run",
"test:ui": "vitest --ui",
"test:watch": "vitest"
}
}
```bash npm2yarn
npm install --save-dev @vitest/ui
```

2. To compile the Svelte components before using them in Vitest, you need to
install
[@sveltejs/vite-plugin-svelte](https://github.com/sveltejs/vite-plugin-svelte)
and Vite
2. Add a `vitest-setup.js` file to optionally set up automatic post-test cleanup
and [`@testing-library/jest-dom`][@testing-library/jest-dom] expect matchers.

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

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

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

export default defineConfig({
plugins: [svelte({hot: !process.env.VITEST})],
export default defineConfig(({mode}) => ({
plugins: [svelte()],
resolve: {
conditions: mode === 'test' ? ['browser'] : [],
},
test: {
globals: true,
environment: 'jsdom',
setupFiles: ['./vitest-setup.js'],
},
})
}))
```

4. Optionally install [vitest-dom](https://github.com/chaance/vitest-dom) to add
handy assertions to Vitest

4.1 Install `vitest-dom`
:::note

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

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

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

// or:
import 'vitest-dom/extend-expect'
```json title="package.json"
{
"scripts": {
"test": "vitest run",
"test:ui": "vitest --ui",
"test:watch": "vitest"
}
}
```

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

## Jest

1. Install Jest & jest-environment-jsdom

```bash npm2yarn
npm install --save-dev jest jest-environment-jsdom
```

2. Add the following to your `package.json`

```json
{
"scripts": {
"test": "jest src",
"test:watch": "jest src --watch"
}
}
```

3. You'll need to compile the Svelte components before using them in Jest, so
we need to install
[svelte-jester](https://github.com/mihar-22/svelte-jester)
[@testing-library/svelte]:
https://github.com/testing-library/svelte-testing-library
[@testing-library/jest-dom]: https://github.com/testing-library/jest-dom
[@sveltejs/vite-plugin-svelte]: https://github.com/sveltejs/vite-plugin-svelte
[jsdom]: https://github.com/jsdom/jsdom
[happy-dom]: https://github.com/capricorn86/happy-dom
[@vitest/ui]: https://vitest.dev/guide/ui.html
[vitest dom]: https://vitest.dev/guide/environment.html
[testing-library/svelte-testing-library#222]:
https://github.com/testing-library/svelte-testing-library/issues/222

```bash npm2yarn
npm install --save-dev svelte-jester
```

4. Add the following Jest configuration to your `package.json`

```json
{
"jest": {
"transform": {
"^.+\\.svelte$": "svelte-jester"
},
"moduleFileExtensions": ["js", "svelte"],
"testEnvironment": "jsdom"
}
}
```

5. If you are using ES6 modules in your project you have to add Jest's babel
transform setting (it is set by default, but since we are overriding the
transform config, we have to add it explicitly)
## Jest

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

```bash npm2yarn
npm install --save-dev babel-jest
```
1. Add development dependencies

5.2. Add a basic `.babelrc` configuration
- [`@testing-library/svelte`][@testing-library/svelte]
- [`@testing-library/jest-dom`][@testing-library/jest-dom] (Optional, but
highly recommended)
- [`svelte-jester`][svelte-jester]
- [`jest`][vitest]
- [`jest-environment-jsdom`][jest-environment-jsdom]

```json
{
"presets": [["@babel/preset-env", {"targets": {"node": "current"}}]]
}
```
```bash npm2yarn
npm install --save-dev \
@testing-library/svelte \
@testing-library/jest-dom \
svelte-jester \
jest \
jest-environment-jsdom
```

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

```json
"transform": {
"^.+\\.js$": "babel-jest",
"^.+\\.svelte$": "svelte-jester"
},
```
```ts title="jest-setup.js"
import '@testing-library/jest-dom'
```

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

6.1 Install `jest-dom`
```js title="jest.config.js"
module.exports = {
"transform": {
"^.+\\.svelte$": "svelte-jester"
},
"moduleFileExtensions": ["js", "svelte"],
"extensionsToTreatAsEsm": ["svelte"]
"testEnvironment": "jsdom",
"setupFilesAfterEnv": ["<rootDir>/jest-setup.js"]
}
```

```bash npm2yarn
npm install --save-dev @testing-library/jest-dom
```
4. Add the following to your `package.json`

6.2 Add the following to your Jest configuration in `package.json`
```json title="package.json"
{
"scripts": {
"test": "npx --node-options=\"--experimental-vm-modules\" jest src",
"test:watch": "npx --node-options=\"--experimental-vm-modules\" jest src --watch"
}
}
```

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

7. Create your component + test file (checkout the rest of the docs to see how)
and run it
```bash npm2yarn
npm test
```

```bash npm2yarn
npm test
```
[jest esm mode]: https://jestjs.io/docs/ecmascript-modules
[svelte-jester]: https://github.com/svelteness/svelte-jester
[jest-environment-jsdom]:
https://jestjs.io/docs/configuration#testenvironment-string

### TypeScript
### TypeScript and preprocessors

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

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

If you'd like to also include any
[Svelte preprocessors](https://github.com/sveltejs/svelte-preprocess) then
simply follow the instructions over at
[svelte-jester](https://github.com/mihar-22/svelte-jester#babel).
[svelte-preprocess]: https://github.com/sveltejs/svelte-preprocess
[svelte-jester typescript]:
https://github.com/svelteness/svelte-jester#typescript
[svelte-jester preprocess]:
https://github.com/svelteness/svelte-jester#preprocess

0 comments on commit 01bb6d3

Please sign in to comment.