@testing-library/svelte 5.0.0 → 5.1.0

package/README.md

@@ -13,7 +13,7 @@
 <p>Simple and complete Svelte testing utilities that encourage good testing practices.</p>
 
 [**Read The Docs**](https://testing-library.com/docs/svelte-testing-library/intro) |
-[Edit the docs](https://github.com/alexkrolick/testing-library-docs)
+[Edit the docs](https://github.com/testing-library/testing-library-docs)
 
 <!-- prettier-ignore-start -->
 [![Build Status][build-badge]][build]
@@ -80,19 +80,42 @@ This library has `peerDependencies` listings for `svelte >= 3`.
 You may also be interested in installing `@testing-library/jest-dom` so you can use
 [the custom jest matchers](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
+
 ### Svelte 5 support
 
 If you are riding the bleeding edge of Svelte 5, you'll need to either
-import from `@testing-library/svelte/svelte5` instead of `@testing-library/svelte`, or have your `vite.config.js` contains the following alias:
+import from `@testing-library/svelte/svelte5` instead of `@testing-library/svelte`, or add an alias to your `vite.config.js`:
 
-```
-export default defineConfig(({ }) => ({
+```js
+export default defineConfig({
+  plugins: [svelte(), svelteTesting()],
   test: {
     alias: {
-      '@testing-library/svelte': '@testing-library/svelte/svelte5'
-    }
+      '@testing-library/svelte': '@testing-library/svelte/svelte5',
+    },
   },
-}))
+})
 ```
 
 ## Docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testing-library/svelte",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Simple and complete Svelte testing utilities that encourage good testing practices.",
   "main": "src/index.js",
   "exports": {
@@ -14,6 +14,10 @@
     },
     "./vitest": {
       "default": "./src/vitest.js"
+    },
+    "./vite": {
+      "types": "./types/vite.d.ts",
+      "default": "./src/vite.js"
     }
   },
   "type": "module",
@@ -43,8 +47,10 @@
     "e2e"
   ],
   "files": [
-    "src/",
-    "types/index.d.ts"
+    "src",
+    "types",
+    "!*.test-d.ts",
+    "!__tests__"
   ],
   "scripts": {
     "toc": "doctoc README.md",
@@ -68,7 +74,17 @@
     "contributors:generate": "all-contributors generate"
   },
   "peerDependencies": {
-    "svelte": "^3 || ^4 || ^5"
+    "svelte": "^3 || ^4 || ^5",
+    "vite": "*",
+    "vitest": "*"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@testing-library/dom": "^9.3.1"

package/src/__tests__/_vitest-setup.js

@@ -1,2 +1 @@
 import '@testing-library/jest-dom/vitest'
-import '../vitest'

package/src/vite.js

@@ -0,0 +1,75 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Vite plugin to configure @testing-library/svelte.
+ *
+ * Ensures Svelte is imported correctly in tests
+ * and that the DOM is cleaned up after each test.
+ *
+ * @param {{resolveBrowser?: boolean, autoCleanup?: boolean}} options
+ * @returns {import('vite').Plugin}
+ */
+export const svelteTesting = ({
+  resolveBrowser = true,
+  autoCleanup = true,
+} = {}) => ({
+  name: 'vite-plugin-svelte-testing-library',
+  config: (config) => {
+    if (!process.env.VITEST) {
+      return
+    }
+
+    if (resolveBrowser) {
+      addBrowserCondition(config)
+    }
+
+    if (autoCleanup) {
+      addAutoCleanup(config)
+    }
+  },
+})
+
+/**
+ * Add `browser` to `resolve.conditions` before `node`.
+ *
+ * This ensures that Svelte's browser code is used in tests,
+ * rather than its SSR code.
+ *
+ * @param {import('vitest/config').UserConfig} config
+ */
+const addBrowserCondition = (config) => {
+  const resolve = config.resolve ?? {}
+  const conditions = resolve.conditions ?? []
+  const nodeConditionIndex = conditions.indexOf('node')
+  const browserConditionIndex = conditions.indexOf('browser')
+
+  if (
+    nodeConditionIndex >= 0 &&
+    (nodeConditionIndex < browserConditionIndex || browserConditionIndex < 0)
+  ) {
+    conditions.splice(nodeConditionIndex, 0, 'browser')
+  }
+
+  resolve.conditions = conditions
+  config.resolve = resolve
+}
+
+/**
+ * Add auto-cleanup file to Vitest's setup files.
+ *
+ * @param {import('vitest/config').UserConfig} config
+ */
+const addAutoCleanup = (config) => {
+  const test = config.test ?? {}
+  let setupFiles = test.setupFiles ?? []
+
+  if (typeof setupFiles === 'string') {
+    setupFiles = [setupFiles]
+  }
+
+  setupFiles.push(join(dirname(fileURLToPath(import.meta.url)), './vitest.js'))
+
+  test.setupFiles = setupFiles
+  config.test = test
+}

package/types/types.test-d.ts

@@ -0,0 +1,65 @@
+import { expectTypeOf } from 'expect-type'
+import type { ComponentProps, SvelteComponent } from 'svelte'
+import { describe, test } from 'vitest'
+
+import Simple from '../src/__tests__/fixtures/Simple.svelte'
+import * as subject from './index.js'
+
+describe('types', () => {
+  test('render is a function that accepts a Svelte component', () => {
+    subject.render(Simple, { name: 'Alice', count: 42 })
+    subject.render(Simple, { props: { name: 'Alice', count: 42 } })
+  })
+
+  test('rerender is a function that accepts partial props', async () => {
+    const { rerender } = subject.render(Simple, { name: 'Alice', count: 42 })
+
+    await rerender({ name: 'Bob' })
+    await rerender({ count: 0 })
+  })
+
+  test('invalid prop types are rejected', () => {
+    // @ts-expect-error: name should be a string
+    subject.render(Simple, { name: 42 })
+
+    // @ts-expect-error: name should be a string
+    subject.render(Simple, { props: { name: 42 } })
+  })
+
+  test('render result has container and component', () => {
+    const result = subject.render(Simple, { name: 'Alice', count: 42 })
+
+    expectTypeOf(result).toMatchTypeOf<{
+      container: HTMLElement
+      component: SvelteComponent<{ name: string }>
+      debug: (el?: HTMLElement) => void
+      rerender: (props: Partial<ComponentProps<Simple>>) => Promise<void>
+      unmount: () => void
+    }>()
+  })
+
+  test('render result has default queries', () => {
+    const result = subject.render(Simple, { name: 'Alice', count: 42 })
+
+    expectTypeOf(result.getByRole).parameters.toMatchTypeOf<
+      [role: subject.ByRoleMatcher, options?: subject.ByRoleOptions]
+    >()
+  })
+
+  test('render result can have custom queries', () => {
+    const [getByVibes] = subject.buildQueries(
+      (_container: HTMLElement, vibes: string) => {
+        throw new Error(`unimplemented ${vibes}`)
+      },
+      () => '',
+      () => ''
+    )
+    const result = subject.render(
+      Simple,
+      { name: 'Alice', count: 42 },
+      { queries: { getByVibes } }
+    )
+
+    expectTypeOf(result.getByVibes).parameters.toMatchTypeOf<[vibes: string]>()
+  })
+})

package/types/vite.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from 'vite'
+
+/**
+ * Vite plugin to configure @testing-library/svelte.
+ *
+ * Ensures Svelte is imported correctly in tests
+ * and that the DOM is cleaned up after each test.
+ */
+export function svelteTesting(options?: {
+  resolveBrowser?: boolean
+  autoCleanup?: boolean
+}): Plugin