Setup - Testing Library

We recommend using Vitest, but you're free to use the library with any test runner that's ESM compatible.

Vitest

Add development dependencies
- @testing-library/svelte
- @testing-library/jest-dom (Optional, but highly recommended)
- @sveltejs/vite-plugin-svelte
- vitest
- jsdom, happy-dom, or other Vitest DOM environment
bash
```
npm install --save-dev \
  @testing-library/svelte \
  @testing-library/jest-dom \
  @sveltejs/vite-plugin-svelte \
  vitest \
  jsdom
```
Optionally install @vitest/ui, which opens a UI within a browser window to follow the progress and interact with your tests.
bash
```
npm install --save-dev @vitest/ui
```
Add a vitest-setup.js file to optionally set up @testing-library/jest-dom expect matchers.
js
```
import '@testing-library/jest-dom/vitest'
```

Add vitest.config.js, or update your existing vite.config.js, with the svelte and svelteTesting Vite plugins. Set the testing environment to your DOM library of choice and optionally configure your setup file from step (2).

import {defineConfig} from 'vitest/config'
import {svelte} from '@sveltejs/vite-plugin-svelte'
import {svelteTesting} from '@testing-library/svelte/vite'

export default defineConfig({
  plugins: [svelte(), svelteTesting()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./vitest-setup.js'],
  },
})

Or, if you're using SvelteKit:

import {defineConfig} from 'vitest/config'
import {sveltekit} from '@sveltejs/kit/vite'
import {svelteTesting} from '@testing-library/svelte/vite'

export default defineConfig({
  plugins: [sveltekit(), svelteTesting()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./vitest-setup.js'],
  },
})

:::note

The svelteTesting plugin:

Adds an automatic cleanup fixture to test.setupFiles
Adds browser to resolve.conditions

If needed, you can disable either behavior. Disabling both options is equivalent to omitting the plugin.

svelteTesting({
  // disable auto cleanup
  autoCleanup: false,
  // disable browser resolution condition
  resolveBrowser: false,
})

Resolving the browser condition may cause issues if you have a complex Vite configuration or dependencies that cannot be loaded into Node.js. See testing-library/svelte-testing-library#222 for more information and alternative configuration options to ensure Svelte's browser code is used. :::

Add test scripts to your package.json to run the tests with Vitest

json

{
  "scripts": {
    "test": "vitest run",
    "test:ui": "vitest --ui",
    "test:watch": "vitest"
  }
}

Create your component and a test file (checkout the rest of the docs to see how) and run the following command to run the tests.
bash
```
npm test
```

TypeScript

Include @testing-library/jest-dom to the TypeScript types to make the TypeScript compiler aware about the @testing-library/jest-dom matchers.

json

{
  "compilerOptions": {
	"types": ["@testing-library/jest-dom"],
  }
}

Jest

@testing-library/svelte is ESM-only, which means you must use Jest in ESM mode.

Add development dependencies
- @testing-library/svelte
- @testing-library/jest-dom (Optional, but highly recommended)
- svelte-jester
- jest
- jest-environment-jsdom
bash
```
npm install --save-dev \
  @testing-library/svelte \
  @testing-library/jest-dom \
  svelte-jester \
  jest \
  jest-environment-jsdom
```
Add a jest-setup.js file to configure @testing-library/jest-dom, if using.
ts
```
import '@testing-library/jest-dom'
```

Configure Jest to use jsdom, transform Svelte files, and use your setup file

export default {
  transform: {
    '^.+\\.svelte$': 'svelte-jester',
  },
  moduleFileExtensions: ['js', 'svelte'],
  extensionsToTreatAsEsm: ['.svelte'],
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest-setup.js'],
}

:::note

If you are using Svelte 5, you must use svelte-jester@5 or later, and you will need to make additional changes to your Jest configuration.

Update transform to compile .svelte.(js|ts) modules
Allow @testing-library/svelte to be transformed, even though it's in node_modules

diff

  export default {
    transform: {
-     '^.+\\.svelte$': 'svelte-jester',
+     '^.+\\.svelte(\\.(js|ts))?$': 'svelte-jester',
    },
+   transformIgnorePatterns: [
+     '/node_modules/(?!@testing-library/svelte/)',
+   ],
    moduleFileExtensions: ['js', 'svelte'],
    extensionsToTreatAsEsm: ['.svelte'],
    testEnvironment: 'jsdom',
    setupFilesAfterEnv: ['<rootDir>/jest-setup.js'],
  }

:::

Add the following to your package.json

json

{
  "scripts": {
    "test": "npx --node-options=\"--experimental-vm-modules\" jest src",
    "test:watch": "npx --node-options=\"--experimental-vm-modules\" jest src --watch"
  }
}

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

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 docs.

If you'd like include any other Svelte preprocessors, see the svelte-jester docs.