svelte-testing-library: testing Svelte components through the DOM

A thin layer over svelte and @testing-library/dom

The README states the problem in one line: you want to write maintainable tests for your Svelte components. The solution follows from that in the same number of words, because the library deliberately does very little of its own.

@testing-library/svelte is described as a lightweight library for testing Svelte components. It provides functions on top of svelte and @testing-library/dom so that you can mount Svelte components and query their rendered output in the DOM. Two dependencies you probably already know, and a set of functions rather than a new model.

The guiding principle is quoted in the README and comes from Kent C. Dodds: the more your tests resemble the way your software is used, the more confidence they can give you. That principle is the reason the library is query-centric. You do not reach into a component and call its methods; you render it, then look for text, roles and labels in the DOM, exactly as a screen reader or a user would.

The consequence for the code you write is that tests break when behaviour changes and not when implementation changes. A refactor that renames an internal variable leaves the test alone, while a button whose accessible name changes fails the test immediately.

The audience is Svelte developers writing component tests, and the project sits inside the wider Testing Library family, with the same philosophy applied to each framework. The documentation lives on the Testing Library site rather than in the repository, and the examples/ directory in the repository contains a working app per feature area.

One plugin, two cleanup paths

The setup story is where this library is more than a set of query helpers, and the README is unusually specific about it.

The recommendation is to use @testing-library/svelte with Vitest as the test runner, and to add the svelteTesting plugin to your Vite or Vitest config. The change is two lines:

  // vite.config.js
  import { svelte } from '@sveltejs/vite-plugin-svelte'
+ import { svelteTesting } from '@testing-library/svelte/vite'

  export default defineConfig({
    plugins: [
      svelte(),
+     svelteTesting(),
    ]
  });

With that plugin in place, the library sets up and cleans up the test environment before and after each test, in Vitest via the plugin and in Jest via the beforeEach and afterEach globals.

Why that matters is a practical annoyance in component testing. A Svelte component mounted into the document leaves its DOM behind unless something tears it down, and leftovers from one test are the classic cause of a suite that passes alone and fails in a file. Handling that in every test file is noise, and the plugin removes it.

If you want to do the cleanup yourself, or you are on a framework the plugin does not cover, the library exports setup and cleanup functions and the README shows the intended shape:

import { cleanup, render, setup } from '@testing-library/svelte'

// before
await setup()

// test
render(/* ... */)

// after
cleanup()

And there are two documented escape hatches for turning the automatic behaviour off. In Vitest, set the autoCleanup option of the plugin to false with svelteTesting({ autoCleanup: false }). In Jest and other frameworks with global test hooks, set the STL_SKIP_AUTO_CLEANUP environment variable, for example STL_SKIP_AUTO_CLEANUP=1 jest.

Two packages released together, versioned apart

The release list shows that this project ships more than one npm package, and that they do not share a version number.

@testing-library/svelte is the package you install. Its recent releases are 5.4.1 on 2026-06-21 and 5.4.2 on 2026-06-23. Alongside it, @testing-library/svelte-core was published as 1.1.3 on the same day, 2026-06-23, while the previous core release, 1.1.3, sits far below the component library's 5.x line.

The split matters for one practical reason: a lockfile that pins only @testing-library/svelte still resolves a core package underneath it, and the two are versioned on different schedules. If you are pinning dependencies for a reproducible test environment, pinning both is the safer choice.

The repository is a pnpm workspace. The root package.json is a private package named @testing-library/svelte-repo, declares type as module, and lists @testing-library/svelte as a workspace dependency, with pnpm-workspace.yaml at the root. The packages/ directory holds the publishable packages.

The version spread also hints at a compatibility story. The README states the library supports svelte versions 3, 4 and 5, and the repository has scripts to install dependencies per major version, install:3, install:4 and install:5, along with separate typecheck and test scripts for the legacy path. The repository root holds both vite.config.js and jest.config.js, so both runners are supported in the tree.

The test matrix is the interesting part of the repository

The scripts in the root package.json describe how thoroughly this project tests itself, and it is more than the typical single-runner setup.

The test command is vitest run --coverage, and there are parallel scripts for the two DOM environments: test:vitest:jsdom runs vitest with the jsdom environment and test:vitest:happy-dom does the same with happy-dom. A separate script runs Jest with coverage, using NODE_OPTIONS="--experimental-vm-modules --no-warnings" to enable native ESM support in Jest, which is the detail that makes a modern Svelte project testable under Jest at all.

The aggregate scripts compose them. test:all runs the jsdom suite, then the happy-dom suite, then Jest, then the examples suite, and test:all:legacy runs the same chain without the examples. The examples directory contains a working app per feature area, with directories named basic, binds, contexts, deprecated, events, snippets and wrappers, plus a readme.md and a tsconfig.json. Running the examples as tests is how the library checks that its documented usage still works.

Type checking has its own split. typecheck runs svelte-check against tests/tsconfig.json and typecheck:legacy against tests/tsconfig.legacy.json, so the two Svelte generations are verified separately. The build itself is tsc --build for the types and a remark pass for the documentation, with remark-toc generating the table of contents and remark-code-import pulling code into the READMEs, so the docs cannot drift from the source.

This matrix is the practical reason to trust the library's claims about framework support. Running the same suite under two DOM implementations and two runners is a cheap way to find the assumptions that only hold in one environment.

Where the library deliberately stops

The boundaries are worth being explicit about, because a testing library that pretends to be more than it is costs you time.

It does not test Svelte internals. The whole API is render plus queries plus cleanup. There is no wrapper that calls a component method, no snapshot helper for a component's internal state, and no mechanism to reach into a Svelte store from a test. If your requirement is to assert that a function was called with particular arguments, this library is the wrong tool and no amount of configuration will change that.

It does not pick your test runner for you. The recommended path is the Vitest plugin, and the Jest path depends on global beforeEach and afterEach hooks, with STL_SKIP_AUTO_CLEANUP to opt out. The README says the setup documentation covers other runners such as Jest, but the shape of the API still assumes a runner with global hooks, which excludes a lot of bespoke harnesses.

It also does not include the assertion helpers. The README points you at @testing-library/jest-dom separately for the custom jest matchers, which is a deliberate separation: the matchers are shared across the whole Testing Library family, and this package stays focused on rendering and queries.

One more practical limit is the ecosystem around Svelte itself. The library supports svelte 3, 4 and 5, and the components under test are compiled by whatever plugin your build uses. When a Svelte release changes how a component compiles, the test outcomes can change with it, which is why the repository keeps a legacy test path alongside the current one rather than deleting it.

The parts of the repository you will not use

Reading the repository listing explains where the work of a release comes from, and it also lists everything you can ignore as a user of the package.

The maintenance surface is the .github/ directory with its release workflow, the scripts/ directory with the per-version dependency installers, the release.config.js for the release tooling, and the CHANGELOG.md. The formatting and linting setup is prettier.config.js, eslint.config.js, .prettierignore and .editorconfig, and the type configuration is tsconfig.json with svelte.config.js for the Svelte compiler options. There is a .all-contributorsrc and contributor scripts, CODE_OF_CONDUCT.md, CONTRIBUTING.md and a Discord badge for support.

As a consumer, all of that is somebody else's maintenance, and your only obligations are the dependency in your devDependencies and the plugin in your config.

The licence is MIT, which is the permissive end of the scale and the reason this can be a dependency in a commercial product without a legal review.

The documentation lives outside the repository on the Testing Library site, and the README links the docs and the docs repository separately, with the examples directory as the third source of truth. That arrangement is the Testing Library pattern: the package stays small, the documentation is shared across frameworks, and the examples are runnable code rather than prose.

The last push was on 2026-10-01 and the repository is not archived, so the library is still being worked on, and the newest published versions are 5.4.2 for the main package and 1.1.3 for the core package, both from 2026-06-23.

Editorial conclusion

svelte-testing-library fits a Svelte team that wants component tests written the way users interact with the page, and that is willing to add a Vitest plugin or the setup and cleanup calls to its test harness. It is the wrong choice for a project that has not settled on a test runner, since the plugin is Vitest-shaped and the Jest path depends on global hooks and an environment variable, and it is the wrong choice for tests that need to assert on component internals rather than on rendered output. Before adopting, add the svelteTesting plugin to your Vite config, confirm the cleanup behaviour matches how your suite isolates tests, and pin both @testing-library/svelte and @testing-library/svelte-core, since the newest published versions are 5.4.2 and 1.1.3 from 2026-06-23 and the two are released together.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. testing-library/svelte-testing-library on GitHub