From c1ed85bcfb85cd39044de007dc74771c506c08c4 Mon Sep 17 00:00:00 2001 From: Michael Cousins Date: Mon, 29 Jan 2024 14:58:51 +1100 Subject: [PATCH 1/2] docs(svelte-testing-library): update vitest and jest setup instructions --- docs/svelte-testing-library/intro.mdx | 17 +- docs/svelte-testing-library/setup.mdx | 267 +++++++++++++------------- 2 files changed, 141 insertions(+), 143 deletions(-) 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..61c620180 100644 --- a/docs/svelte-testing-library/setup.mdx +++ b/docs/svelte-testing-library/setup.mdx @@ -4,83 +4,89 @@ 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][] -```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 configure cleanup and + [`@testing-library/jest-dom`][@testing-library/jest-dom], if using. - ```bash npm2yarn - npm install --save-dev @sveltejs/vite-plugin-svelte vite + ```ts + // 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 + // 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 + :::note - 4.1 Install `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 - ```bash npm2yarn - npm install --save-dev vitest-dom - ``` + See [testing-library/svelte-testing-library#222][] for more information and + alternative configuration options to ensure Svelte's browser bundle is used. + ::: - 4.2 import `vitest-dom` at within the vitest setup file (usually - `vitest-setup.(js|ts)`) +4. Add test scipts to your `package.json` to run the tests with Vitest - ```js - import * as matchers from 'vitest-dom/matchers' - import {expect} from 'vitest' - expect.extend(matchers) - - // or: - import 'vitest-dom/extend-expect' + ```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 +96,97 @@ 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 environment]: 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 + // 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 + // 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 + { + "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 From eede65d5641c8f9e23d41cd6c5278856d0968aad Mon Sep 17 00:00:00 2001 From: Michael Cousins Date: Wed, 31 Jan 2024 07:25:35 +1100 Subject: [PATCH 2/2] fixup: address review feedback --- docs/svelte-testing-library/setup.mdx | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/svelte-testing-library/setup.mdx b/docs/svelte-testing-library/setup.mdx index 61c620180..473aa51ba 100644 --- a/docs/svelte-testing-library/setup.mdx +++ b/docs/svelte-testing-library/setup.mdx @@ -19,7 +19,7 @@ runner that's ESM compatible. - [`@sveltejs/vite-plugin-svelte`][@sveltejs/vite-plugin-svelte] - [`vitest`][vitest] - [`jsdom`][jsdom], [`happy-dom`][happy-dom], or other [Vitest DOM - environment][] + environment][vitest dom] ```bash npm2yarn npm install --save-dev \ @@ -37,11 +37,10 @@ runner that's ESM compatible. npm install --save-dev @vitest/ui ``` -2. Add a `vitest-setup.js` file to configure cleanup and - [`@testing-library/jest-dom`][@testing-library/jest-dom], if using. +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. - ```ts - // vitest-setup.js + ```ts title="vitest-setup.js" import '@testing-library/svelte/vitest' import '@testing-library/jest-dom/vitest' ``` @@ -50,8 +49,7 @@ runner that's ESM compatible. Svelte files, resolve browser exports during tests, use the [jsdom][] (or [happy-dom][]) environment, and run your setup file. - ```js - // vitest.config.js + ```js title="vitest.config.js" import {defineConfig} from 'vitest/config' import {svelte} from '@sveltejs/vite-plugin-svelte' @@ -77,9 +75,9 @@ runner that's ESM compatible. alternative configuration options to ensure Svelte's browser bundle is used. ::: -4. Add test scipts to your `package.json` to run the tests with Vitest +4. Add test scripts to your `package.json` to run the tests with Vitest - ```json + ```json title="package.json" { "scripts": { "test": "vitest run", @@ -103,7 +101,7 @@ runner that's ESM compatible. [jsdom]: https://github.com/jsdom/jsdom [happy-dom]: https://github.com/capricorn86/happy-dom [@vitest/ui]: https://vitest.dev/guide/ui.html -[vitest dom environment]: https://vitest.dev/guide/environment.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 @@ -133,15 +131,13 @@ you must use Jest in [ESM mode][jest esm mode]. 2. Add a `jest-setup.js` file to configure [`@testing-library/jest-dom`][@testing-library/jest-dom], if using. - ```ts - // jest-setup.js + ```ts title="jest-setup.js" import '@testing-library/jest-dom' ``` 3. Configure Jest to use jsdom, transform Svelte files, and use your setup file - ```js - // jest.config.js + ```js title="jest.config.js" module.exports = { "transform": { "^.+\\.svelte$": "svelte-jester" @@ -155,7 +151,7 @@ you must use Jest in [ESM mode][jest esm mode]. 4. Add the following to your `package.json` - ```json + ```json title="package.json" { "scripts": { "test": "npx --node-options=\"--experimental-vm-modules\" jest src",