@testing-library/svelte 5.1.0 → 5.2.0-next.2

package/README.md

@@ -12,17 +12,18 @@
 
 <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/testing-library/testing-library-docs)
+[**Read The Docs**][stl-docs] | [Edit the docs][stl-docs-repo]
 
 <!-- prettier-ignore-start -->
 [![Build Status][build-badge]][build]
 [![Code Coverage][coverage-badge]][coverage]
-[![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends]
+[![version][version-badge]][package]
+[![downloads][downloads-badge]][downloads]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
-[![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc]
+[![All Contributors][contributors-badge]][contributors]
+[![PRs Welcome][prs-badge]][prs]
+[![Code of Conduct][coc-badge]][coc]
 [![Discord][discord-badge]][discord]
 
 [![Watch on GitHub][github-watch-badge]][github-watch]
@@ -33,6 +34,33 @@
 
 <hr />
 
+[stl-docs]: https://testing-library.com/docs/svelte-testing-library/intro
+[stl-docs-repo]: https://github.com/testing-library/testing-library-docs
+[build-badge]: https://img.shields.io/github/actions/workflow/status/testing-library/svelte-testing-library/release.yml?style=flat-square
+[build]: https://github.com/testing-library/svelte-testing-library/actions
+[coverage-badge]: https://img.shields.io/codecov/c/github/testing-library/svelte-testing-library.svg?style=flat-square
+[coverage]: https://codecov.io/github/testing-library/svelte-testing-library
+[version-badge]: https://img.shields.io/npm/v/@testing-library/svelte.svg?style=flat-square
+[package]: https://www.npmjs.com/package/@testing-library/svelte
+[downloads-badge]: https://img.shields.io/npm/dm/@testing-library/svelte.svg?style=flat-square
+[downloads]: http://www.npmtrends.com/@testing-library/svelte
+[license-badge]: https://img.shields.io/github/license/testing-library/svelte-testing-library?color=b&style=flat-square
+[license]: https://github.com/testing-library/svelte-testing-library/blob/main/LICENSE
+[contributors-badge]: https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square
+[contributors]: #contributors
+[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
+[prs]: http://makeapullrequest.com
+[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
+[coc]: https://github.com/testing-library/svelte-testing-library/blob/main/CODE_OF_CONDUCT.md
+[discord-badge]: https://img.shields.io/discord/723559267868737556.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square
+[discord]: https://discord.gg/testing-library
+[github-watch-badge]: https://img.shields.io/github/watchers/testing-library/svelte-testing-library.svg?style=social
+[github-watch]: https://github.com/testing-library/svelte-testing-library/watchers
+[github-star-badge]: https://img.shields.io/github/stars/testing-library/svelte-testing-library.svg?style=social
+[github-star]: https://github.com/testing-library/svelte-testing-library/stargazers
+[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20svelte-testing-library%20by%20%40@TestingLib%20https%3A%2F%2Fgithub.com%2Ftesting-library%2Fsvelte-testing-library%20%F0%9F%91%8D
+[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/svelte-testing-library.svg?style=social
+
 ## Table of Contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
@@ -41,48 +69,57 @@
 - [The Problem](#the-problem)
 - [This Solution](#this-solution)
 - [Installation](#installation)
+- [Setup](#setup)
 - [Docs](#docs)
 - [Issues](#issues)
   - [🐛 Bugs](#-bugs)
   - [💡 Feature Requests](#-feature-requests)
   - [❓ Questions](#-questions)
 - [Contributors](#contributors)
-- [LICENSE](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## The Problem
 
-You want to write tests for your Svelte components so that they avoid including implementation
-details, and are maintainable in the long run.
+You want to write maintainable tests for your [Svelte][svelte] components.
+
+[svelte]: https://svelte.dev/
 
 ## This Solution
 
-The `svelte-testing-library` is a very lightweight solution for testing Svelte
-components. It provides light utility functions on top of `svelte` and
-`dom-testing-library`, in a way that encourages better testing practices. Its
-primary guiding principle is:
+`@testing-library/svelte` is a lightweight library for testing Svelte
+components. It provides functions on top of `svelte` and
+`@testing-library/dom` so you can mount Svelte components and query their
+rendered output in the DOM. Its primary guiding principle is:
 
 > [The more your tests resemble the way your software is used, the more
 > confidence they can give you.][guiding-principle]
 
+[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
+
 ## Installation
 
 This module is distributed via [npm][npm] which is bundled with [node][node] and
 should be installed as one of your project's `devDependencies`:
 
-```
+```shell
 npm install --save-dev @testing-library/svelte
 ```
 
-This library has `peerDependencies` listings for `svelte >= 3`.
+This library supports `svelte` versions `3`, `4`, and `5`.
+
+You may also be interested in installing `@testing-library/jest-dom` so you can
+use [the custom jest matchers][jest-dom].
 
-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).
+[npm]: https://www.npmjs.com/
+[node]: https://nodejs.org
+[jest-dom]: 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.
+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
@@ -97,42 +134,31 @@ We recommend using `@testing-library/svelte` with [Vitest][] as your test runner
   });
 ```
 
-See the [setup docs][] for more detailed setup instructions, including for other test runners like Jest.
+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 add an alias to your `vite.config.js`:
-
-```js
-export default defineConfig({
-  plugins: [svelte(), svelteTesting()],
-  test: {
-    alias: {
-      '@testing-library/svelte': '@testing-library/svelte/svelte5',
-    },
-  },
-})
-```
-
 ## Docs
 
-See the [**docs**](https://testing-library.com/docs/svelte-testing-library/intro) over at the Testing Library website.
+See the [**docs**][stl-docs] over at the Testing Library website.
 
 ## Issues
 
 _Looking to contribute? Look for the [Good First Issue][good-first-issue]
 label._
 
+[good-first-issue]: https://github.com/testing-library/svelte-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+
+
 ### 🐛 Bugs
 
 Please file an issue for bugs, missing documentation, or unexpected behavior.
 
 [**See Bugs**][bugs]
 
+[bugs]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
+
 ### 💡 Feature Requests
 
 Please file an issue to suggest new features. Vote on feature requests by adding
@@ -140,6 +166,8 @@ a 👍. This helps maintainers prioritize what to work on.
 
 [**See Feature Requests**][requests]
 
+[requests]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
+
 ### ❓ Questions
 
 For questions related to using the library, please visit a support community
@@ -148,6 +176,8 @@ instead of filing an issue on GitHub.
 - [Discord][discord]
 - [Stack Overflow][stackoverflow]
 
+[stackoverflow]: https://stackoverflow.com/questions/tagged/svelte-testing-library
+
 ## Contributors
 
 Thanks goes to these people ([emoji key][emojis]):
@@ -189,44 +219,5 @@ Thanks goes to these people ([emoji key][emojis]):
 This project follows the [all-contributors][all-contributors] specification.
 Contributions of any kind welcome!
 
-## LICENSE
-
-[MIT](LICENSE)
-
-<!-- prettier-ignore-start -->
-
-[npm]: https://www.npmjs.com/
-[node]: https://nodejs.org
-[build-badge]: https://img.shields.io/github/actions/workflow/status/testing-library/svelte-testing-library/release.yml?style=flat-square
-[build]: https://github.com/testing-library/svelte-testing-library/actions
-[coverage-badge]: https://img.shields.io/codecov/c/github/testing-library/svelte-testing-library.svg?style=flat-square
-[coverage]: https://codecov.io/github/testing-library/svelte-testing-library
-[version-badge]: https://img.shields.io/npm/v/@testing-library/svelte.svg?style=flat-square
-[package]: https://www.npmjs.com/package/@testing-library/svelte
-[downloads-badge]: https://img.shields.io/npm/dm/@testing-library/svelte.svg?style=flat-square
-[npmtrends]: http://www.npmtrends.com/@testing-library/svelte
-[discord-badge]: https://img.shields.io/discord/723559267868737556.svg?color=7389D8&labelColor=6A7EC2&logo=discord&logoColor=ffffff&style=flat-square
-[discord]: https://discord.gg/testing-library
-[license-badge]: https://img.shields.io/github/license/testing-library/svelte-testing-library?color=b&style=flat-square
-[license]: https://github.com/testing-library/svelte-testing-library/blob/main/LICENSE
-[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
-[prs]: http://makeapullrequest.com
-[donate-badge]: https://img.shields.io/badge/$-support-green.svg?style=flat-square
-[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
-[coc]: https://github.com/testing-library/svelte-testing-library/blob/main/CODE_OF_CONDUCT.md
-[github-watch-badge]: https://img.shields.io/github/watchers/testing-library/svelte-testing-library.svg?style=social
-[github-watch]: https://github.com/testing-library/svelte-testing-library/watchers
-[github-star-badge]: https://img.shields.io/github/stars/testing-library/svelte-testing-library.svg?style=social
-[github-star]: https://github.com/testing-library/svelte-testing-library/stargazers
-[twitter]: https://twitter.com/intent/tweet?text=Check%20out%20svelte-testing-library%20by%20%40@TestingLib%20https%3A%2F%2Fgithub.com%2Ftesting-library%2Fsvelte-testing-library%20%F0%9F%91%8D
-[twitter-badge]: https://img.shields.io/twitter/url/https/github.com/testing-library/svelte-testing-library.svg?style=social
 [emojis]: https://github.com/all-contributors/all-contributors#emoji-key
 [all-contributors]: https://github.com/all-contributors/all-contributors
-[set-immediate]: https://developer.mozilla.org/en-US/docs/Web/API/Window/setImmediate
-[guiding-principle]: https://twitter.com/kentcdodds/status/977018512689455106
-[bugs]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Acreated-desc
-[requests]: https://github.com/testing-library/svelte-testing-library/issues?q=is%3Aissue+sort%3Areactions-%2B1-desc+label%3Aenhancement+is%3Aopen
-[good-first-issue]: https://github.com/testing-library/svelte-testing-library/issues?utf8=✓&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A"good+first+issue"+
-[stackoverflow]: https://stackoverflow.com/questions/tagged/svelte-testing-library
-
-<!-- prettier-ignore-end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testing-library/svelte",
-  "version": "5.1.0",
+  "version": "5.2.0-next.2",
   "description": "Simple and complete Svelte testing utilities that encourage good testing practices.",
   "main": "src/index.js",
   "exports": {
@@ -10,9 +10,10 @@
     },
     "./svelte5": {
       "types": "./types/index.d.ts",
-      "default": "./src/svelte5-index.js"
+      "default": "./src/index.js"
     },
     "./vitest": {
+      "types": "./types/vitest.d.ts",
       "default": "./src/vitest.js"
     },
     "./vite": {
@@ -26,7 +27,7 @@
   "homepage": "https://github.com/testing-library/svelte-testing-library#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/testing-library/svelte-testing-library"
+    "url": "git+https://github.com/testing-library/svelte-testing-library.git"
   },
   "bugs": {
     "url": "https://github.com/testing-library/svelte-testing-library/issues"
@@ -49,7 +50,6 @@
   "files": [
     "src",
     "types",
-    "!*.test-d.ts",
     "!__tests__"
   ],
   "scripts": {
@@ -65,13 +65,15 @@
     "setup": "npm install && npm run validate",
     "test": "vitest run --coverage",
     "test:watch": "vitest",
-    "test:update": "vitest run --update",
     "test:vitest:jsdom": "vitest run --coverage --environment jsdom",
     "test:vitest:happy-dom": "vitest run --coverage --environment happy-dom",
+    "test:jest": "npx --node-options=\"--experimental-vm-modules --no-warnings\" jest --coverage",
     "types": "svelte-check",
-    "validate": "npm-run-all test:vitest:* types",
+    "validate": "npm-run-all test:vitest:* test:jest types build",
+    "build": "tsc -p tsconfig.build.json",
     "contributors:add": "all-contributors add",
-    "contributors:generate": "all-contributors generate"
+    "contributors:generate": "all-contributors generate",
+    "preview-release": "./scripts/preview-release"
   },
   "peerDependencies": {
     "svelte": "^3 || ^4 || ^5",
@@ -87,38 +89,41 @@
     }
   },
   "dependencies": {
-    "@testing-library/dom": "^9.3.1"
+    "@testing-library/dom": "^10.0.0"
   },
   "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.0.2",
+    "@jest/globals": "^29.7.0",
+    "@sveltejs/vite-plugin-svelte": "^3.1.1",
     "@testing-library/jest-dom": "^6.3.0",
     "@testing-library/user-event": "^14.5.2",
-    "@typescript-eslint/eslint-plugin": "6.19.1",
-    "@typescript-eslint/parser": "6.19.1",
-    "@vitest/coverage-v8": "^0.33.0",
+    "@typescript-eslint/eslint-plugin": "7.8.0",
+    "@typescript-eslint/parser": "7.8.0",
+    "@vitest/coverage-v8": "^1.5.2",
     "all-contributors-cli": "^6.26.1",
     "doctoc": "^2.2.1",
-    "eslint": "8.56.0",
+    "eslint": "8.57.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-config-standard": "17.1.0",
     "eslint-plugin-import": "2.29.1",
     "eslint-plugin-json-files": "^4.1.0",
     "eslint-plugin-n": "16.6.2",
     "eslint-plugin-promise": "6.1.1",
-    "eslint-plugin-simple-import-sort": "10.0.0",
-    "eslint-plugin-svelte": "2.35.1",
-    "eslint-plugin-vitest-globals": "1.4.0",
-    "expect-type": "^0.17.3",
+    "eslint-plugin-simple-import-sort": "12.1.0",
+    "eslint-plugin-svelte": "2.38.0",
+    "eslint-plugin-vitest-globals": "1.5.0",
+    "expect-type": "^0.19.0",
     "happy-dom": "^14.7.1",
-    "jsdom": "^22.1.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^24.0.0",
     "npm-run-all": "^4.1.5",
-    "prettier": "3.2.4",
-    "prettier-plugin-svelte": "3.1.2",
+    "prettier": "3.2.5",
+    "prettier-plugin-svelte": "3.2.3",
     "svelte": "^3 || ^4 || ^5",
     "svelte-check": "^3.6.3",
-    "svelte-jester": "^3.0.0",
+    "svelte-jester": "^5.0.0",
     "typescript": "^5.3.3",
     "vite": "^5.1.1",
-    "vitest": "^0.33.0"
+    "vitest": "^1.5.2"
   }
 }

package/src/core/index.js

@@ -0,0 +1,27 @@
+/**
+ * Rendering core for svelte-testing-library.
+ *
+ * Defines how components are added to and removed from the DOM.
+ * Will switch to legacy, class-based mounting logic
+ * if it looks like we're in a Svelte <= 4 environment.
+ */
+import * as LegacyCore from './legacy.js'
+import * as ModernCore from './modern.svelte.js'
+import {
+  createValidateOptions,
+  UnknownSvelteOptionsError,
+} from './validate-options.js'
+
+const { mount, unmount, updateProps, allowedOptions } =
+  ModernCore.IS_MODERN_SVELTE ? ModernCore : LegacyCore
+
+/** Validate component options. */
+const validateOptions = createValidateOptions(allowedOptions)
+
+export {
+  mount,
+  UnknownSvelteOptionsError,
+  unmount,
+  updateProps,
+  validateOptions,
+}

package/src/core/legacy.js

@@ -0,0 +1,46 @@
+/**
+ * Legacy rendering core for svelte-testing-library.
+ *
+ * Supports Svelte <= 4.
+ */
+
+/** Allowed options for the component constructor. */
+const allowedOptions = [
+  'target',
+  'accessors',
+  'anchor',
+  'props',
+  'hydrate',
+  'intro',
+  'context',
+]
+
+/**
+ * Mount the component into the DOM.
+ *
+ * The `onDestroy` callback is included for strict backwards compatibility
+ * with previous versions of this library. It's mostly unnecessary logic.
+ */
+const mount = (Component, options, onDestroy) => {
+  const component = new Component(options)
+
+  if (typeof onDestroy === 'function') {
+    component.$$.on_destroy.push(() => {
+      onDestroy(component)
+    })
+  }
+
+  return component
+}
+
+/** Remove the component from the DOM. */
+const unmount = (component) => {
+  component.$destroy()
+}
+
+/** Update the component's props. */
+const updateProps = (component, nextProps) => {
+  component.$set(nextProps)
+}
+
+export { allowedOptions, mount, unmount, updateProps }

package/src/core/modern.svelte.js

@@ -0,0 +1,50 @@
+/**
+ * Modern rendering core for svelte-testing-library.
+ *
+ * Supports Svelte >= 5.
+ */
+import * as Svelte from 'svelte'
+
+/** Props signals for each rendered component. */
+const propsByComponent = new Map()
+
+/** Whether we're using Svelte >= 5. */
+const IS_MODERN_SVELTE = typeof Svelte.mount === 'function'
+
+/** Allowed options to the `mount` call. */
+const allowedOptions = [
+  'target',
+  'anchor',
+  'props',
+  'events',
+  'context',
+  'intro',
+]
+
+/** Mount the component into the DOM. */
+const mount = (Component, options) => {
+  const props = $state(options.props ?? {})
+  const component = Svelte.mount(Component, { ...options, props })
+
+  propsByComponent.set(component, props)
+
+  return component
+}
+
+/** Remove the component from the DOM. */
+const unmount = (component) => {
+  propsByComponent.delete(component)
+  Svelte.unmount(component)
+}
+
+/**
+ * Update the component's props.
+ *
+ * Relies on the `$state` signal added in `mount`.
+ */
+const updateProps = (component, nextProps) => {
+  const prevProps = propsByComponent.get(component)
+  Object.assign(prevProps, nextProps)
+}
+
+export { allowedOptions, IS_MODERN_SVELTE, mount, unmount, updateProps }

package/src/core/validate-options.js

@@ -0,0 +1,39 @@
+class UnknownSvelteOptionsError extends TypeError {
+  constructor(unknownOptions, allowedOptions) {
+    super(`Unknown options.
+
+    Unknown: [ ${unknownOptions.join(', ')} ]
+    Allowed: [ ${allowedOptions.join(', ')} ]
+
+    To pass both Svelte options and props to a component,
+    or to use props that share a name with a Svelte option,
+    you must place all your props under the \`props\` key:
+
+    render(Component, { props: { /** props here **/ } })
+`)
+    this.name = 'UnknownSvelteOptionsError'
+  }
+}
+
+const createValidateOptions = (allowedOptions) => (options) => {
+  const isProps = !Object.keys(options).some((option) =>
+    allowedOptions.includes(option)
+  )
+
+  if (isProps) {
+    return { props: options }
+  }
+
+  // Check if any props and Svelte options were accidentally mixed.
+  const unknownOptions = Object.keys(options).filter(
+    (option) => !allowedOptions.includes(option)
+  )
+
+  if (unknownOptions.length > 0) {
+    throw new UnknownSvelteOptionsError(unknownOptions, allowedOptions)
+  }
+
+  return options
+}
+
+export { createValidateOptions, UnknownSvelteOptionsError }

package/src/index.js

@@ -4,8 +4,7 @@ import { act, cleanup } from './pure.js'
 // If we're running in a test runner that supports afterEach
 // then we'll automatically run cleanup afterEach test
 // this ensures that tests run in isolation from each other
-// if you don't like this then either import the `pure` module
-// or set the STL_SKIP_AUTO_CLEANUP env variable to 'true'.
+// if you don't like this then set the STL_SKIP_AUTO_CLEANUP env variable.
 if (typeof afterEach === 'function' && !process.env.STL_SKIP_AUTO_CLEANUP) {
   afterEach(async () => {
     await act()
@@ -17,5 +16,7 @@ if (typeof afterEach === 'function' && !process.env.STL_SKIP_AUTO_CLEANUP) {
 export * from '@testing-library/dom'
 
 // export svelte-specific functions and custom `fireEvent`
-// `fireEvent` must be a named export to take priority over wildcard export above
-export { act, cleanup, fireEvent, render } from './pure.js'
+export { UnknownSvelteOptionsError } from './core/index.js'
+export * from './pure.js'
+// `fireEvent` must be named to take priority over wildcard from @testing-library/dom
+export { fireEvent } from './pure.js'