docs: add testing section (#12600)

* docs: add testing section

- explain component and rune testing using Vitest
- explain e2e testing using Playwright

closes #10244
closes #10650

* better examples

* Update documentation/docs/05-misc/02-testing.md

Co-authored-by: Rich Harris <[email protected]>

* Update documentation/docs/05-misc/02-testing.md

Co-authored-by: Rich Harris <[email protected]>

* Update documentation/docs/05-misc/02-testing.md

Co-authored-by: Rich Harris <[email protected]>

* fix

* Update documentation/docs/05-misc/02-testing.md

* Update documentation/docs/05-misc/02-testing.md

Co-authored-by: Ben McCann <[email protected]>

* Update documentation/docs/05-misc/02-testing.md

* we normally use single quotes

* Apply suggestions from code review

Co-authored-by: Rich Harris <[email protected]>

* more details on component testing

* extract component testing into its own sub section, reorder a bit

* fix code example

* Update documentation/docs/05-misc/02-testing.md

* Apply suggestions from code review

Co-authored-by: Rich Harris <[email protected]>

---------

Co-authored-by: Rich Harris <[email protected]>
Co-authored-by: Ben McCann <[email protected]>

Author: 3 people

documentation/docs/05-misc/02-testing.md

@@ -2,7 +2,217 @@
 title: Testing
 ---
 
-- component testing basics
-- rune testing basics
-- vitest setup
-- e2e
+Testing helps you write and maintain your code and guard against regressions. Testing frameworks help you with that, allowing you to describe assertions or expectations about how your code should behave. Svelte is unopinionated about which testing framework you use — you can write unit tests, integration tests, and end-to-end tests using solutions like [Vitest](https://vitest.dev/), [Jasmine](https://jasmine.github.io/), [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/).
+
+## Unit and integration testing using Vitest
+
+Unit tests allow you to test small isolated parts of your code. Integration tests allow you to test parts of your application to see if they work together. If you're using Vite (including via SvelteKit), we recommend using [Vitest](https://vitest.dev/).
+
+To get started, install Vitest:
+
+```bash
+npm install -D vitest
+```
+
+Then adjust your `vite.config.js`:
+
+```diff
+/// file: vite.config.js
+- import { defineConfig } from 'vite';
++ import { defineConfig } from 'vitest/config';
+
+export default defineConfig({ /* ... */ })
+```
+
+You can now write unit tests for code inside your `.js/.ts` files:
+
+```js
+/// file: multiplier.svelte.test.js
+import { flushSync } from 'svelte';
+import { expect, test } from 'vitest';
+import { multiplier } from './multiplier.js';
+
+test('Multiplier', () => {
+	let double = multiplier(0, 2);
+
+	expect(double.value).toEqual(0);
+
+	double.set(5);
+
+	expect(double.value).toEqual(10);
+});
+```
+
+### Using runes inside your test files
+
+It is possible to use runes inside your test files. First ensure your bundler knows to route the file through the Svelte compiler before running the test by adding `.svelte` to the filename (e.g `multiplier.svelte.test.js`). After that, you can use runes inside your tests.
+
+```js
+/// file: multiplier.svelte.test.js
+import { flushSync } from 'svelte';
+import { expect, test } from 'vitest';
+import { multiplier } from './multiplier.svelte.js';
+
+test('Multiplier', () => {
+	let count = $state(0);
+	let double = multiplier(() => count, 2);
+
+	expect(double.value).toEqual(0);
+
+	count = 5;
+
+	expect(double.value).toEqual(10);
+});
+```
+
+If the code being tested uses effects, you need to wrap the test inside `$effect.root`:
+
+```js
+/// file: logger.svelte.test.js
+import { flushSync } from 'svelte';
+import { expect, test } from 'vitest';
+import { logger } from './logger.svelte.js';
+
+test('Effect', () => {
+	const cleanup = $effect.root(() => {
+		let count = $state(0);
+
+		// logger uses an $effect to log updates of its input
+		let log = logger(() => count);
+
+		// effects normally run after a microtask,
+		// use flushSync to execute all pending effects synchronously
+		flushSync();
+		expect(log.value).toEqual([0]);
+
+		count = 1;
+		flushSync();
+
+		expect(log.value).toEqual([0, 1]);
+	});
+
+	cleanup();
+});
+```
+
+### Component testing
+
+It is possible to test your components in isolation using Vitest.
+
+> 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
+
+To get started, install jsdom (a library that shims DOM APIs):
+
+```bash
+npm install -D jsdom
+```
+
+Then adjust your `vite.config.js`:
+
+```js
+/// file: vite.config.js
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+	plugins: [
+		/* ... */
+	],
+	test: {
+		// If you are testing components client-side, you need to setup a DOM environment.
+		// If not all your files should have this environment, you can use a
+		// `// @vitest-environment jsdom` comment at the top of the test files instead.
+		environment: 'jsdom'
+	},
+	// Tell Vitest to use the `browser` entry points in `package.json` files, even though it's running in Node
+	resolve: process.env.VITEST
+		? {
+				conditions: ['browser']
+			}
+		: undefined
+});
+```
+
+After that, you can create a test file in which you import the component to test, interact with it programmatically and write expectations about the results:
+
+```js
+/// file: component.test.js
+import { flushSync, mount, unmount } from 'svelte';
+import { expect, test } from 'vitest';
+import Component from './Component.svelte';
+
+test('Component', () => {
+	// Instantiate the component using Svelte's `mount` API
+	const component = mount(Component, {
+		target: document.body, // `document` exists because of jsdom
+		props: { initial: 0 }
+	});
+
+	expect(document.body.innerHTML).toBe('<button>0</button>');
+
+	// Click the button, then flush the changes so you can synchronously write expectations
+	document.body.querySelector('button').click();
+	flushSync();
+
+	expect(document.body.innerHTML).toBe('<button>1</button>');
+
+	// Remove the component from the DOM
+	unmount(component);
+});
+```
+
+While the process is very straightforward, it is also low level and somewhat brittle, as the precise structure of your component may change frequently. Tools like [@testing-library/svelte](https://testing-library.com/docs/svelte-testing-library/intro/) can help streamline your tests. The above test could be rewritten like this:
+
+```js
+/// file: component.test.js
+import { render, screen } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import { expect, test } from 'vitest';
+import Component from './Component.svelte';
+
+test('Component', async () => {
+	const user = userEvent.setup();
+	render(Component);
+
+	const button = screen.getByRole('button');
+	expect(button).toHaveTextContent(0);
+
+	await user.click(button);
+	expect(button).toHaveTextContent(1);
+});
+```
+
+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).
+
+## 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/).
+
+To get start with Playwright, either let you guide by [their VS Code extension](https://playwright.dev/docs/getting-started-vscode), or install it from the command line using `npm init playwright`. It is also part of the setup CLI when you run `npm create svelte`.
+
+After you've done that, you should have a `tests` folder and a Playwright config. You may need to adjust that config to tell Playwright what to do before running the tests - mainly starting your application at a certain port:
+
+```js
+/// file: playwright.config.js
+const config = {
+	webServer: {
+		command: 'npm run build && npm run preview',
+		port: 4173
+	},
+	testDir: 'tests',
+	testMatch: /(.+\.)?(test|spec)\.[jt]s/
+};
+
+export default config;
+```
+
+You can now start writing tests. These are totally unaware of Svelte as a framework, so you mainly interact with the DOM and write assertions.
+
+```js
+/// file: tests/hello-world.spec.js
+import { expect, test } from '@playwright/test';
+
+test('home page has expected h1', async ({ page }) => {
+	await page.goto('/');
+	await expect(page.locator('h1')).toBeVisible();
+});
+```