diff --git a/docs/svelte-testing-library/intro.mdx b/docs/svelte-testing-library/intro.mdx index 375ae98cd..4c0a5df1f 100644 --- a/docs/svelte-testing-library/intro.mdx +++ b/docs/svelte-testing-library/intro.mdx @@ -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 @@ -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**: diff --git a/docs/svelte-testing-library/setup.mdx b/docs/svelte-testing-library/setup.mdx index cc02a7386..473aa51ba 100644 --- a/docs/svelte-testing-library/setup.mdx +++ b/docs/svelte-testing-library/setup.mdx @@ -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 @@ -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": ["/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