From 9dce164c7f1e0f1b012f7e4604352ac3bfd9eb98 Mon Sep 17 00:00:00 2001 From: Michael Cousins Date: Thu, 20 Jun 2024 11:17:14 -0400 Subject: [PATCH] feat(svelte5): incorporate Svelte 5 support into main entry point (#375) --- .eslintrc.cjs | 2 + README.md | 20 +-- jest.config.js | 8 +- package.json | 4 +- src/__tests__/auto-cleanup.test.js | 9 +- src/__tests__/fixtures/Comp.svelte | 1 + src/__tests__/fixtures/CompRunes.svelte | 13 ++ src/__tests__/fixtures/Mounter.svelte | 2 +- src/__tests__/render.test.js | 14 +- src/__tests__/rerender.test.js | 26 +-- src/__tests__/utils.js | 17 ++ src/core/index.js | 27 ++++ src/core/legacy.js | 46 ++++++ src/core/modern.svelte.js | 50 ++++++ src/core/validate-options.js | 39 +++++ src/index.js | 8 +- src/pure.js | 200 +++++++++--------------- src/svelte5-index.js | 23 --- src/svelte5.js | 30 ---- vite.config.js | 16 -- 20 files changed, 311 insertions(+), 244 deletions(-) create mode 100644 src/__tests__/fixtures/CompRunes.svelte create mode 100644 src/core/index.js create mode 100644 src/core/legacy.js create mode 100644 src/core/modern.svelte.js create mode 100644 src/core/validate-options.js delete mode 100644 src/svelte5-index.js delete mode 100644 src/svelte5.js diff --git a/.eslintrc.cjs b/.eslintrc.cjs index 778d507..326785a 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -25,6 +25,7 @@ module.exports = { }, rules: { 'no-undef-init': 'off', + 'prefer-const': 'off', }, }, { @@ -49,5 +50,6 @@ module.exports = { ecmaVersion: 2022, sourceType: 'module', }, + globals: { $state: 'readonly', $props: 'readonly' }, ignorePatterns: ['!/.*'], } diff --git a/README.md b/README.md index 51ca77a..12a1984 100644 --- a/README.md +++ b/README.md @@ -71,11 +71,11 @@ primary guiding principle is: 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](https://github.com/testing-library/jest-dom). @@ -102,22 +102,6 @@ See the [setup docs][] for more detailed setup instructions, including for other [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. diff --git a/jest.config.js b/jest.config.js index d6b1fde..8e78075 100644 --- a/jest.config.js +++ b/jest.config.js @@ -1,11 +1,12 @@ import { VERSION as SVELTE_VERSION } from 'svelte/compiler' -const IS_SVELTE_5 = SVELTE_VERSION >= '5' +const SVELTE_TRANSFORM_PATTERN = + SVELTE_VERSION >= '5' ? '^.+\\.svelte(?:\\.js)?$' : '^.+\\.svelte$' export default { testMatch: ['/src/__tests__/**/*.test.js'], transform: { - '^.+\\.svelte$': 'svelte-jester', + [SVELTE_TRANSFORM_PATTERN]: 'svelte-jester', }, moduleFileExtensions: ['js', 'svelte'], extensionsToTreatAsEsm: ['.svelte'], @@ -14,9 +15,6 @@ export default { injectGlobals: false, moduleNameMapper: { '^vitest$': '/src/__tests__/_jest-vitest-alias.js', - '^@testing-library/svelte$': IS_SVELTE_5 - ? '/src/svelte5-index.js' - : '/src/index.js', }, resetMocks: true, restoreMocks: true, diff --git a/package.json b/package.json index c42f670..a79dc52 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ }, "./svelte5": { "types": "./types/index.d.ts", - "default": "./src/svelte5-index.js" + "default": "./src/index.js" }, "./vitest": { "default": "./src/vitest.js" @@ -120,7 +120,7 @@ "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": "^1.5.2" diff --git a/src/__tests__/auto-cleanup.test.js b/src/__tests__/auto-cleanup.test.js index b06d120..803001e 100644 --- a/src/__tests__/auto-cleanup.test.js +++ b/src/__tests__/auto-cleanup.test.js @@ -1,10 +1,5 @@ import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest' -import { IS_SVELTE_5 } from './utils.js' - -const importSvelteTestingLibrary = async () => - IS_SVELTE_5 ? import('../svelte5-index.js') : import('../index.js') - const globalAfterEach = vi.fn() describe('auto-cleanup', () => { @@ -19,7 +14,7 @@ describe('auto-cleanup', () => { }) test('calls afterEach with cleanup if globally defined', async () => { - const { render } = await importSvelteTestingLibrary() + const { render } = await import('../index.js') expect(globalAfterEach).toHaveBeenCalledTimes(1) expect(globalAfterEach).toHaveBeenLastCalledWith(expect.any(Function)) @@ -35,7 +30,7 @@ describe('auto-cleanup', () => { test('does not call afterEach if process STL_SKIP_AUTO_CLEANUP is set', async () => { process.env.STL_SKIP_AUTO_CLEANUP = 'true' - await importSvelteTestingLibrary() + await import('../index.js') expect(globalAfterEach).toHaveBeenCalledTimes(0) }) diff --git a/src/__tests__/fixtures/Comp.svelte b/src/__tests__/fixtures/Comp.svelte index ba23d88..86d8acd 100644 --- a/src/__tests__/fixtures/Comp.svelte +++ b/src/__tests__/fixtures/Comp.svelte @@ -1,3 +1,4 @@ + + +

Hello {name}!

+ + diff --git a/src/__tests__/fixtures/Mounter.svelte b/src/__tests__/fixtures/Mounter.svelte index 51ebcd8..27205dd 100644 --- a/src/__tests__/fixtures/Mounter.svelte +++ b/src/__tests__/fixtures/Mounter.svelte @@ -16,4 +16,4 @@ }) - diff --git a/src/__tests__/render.test.js b/src/__tests__/render.test.js index ea445d5..f396751 100644 --- a/src/__tests__/render.test.js +++ b/src/__tests__/render.test.js @@ -1,11 +1,15 @@ import { render } from '@testing-library/svelte' -import { describe, expect, test } from 'vitest' +import { beforeAll, describe, expect, test } from 'vitest' -import Comp from './fixtures/Comp.svelte' -import { IS_SVELTE_5 } from './utils.js' +import { COMPONENT_FIXTURES } from './utils.js' -describe('render', () => { +describe.each(COMPONENT_FIXTURES)('render ($mode)', ({ component }) => { const props = { name: 'World' } + let Comp + + beforeAll(async () => { + Comp = await import(component) + }) test('renders component into the document', () => { const { getByText } = render(Comp, { props }) @@ -65,7 +69,7 @@ describe('render', () => { expect(baseElement.firstChild).toBe(container) }) - test.skipIf(IS_SVELTE_5)('should accept anchor option in Svelte v4', () => { + test('should accept anchor option', () => { const baseElement = document.body const target = document.createElement('section') const anchor = document.createElement('div') diff --git a/src/__tests__/rerender.test.js b/src/__tests__/rerender.test.js index 21a782c..52acd0f 100644 --- a/src/__tests__/rerender.test.js +++ b/src/__tests__/rerender.test.js @@ -1,10 +1,15 @@ import { act, render, screen } from '@testing-library/svelte' -import { VERSION as SVELTE_VERSION } from 'svelte/compiler' -import { describe, expect, test, vi } from 'vitest' +import { beforeAll, describe, expect, test, vi } from 'vitest' -import Comp from './fixtures/Comp.svelte' +import { COMPONENT_FIXTURES, IS_SVELTE_5, MODE_RUNES } from './utils.js' + +describe.each(COMPONENT_FIXTURES)('rerender ($mode)', ({ mode, component }) => { + let Comp + + beforeAll(async () => { + Comp = await import(component) + }) -describe('rerender', () => { test('updates props', async () => { const { rerender } = render(Comp, { name: 'World' }) const element = screen.getByText('Hello World!') @@ -29,13 +34,12 @@ describe('rerender', () => { ) }) - test('change props with accessors', async () => { - const { component, getByText } = render( - Comp, - SVELTE_VERSION < '5' - ? { accessors: true, props: { name: 'World' } } - : { name: 'World' } - ) + test.skipIf(mode === MODE_RUNES)('change props with accessors', async () => { + const componentOptions = IS_SVELTE_5 + ? { name: 'World' } + : { accessors: true, props: { name: 'World' } } + + const { component, getByText } = render(Comp, componentOptions) const element = getByText('Hello World!') expect(element).toBeInTheDocument() diff --git a/src/__tests__/utils.js b/src/__tests__/utils.js index 69be184..68be33c 100644 --- a/src/__tests__/utils.js +++ b/src/__tests__/utils.js @@ -5,3 +5,20 @@ export const IS_JSDOM = window.navigator.userAgent.includes('jsdom') export const IS_HAPPYDOM = !IS_JSDOM // right now it's happy or js export const IS_SVELTE_5 = SVELTE_VERSION >= '5' + +export const MODE_LEGACY = 'legacy' + +export const MODE_RUNES = 'runes' + +export const COMPONENT_FIXTURES = [ + { + mode: MODE_LEGACY, + component: './fixtures/Comp.svelte', + isEnabled: true, + }, + { + mode: MODE_RUNES, + component: './fixtures/CompRunes.svelte', + isEnabled: IS_SVELTE_5, + }, +].filter(({ isEnabled }) => isEnabled) diff --git a/src/core/index.js b/src/core/index.js new file mode 100644 index 0000000..f4a40aa --- /dev/null +++ b/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, +} diff --git a/src/core/legacy.js b/src/core/legacy.js new file mode 100644 index 0000000..c9e6d1c --- /dev/null +++ b/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 } diff --git a/src/core/modern.svelte.js b/src/core/modern.svelte.js new file mode 100644 index 0000000..3da78b4 --- /dev/null +++ b/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 } diff --git a/src/core/validate-options.js b/src/core/validate-options.js new file mode 100644 index 0000000..c0d794b --- /dev/null +++ b/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 } diff --git a/src/index.js b/src/index.js index 2e3d772..3d8f18f 100644 --- a/src/index.js +++ b/src/index.js @@ -17,4 +17,10 @@ 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 { + act, + cleanup, + fireEvent, + render, + UnknownSvelteOptionsError, +} from './pure.js' diff --git a/src/pure.js b/src/pure.js index 364c225..71dff1e 100644 --- a/src/pure.js +++ b/src/pure.js @@ -3,155 +3,105 @@ import { getQueriesForElement, prettyDOM, } from '@testing-library/dom' -import * as Svelte from 'svelte' -import { VERSION as SVELTE_VERSION } from 'svelte/compiler' - -const IS_SVELTE_5 = /^5\./.test(SVELTE_VERSION) - -export class SvelteTestingLibrary { - svelteComponentOptions = [ - 'target', - 'accessors', - 'anchor', - 'props', - 'hydrate', - 'intro', - 'context', - ] - - targetCache = new Set() - componentCache = new Set() - - checkProps(options) { - const isProps = !Object.keys(options).some((option) => - this.svelteComponentOptions.includes(option) - ) - - // Check if any props and Svelte options were accidentally mixed. - if (!isProps) { - const unrecognizedOptions = Object.keys(options).filter( - (option) => !this.svelteComponentOptions.includes(option) - ) - - if (unrecognizedOptions.length > 0) { - throw Error(` - Unknown options were found [${unrecognizedOptions}]. This might happen if you've mixed - passing in props with Svelte options into the render function. Valid Svelte options - are [${this.svelteComponentOptions}]. You can either change the prop names, or pass in your - props for that component via the \`props\` option.\n\n - Eg: const { /** Results **/ } = render(MyComponent, { props: { /** props here **/ } })\n\n - `) - } - - return options - } - - return { props: options } - } - - render(Component, componentOptions = {}, renderOptions = {}) { - componentOptions = this.checkProps(componentOptions) - - const baseElement = - renderOptions.baseElement ?? componentOptions.target ?? document.body - - const target = - componentOptions.target ?? - baseElement.appendChild(document.createElement('div')) - - this.targetCache.add(target) - - const ComponentConstructor = Component.default || Component - - const component = this.renderComponent(ComponentConstructor, { - ...componentOptions, - target, - }) - - return { - baseElement, - component, - container: target, - debug: (el = baseElement) => console.log(prettyDOM(el)), - rerender: async (props) => { - if (props.props) { - console.warn( - 'rerender({ props: {...} }) deprecated, use rerender({...}) instead' - ) - props = props.props - } - component.$set(props) - await Svelte.tick() - }, - unmount: () => { - this.cleanupComponent(component) - }, - ...getQueriesForElement(baseElement, renderOptions.queries), - } - } - - renderComponent(ComponentConstructor, componentOptions) { - if (IS_SVELTE_5) { - throw new Error('for Svelte 5, use `@testing-library/svelte/svelte5`') - } - - const component = new ComponentConstructor(componentOptions) +import { tick } from 'svelte' - this.componentCache.add(component) - - // TODO(mcous, 2024-02-11): remove this behavior in the next major version - component.$$.on_destroy.push(() => { - this.componentCache.delete(component) - }) +import { + mount, + UnknownSvelteOptionsError, + unmount, + updateProps, + validateOptions, +} from './core/index.js' + +const targetCache = new Set() +const componentCache = new Set() + +const render = (Component, options = {}, renderOptions = {}) => { + options = validateOptions(options) + + const baseElement = + renderOptions.baseElement ?? options.target ?? document.body + + const queries = getQueriesForElement(baseElement, renderOptions.queries) + + const target = + options.target ?? baseElement.appendChild(document.createElement('div')) + + targetCache.add(target) + + const component = mount( + Component.default ?? Component, + { ...options, target }, + cleanupComponent + ) + + componentCache.add(component) + + return { + baseElement, + component, + container: target, + debug: (el = baseElement) => { + console.log(prettyDOM(el)) + }, + rerender: async (props) => { + if (props.props) { + console.warn( + 'rerender({ props: {...} }) deprecated, use rerender({...}) instead' + ) + props = props.props + } - return component + updateProps(component, props) + await tick() + }, + unmount: () => { + cleanupComponent(component) + }, + ...queries, } +} - cleanupComponent(component) { - const inCache = this.componentCache.delete(component) +const cleanupComponent = (component) => { + const inCache = componentCache.delete(component) - if (inCache) { - component.$destroy() - } + if (inCache) { + unmount(component) } +} - cleanupTarget(target) { - const inCache = this.targetCache.delete(target) - - if (inCache && target.parentNode === document.body) { - document.body.removeChild(target) - } - } +const cleanupTarget = (target) => { + const inCache = targetCache.delete(target) - cleanup() { - this.componentCache.forEach(this.cleanupComponent.bind(this)) - this.targetCache.forEach(this.cleanupTarget.bind(this)) + if (inCache && target.parentNode === document.body) { + document.body.removeChild(target) } } -const instance = new SvelteTestingLibrary() - -export const render = instance.render.bind(instance) - -export const cleanup = instance.cleanup.bind(instance) +const cleanup = () => { + componentCache.forEach(cleanupComponent) + targetCache.forEach(cleanupTarget) +} -export const act = async (fn) => { +const act = async (fn) => { if (fn) { await fn() } - return Svelte.tick() + return tick() } -export const fireEvent = async (...args) => { +const fireEvent = async (...args) => { const event = dtlFireEvent(...args) - await Svelte.tick() + await tick() return event } Object.keys(dtlFireEvent).forEach((key) => { fireEvent[key] = async (...args) => { const event = dtlFireEvent[key](...args) - await Svelte.tick() + await tick() return event } }) + +export { act, cleanup, fireEvent, render, UnknownSvelteOptionsError } diff --git a/src/svelte5-index.js b/src/svelte5-index.js deleted file mode 100644 index ab49641..0000000 --- a/src/svelte5-index.js +++ /dev/null @@ -1,23 +0,0 @@ -/* eslint-disable import/export */ -import { act } from './pure.js' -import { cleanup } from './svelte5.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 (typeof afterEach === 'function' && !process.env.STL_SKIP_AUTO_CLEANUP) { - afterEach(async () => { - await act() - cleanup() - }) -} - -// export all base queries, screen, etc. -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, fireEvent } from './pure.js' -export { cleanup, render } from './svelte5.js' diff --git a/src/svelte5.js b/src/svelte5.js deleted file mode 100644 index a8dd494..0000000 --- a/src/svelte5.js +++ /dev/null @@ -1,30 +0,0 @@ -import { createClassComponent } from 'svelte/legacy' - -import { SvelteTestingLibrary } from './pure.js' - -class Svelte5TestingLibrary extends SvelteTestingLibrary { - svelteComponentOptions = [ - 'target', - 'props', - 'events', - 'context', - 'intro', - 'recover', - ] - - renderComponent(ComponentConstructor, componentOptions) { - const component = createClassComponent({ - ...componentOptions, - component: ComponentConstructor, - }) - - this.componentCache.add(component) - - return component - } -} - -const instance = new Svelte5TestingLibrary() - -export const render = instance.render.bind(instance) -export const cleanup = instance.cleanup.bind(instance) diff --git a/vite.config.js b/vite.config.js index b18c504..b165d41 100644 --- a/vite.config.js +++ b/vite.config.js @@ -1,28 +1,12 @@ -import path from 'node:path' - import { svelte } from '@sveltejs/vite-plugin-svelte' -import { VERSION as SVELTE_VERSION } from 'svelte/compiler' import { defineConfig } from 'vite' import { svelteTesting } from './src/vite.js' -const IS_SVELTE_5 = SVELTE_VERSION >= '5' - -const alias = [ - { - find: '@testing-library/svelte', - replacement: path.resolve( - __dirname, - IS_SVELTE_5 ? 'src/svelte5-index.js' : 'src/index.js' - ), - }, -] - // https://vitejs.dev/config/ export default defineConfig({ plugins: [svelte(), svelteTesting()], test: { - alias, environment: 'jsdom', setupFiles: ['./src/__tests__/_vitest-setup.js'], mockReset: true,