From 6e7ccf73043ee91fea228da2cc00c65b245ec5e3 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Fri, 29 Aug 2025 10:50:05 -0600 Subject: [PATCH 1/7] docs: add testing with storybook --- documentation/docs/07-misc/02-testing.md | 89 +++++++++++++++++++++++- 1 file changed, 87 insertions(+), 2 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index bcec4db0a39b..32682e97798a 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -160,9 +160,11 @@ export function logger(getValue) { ### Component testing -It is possible to test your components in isolation using Vitest. +It is possible to test your components in isolation, which allows you to render them in a browser (real or simulated), simulate behavior, and make assertions, without spinning up your whole app. -> [!NOTE] Before writing component tests, think about whether you actually need to test the component, or if it's more about the logic _inside_ the component. If so, consider extracting out that logic to test it in isolation, without the overhead of a component +> [!NOTE] Before writing component tests, think about whether you actually need to test the component, or if it's more about the logic _inside_ the component. If so, consider extracting out that logic to test it in isolation, without the overhead of a component. + +_With Vitest and jsdom_ To get started, install jsdom (a library that shims DOM APIs): @@ -246,6 +248,89 @@ test('Component', async () => { When writing component tests that involve two-way bindings, context or snippet props, it's best to create a wrapper component for your specific test and interact with that. `@testing-library/svelte` contains some [examples](https://testing-library.com/docs/svelte-testing-library/example). +_With Storybook_ + +[Storybook](https://storybook.js.org?ref=svelte-docs) is the industry standard for developing and documenting UI components, and it can also be used to test your components. A storybook is made up of [stories](https://storybook.js.org/docs/writing-stories?ref=svelte-docs&renderer=svelte)โ€”isolated examples of your components in different states and with simulated interactions. These stories can also function as [component tests](https://storybook.js.org/docs/writing-tests?ref=svelte-docs&renderer=svelte), with no additional code needed. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. + +To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project if you haven't already: + +```sh +npx sv add storybook +``` + +When prompted, choose the recommended configuration that includes testing features. + +If you already have Storybook set up, but are not yet using the testing features, first upgrade to the latest version: + +```sh +npx storybook@latest upgrade +``` + +Then, install and configure Storybook's Vitest addon: + +```sh +npx storybook add @storybook/addon-vitest +``` + +That `add` command will install and register the Vitest addon. It will also inspect your project's Vite and Vitest setup, and install and configure them with sensible defaults, if necessary. You may need to adjust the [configuration](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon?ref=svelte-docs&renderer=svelte#options) to fit your project's needs. + +When you run Storybook, you will see a test widget in the bottom of your sidebar, from where you can run your tests. Each story is automatically transformed into a test. The results will be shown in the sidebar and you can debug your tests using Storybook's tools and the browser devtools. You can also integrate [accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility?ref=svelte-docs&renderer=svelte), which will run alongside your component tests. + +
+ +
+ Running component tests in Storybook, filtering the sidebar to test failures, turning on watch mode, and using the interactions debugger to fix the failure +
+
+ +You can also run those component tests in the terminal (and in CI) using the Vitest CLI.: + +```sh +npx vitest --project storybook +``` + +You can create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?ref=svelte-docs&renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty Form component and one that simulates a user filling out the form: + +```svelte +/// file: LoginForm.stories.svelte + + + + + { + // ๐Ÿ‘‡ Simulate a user filling out the form + await userEvent.type(canvas.getByTestId('email'), 'email@provider.com'); + await userEvent.type(canvas.getByTestId('password'), 'a-random-password'); + await userEvent.click(canvas.getByRole('button')); + + // ๐Ÿ‘‡ Assert that the `onSubmit` function was called + await expect(args.onSubmit).toHaveBeenCalledTimes(1); + + // ๐Ÿ‘‡ Assert that the success message is shown + await expect(canvas.getByText('Youโ€™re in!')).toBeInTheDocument(); + }} +/> +``` + +When you view that story or run that test in Storybook, you can see each step of the simulated behavior and the assertions made against the component. If anything goes wrong, you can step back-and-forth through the test to pinpoint exactly where the issue occurred. + ## E2E tests using Playwright E2E (short for 'end to end') tests allow you to test your full application through the eyes of the user. This section uses [Playwright](https://playwright.dev/) as an example, but you can also use other solutions like [Cypress](https://www.cypress.io/) or [NightwatchJS](https://nightwatchjs.org/). From 7b3bfaa484bae058028492aa4103ccdc4cd3e245 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Tue, 2 Sep 2025 15:21:25 -0600 Subject: [PATCH 2/7] docs: remove video --- documentation/docs/07-misc/02-testing.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index 32682e97798a..468dbfa03f06 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -276,15 +276,6 @@ That `add` command will install and register the Vitest addon. It will also insp When you run Storybook, you will see a test widget in the bottom of your sidebar, from where you can run your tests. Each story is automatically transformed into a test. The results will be shown in the sidebar and you can debug your tests using Storybook's tools and the browser devtools. You can also integrate [accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility?ref=svelte-docs&renderer=svelte), which will run alongside your component tests. -
- -
- Running component tests in Storybook, filtering the sidebar to test failures, turning on watch mode, and using the interactions debugger to fix the failure -
-
- You can also run those component tests in the terminal (and in CI) using the Vitest CLI.: ```sh From 805d4542bc5eac8c41ca779286f6b9944f695565 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Tue, 2 Sep 2025 17:46:39 -0600 Subject: [PATCH 3/7] docs: address feedback - consistent tabs vs. spaces in snippet - add more Storybook details --- documentation/docs/07-misc/02-testing.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index 468dbfa03f06..d8115a35b443 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -287,25 +287,25 @@ You can create stories for component variations and test interactions with the [ ```svelte /// file: LoginForm.stories.svelte { + name="Filled Form" + play={async ({ args, canvas, userEvent }) => { // ๐Ÿ‘‡ Simulate a user filling out the form await userEvent.type(canvas.getByTestId('email'), 'email@provider.com'); await userEvent.type(canvas.getByTestId('password'), 'a-random-password'); @@ -316,12 +316,14 @@ You can create stories for component variations and test interactions with the [ // ๐Ÿ‘‡ Assert that the success message is shown await expect(canvas.getByText('Youโ€™re in!')).toBeInTheDocument(); - }} + }} /> ``` When you view that story or run that test in Storybook, you can see each step of the simulated behavior and the assertions made against the component. If anything goes wrong, you can step back-and-forth through the test to pinpoint exactly where the issue occurred. +To learn more about Storybook's mocking, accessibility testing, interactions debugging, and coverage tools, please see the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?ref=svelte-docs&renderer=svelte). + ## E2E tests using Playwright E2E (short for 'end to end') tests allow you to test your full application through the eyes of the user. This section uses [Playwright](https://playwright.dev/) as an example, but you can also use other solutions like [Cypress](https://www.cypress.io/) or [NightwatchJS](https://nightwatchjs.org/). From b78774b85e29cd44aebbbdc1949e7ad606732904 Mon Sep 17 00:00:00 2001 From: Simon H <5968653+dummdidumm@users.noreply.github.com> Date: Wed, 3 Sep 2025 13:58:43 +0200 Subject: [PATCH 4/7] Revise Storybook testing documentation condense, remove referer query parameters --- documentation/docs/07-misc/02-testing.md | 46 ++++-------------------- 1 file changed, 7 insertions(+), 39 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index d8115a35b443..99c78af7e956 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -250,39 +250,11 @@ When writing component tests that involve two-way bindings, context or snippet p _With Storybook_ -[Storybook](https://storybook.js.org?ref=svelte-docs) is the industry standard for developing and documenting UI components, and it can also be used to test your components. A storybook is made up of [stories](https://storybook.js.org/docs/writing-stories?ref=svelte-docs&renderer=svelte)โ€”isolated examples of your components in different states and with simulated interactions. These stories can also function as [component tests](https://storybook.js.org/docs/writing-tests?ref=svelte-docs&renderer=svelte), with no additional code needed. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. +[Storybook](https://storybook.js.org) is a tool for developing and documenting UI components, and it can also be used to test your components. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. -To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project if you haven't already: +To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. Else follow the [Storybooks docs](https://storybook.js.org/docs/get-started/frameworks/svelte-vite#getting-started) on getting started. -```sh -npx sv add storybook -``` - -When prompted, choose the recommended configuration that includes testing features. - -If you already have Storybook set up, but are not yet using the testing features, first upgrade to the latest version: - -```sh -npx storybook@latest upgrade -``` - -Then, install and configure Storybook's Vitest addon: - -```sh -npx storybook add @storybook/addon-vitest -``` - -That `add` command will install and register the Vitest addon. It will also inspect your project's Vite and Vitest setup, and install and configure them with sensible defaults, if necessary. You may need to adjust the [configuration](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon?ref=svelte-docs&renderer=svelte#options) to fit your project's needs. - -When you run Storybook, you will see a test widget in the bottom of your sidebar, from where you can run your tests. Each story is automatically transformed into a test. The results will be shown in the sidebar and you can debug your tests using Storybook's tools and the browser devtools. You can also integrate [accessibility tests](https://storybook.js.org/docs/writing-tests/accessibility?ref=svelte-docs&renderer=svelte), which will run alongside your component tests. - -You can also run those component tests in the terminal (and in CI) using the Vitest CLI.: - -```sh -npx vitest --project storybook -``` - -You can create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?ref=svelte-docs&renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty Form component and one that simulates a user filling out the form: +You can then create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty Form component and one that simulates a user filling out the form: ```svelte /// file: LoginForm.stories.svelte @@ -295,7 +267,7 @@ You can create stories for component variations and test interactions with the [ const { Story } = defineMeta({ component: LoginForm, args: { - // ๐Ÿ‘‡ Pass a mock function to the `onSubmit` prop + // Pass a mock function to the `onSubmit` prop onSubmit: fn(), } }); @@ -306,23 +278,19 @@ You can create stories for component variations and test interactions with the [ { - // ๐Ÿ‘‡ Simulate a user filling out the form + // Simulate a user filling out the form await userEvent.type(canvas.getByTestId('email'), 'email@provider.com'); await userEvent.type(canvas.getByTestId('password'), 'a-random-password'); await userEvent.click(canvas.getByRole('button')); - // ๐Ÿ‘‡ Assert that the `onSubmit` function was called + // Run assertions await expect(args.onSubmit).toHaveBeenCalledTimes(1); - - // ๐Ÿ‘‡ Assert that the success message is shown await expect(canvas.getByText('Youโ€™re in!')).toBeInTheDocument(); }} /> ``` -When you view that story or run that test in Storybook, you can see each step of the simulated behavior and the assertions made against the component. If anything goes wrong, you can step back-and-forth through the test to pinpoint exactly where the issue occurred. - -To learn more about Storybook's mocking, accessibility testing, interactions debugging, and coverage tools, please see the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?ref=svelte-docs&renderer=svelte). +To learn more about Storybook's mocking, accessibility testing, interactions debugging, and coverage tools, please see the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte). ## E2E tests using Playwright From 3966b34407ad1d1087ecd0aa7ea0eee38955faa7 Mon Sep 17 00:00:00 2001 From: Simon H <5968653+dummdidumm@users.noreply.github.com> Date: Wed, 3 Sep 2025 22:35:04 +0200 Subject: [PATCH 5/7] Update documentation/docs/07-misc/02-testing.md Co-authored-by: Jeppe Reinhold --- documentation/docs/07-misc/02-testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index 99c78af7e956..4b2cace4b3e2 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -252,7 +252,7 @@ _With Storybook_ [Storybook](https://storybook.js.org) is a tool for developing and documenting UI components, and it can also be used to test your components. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. -To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. Else follow the [Storybooks docs](https://storybook.js.org/docs/get-started/frameworks/svelte-vite#getting-started) on getting started. +To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. Else follow the [Storybook docs](https://storybook.js.org/docs/get-started/frameworks/svelte-vite#getting-started) on getting started. You can then create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty Form component and one that simulates a user filling out the form: From dd457299345d27471aed5e654ca0a727a339cfbd Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Wed, 3 Sep 2025 18:08:50 -0600 Subject: [PATCH 6/7] Tweaks - Prose updates - More helpful link --- documentation/docs/07-misc/02-testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index 4b2cace4b3e2..570252a4f772 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -252,9 +252,9 @@ _With Storybook_ [Storybook](https://storybook.js.org) is a tool for developing and documenting UI components, and it can also be used to test your components. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. -To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. Else follow the [Storybook docs](https://storybook.js.org/docs/get-started/frameworks/svelte-vite#getting-started) on getting started. +To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. If you're already using Storybook, follow the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte) to get started. -You can then create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty Form component and one that simulates a user filling out the form: +You can create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty LoginForm component and one that simulates a user filling out the form: ```svelte /// file: LoginForm.stories.svelte From 908e35bb6c7cdc2fa06f8f03365d25ab6e6f8225 Mon Sep 17 00:00:00 2001 From: Simon H <5968653+dummdidumm@users.noreply.github.com> Date: Thu, 4 Sep 2025 09:53:24 +0200 Subject: [PATCH 7/7] make it its own section --- documentation/docs/07-misc/02-testing.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/documentation/docs/07-misc/02-testing.md b/documentation/docs/07-misc/02-testing.md index 570252a4f772..23e2e023d34c 100644 --- a/documentation/docs/07-misc/02-testing.md +++ b/documentation/docs/07-misc/02-testing.md @@ -164,8 +164,6 @@ It is possible to test your components in isolation, which allows you to render > [!NOTE] Before writing component tests, think about whether you actually need to test the component, or if it's more about the logic _inside_ the component. If so, consider extracting out that logic to test it in isolation, without the overhead of a component. -_With Vitest and jsdom_ - To get started, install jsdom (a library that shims DOM APIs): ```sh @@ -248,11 +246,11 @@ test('Component', async () => { When writing component tests that involve two-way bindings, context or snippet props, it's best to create a wrapper component for your specific test and interact with that. `@testing-library/svelte` contains some [examples](https://testing-library.com/docs/svelte-testing-library/example). -_With Storybook_ +### Component testing with Storybook [Storybook](https://storybook.js.org) is a tool for developing and documenting UI components, and it can also be used to test your components. They're run with Vitest's browser mode, which renders your components in a real browser for the most realistic testing environment. -To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. If you're already using Storybook, follow the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte) to get started. +To get started, first install Storybook ([using Svelte's CLI](/docs/cli/storybook)) in your project via `npx sv add storybook` and choose the recommended configuration that includes testing features. If you're already using Storybook, and for more information on Storybook's testing capabilities, follow the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte) to get started. You can create stories for component variations and test interactions with the [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests), which allows you to simulate behavior and make assertions using the Testing Library and Vitest APIs. Here's an example of two stories that can be tested, one that renders an empty LoginForm component and one that simulates a user filling out the form: @@ -290,8 +288,6 @@ You can create stories for component variations and test interactions with the [ /> ``` -To learn more about Storybook's mocking, accessibility testing, interactions debugging, and coverage tools, please see the [Storybook testing docs](https://storybook.js.org/docs/writing-tests?renderer=svelte). - ## E2E tests using Playwright E2E (short for 'end to end') tests allow you to test your full application through the eyes of the user. This section uses [Playwright](https://playwright.dev/) as an example, but you can also use other solutions like [Cypress](https://www.cypress.io/) or [NightwatchJS](https://nightwatchjs.org/).