Svelte Testing Library

Simple and complete Svelte testing utilities that encourage good testing practices.

[**Read The Docs**][stl-docs] | [Edit the docs][stl-docs-repo] | [Examples](./examples) [![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![version][version-badge]][package] [![downloads][downloads-badge]][downloads] [![MIT License][license-badge]][license] [![All Contributors][contributors-badge]][contributors] [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] [![Discord][discord-badge]][discord] [![Watch on GitHub][github-watch-badge]][github-watch] [![Star on GitHub][github-star-badge]][github-star] [![Tweet][twitter-badge]][twitter]

[stl-docs]: https://testing-library.com/docs/svelte-testing-library/intro [stl-docs-repo]: https://github.com/testing-library/testing-library-docs [build-badge]: https://img.shields.io/github/actions/workflow/status/testing-library/svelte-testing-library/release.yml?style=flat-square [build]: https://github.com/testing-library/svelte-testing-library/actions [coverage-badge]: https://img.shields.io/codecov/c/github/testing-library/svelte-testing-library.svg?style=flat-square [coverage]: https://codecov.io/github/testing-library/svelte-testing-library [version-badge]: https://img.shields.io/npm/v/@testing-library/svelte.svg?style=flat-square [package]: https://www.npmjs.com/package/@testing-library/svelte [downloads-badge]: https://img.shields.io/npm/dm/@testing-library/svelte.svg?style=flat-square [downloads]: http://www.npmtrends.com/@testing-library/svelte [license-badge]: https://img.shields.io/github/license/testing-library/svelte-testing-library?color=b&style=flat-square [license]: https://github.com/testing-library/svelte-testing-library/blob/main/LICENSE [contributors-badge]: https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square [contributors]: #contributors [prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square [prs]: http://makeapullrequest.com [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square [coc]: https://github.com/testing-library/svelte-testing-library/blob/main/CODE_OF_CONDUCT.md [discord-badge]: https://img.shields.io/discord/723559267868737556.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square [discord]: https://discord.gg/testing-library [github-watch-badge]: https://img.shields.io/github/watchers/testing-library/svelte-testing-library.svg?style=social [github-watch]: https://github.com/testing-library/svelte-testing-library/watchers [github-star-badge]: https://img.shields.io/github/stars/testing-library/svelte-testing-library.svg?style=social [github-star]: https://github.com/testing-library/svelte-testing-library/stargazers [twitter]: https://twitter.com/intent/tweet?text=Check%20out%20svelte-testing-library%20by%20%40@TestingLib%20https%3A%2F%2Fgithub.com%2Ftesting-library%2Fsvelte-testing-library%20%F0%9F%91%8D [twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/svelte-testing-library.svg?style=social ## Table of Contents - [The Problem](#the-problem) - [This Solution](#this-solution) - [Installation](#installation) - [Setup](#setup) - [Auto-cleanup](#auto-cleanup) - [Docs](#docs) - [Issues](#issues) - [🐛 Bugs](#-bugs) - [💡 Feature Requests](#-feature-requests) - [❓ Questions](#-questions) - [Contributors](#contributors) ## The Problem You want to write maintainable tests for your [Svelte][svelte] components. [svelte]: https://svelte.dev/ ## This Solution `@testing-library/svelte` is a lightweight library for testing Svelte components. It provides functions on top of `svelte` and `@testing-library/dom` so you can mount Svelte components and query their rendered output in the DOM. Its primary guiding principle is: > [The more your tests resemble the way your software is used, the more > confidence they can give you.][guiding-principle] [guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106 ## Installation This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's `devDependencies`: ```shell npm install --save-dev @testing-library/svelte ``` This library supports `svelte` versions `3`, `4`, and `5`. You may also be interested in installing `@testing-library/jest-dom` so you can use [the custom jest matchers][jest-dom]. [npm]: https://www.npmjs.com/ [node]: https://nodejs.org [jest-dom]: https://github.com/testing-library/jest-dom ## Setup We recommend using `@testing-library/svelte` with [Vitest][] as your test runner. To get started, add the `svelteTesting` plugin to your Vite or Vitest config. ```diff // vite.config.js import { svelte } from '@sveltejs/vite-plugin-svelte' + import { svelteTesting } from '@testing-library/svelte/vite' export default defineConfig({ plugins: [ svelte(), + svelteTesting(), ] }); ``` See the [setup docs][] for more detailed setup instructions, including for other test runners like Jest. [vitest]: https://vitest.dev/ [setup docs]: https://testing-library.com/docs/svelte-testing-library/setup ### Auto-cleanup In Vitest (via the `svelteTesting` plugin) and Jest (via the `beforeEach` and `afterEach` globals), this library will automatically setup and cleanup the test environment before and after each test. To do your own cleanup, or if you're using another framework, call the `setup` and `cleanup` functions yourself: ```js import { cleanup, render, setup } from '@testing-library/svelte' // before setup() // test render(/* ... */) // after cleanup() ``` To disable auto-cleanup in Vitest, set the `autoCleanup` option of the plugin to false: ```js svelteTesting({ autoCleanup: false }) ``` To disable auto-cleanup in Jest and other frameworks with global test hooks, set the `STL_SKIP_AUTO_CLEANUP` environment variable: ```shell STL_SKIP_AUTO_CLEANUP=1 jest ``` ## Docs See the [**docs**][stl-docs] over at the Testing Library website. ## Issues _Looking to contribute? Look for the [Good First Issue][good-first-issue] label._ [good-first-issue]: https://github.com/testing-library/svelte-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+ ### 🐛 Bugs Please file an issue for bugs, missing documentation, or unexpected behavior. [**See Bugs**][bugs] [bugs]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc ### 💡 Feature Requests Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on. [**See Feature Requests**][requests] [requests]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen ### ❓ Questions For questions related to using the library, please visit a support community instead of filing an issue on GitHub. - [Discord][discord] - [Stack Overflow][stackoverflow] [stackoverflow]: https://stackoverflow.com/questions/tagged/svelte-testing-library ## Contributors Thanks goes to these people ([emoji key][emojis]):

_{Ben Monro} 💻 ⚠️ 🤔 📖	_{Emil Tholin} 💻 ⚠️ 🤔	_{Eduardo Rabelo} ⚠️ 💻 📖 💡	_{Tim Deschryver} 📖	_Emanuele 💻 ⚠️ 📖	_pngwn 💻 ⚠️	_{Sebastian Silbermann} 💻
_{Rahim Alwer} 💻 📖 ⚠️ 👀	_Bob 🐛 💻	_{Ron Merkin} 💻	_{Ben McCann} ⚠️	_{John Bowser} 💻 ⚠️	_Yoann 💻	_{Yanick Champoux} 💻
_{Michael Cousins} 💻

This project follows the [all-contributors][all-contributors] specification. Contributions of any kind welcome! [emojis]: https://github.com/all-contributors/all-contributors#emoji-key [all-contributors]: https://github.com/all-contributors/all-contributors