setup.mdx

id	title	sidebar_label
setup	Setup	Setup

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

Vitest

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

   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.

   npm install --save-dev @vitest/ui

2. Add a vitest-setup.js file to optionally set up automatic post-test cleanup and @testing-library/jest-dom expect matchers.

   import '@testing-library/svelte/vitest'
   import '@testing-library/jest-dom/vitest'

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.

   import {defineConfig} from 'vitest/config'
   import {svelte} from '@sveltejs/vite-plugin-svelte'
   
   export default defineConfig(({mode}) => ({
     plugins: [svelte()],
     resolve: {
       conditions: mode === 'test' ? ['browser'] : [],
     },
     test: {
       environment: 'jsdom',
       setupFiles: ['./vitest-setup.js'],
     },
   }))

   :::note

   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

   See testing-library/svelte-testing-library#222 for more information and alternative configuration options to ensure Svelte's browser bundle is used. :::

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

   {
     "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 how) and run the following command to run the tests.

   npm test

Jest

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

1. Add development dependencies

   • @testing-library/svelte
   • @testing-library/jest-dom (Optional, but highly recommended)
   • svelte-jester
   • jest
   • jest-environment-jsdom

   npm install --save-dev \
     @testing-library/svelte \
     @testing-library/jest-dom \
     svelte-jester \
     jest \
     jest-environment-jsdom

2. Add a jest-setup.js file to configure @testing-library/jest-dom, if using.

   import '@testing-library/jest-dom'

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

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

4. Add the following to your package.json

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

5. Create your component + test file (checkout the rest of the docs to see how) and run it

   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.