@testing-library/svelte-core

Do you want to build your own Svelte testing library? You may want to use our rendering core, which abstracts away differences in Svelte versions to provide a simple API to render Svelte components into the document and clean them up afterwards.

Table of Contents

• Example Usage
• API
  • render
  • setup
  • wrapperSetup
  • mount
  • cleanup
  • addCleanupTask
  • removeCleanupTask
  • Utility types

Example Usage

import { beforeEach } from 'vitest'
import * as SvelteCore from '@testing-library/svelte-core'
import type {
  Component,
  Exports,
  Rerender,
} from '@testing-library/svelte-core/types'

import { bindQueries, type Queries } from './bring-your-own-queries.js'

beforeEach(async () => {
  // Required to use the `wrapper` render option
  await SvelteCore.wrapperSetup()
  SvelteCore.cleanup()
})

export interface RenderResult<C extends Component> extends Queries {
  container: HTMLElement
  component: Exports<C>
  rerender: Rerender<C>
  unmount: () => void
}

export const render = <C extends SvelteCore.Component>(
  Component: SvelteCore.ComponentImport<C>,
  options: SvelteCore.ComponentOptions<C>
): RenderResult<C> => {
  const { baseElement, component, container, rerender, unmount } =
    SvelteCore.render(Component, options)

  const queries = bindQueries(baseElement)

  return { component, container, rerender, unmount, ...queries }
}

API

render

Set up the document and mount a component into that document.

const { baseElement, container, component, rerender, unmount } = render(
  Component,
  componentOptions,
  setupOptions
)

| Argument | Type | Description | | ------------------ | ------------------------------------------------------- | ------------------------------------------------------- | | Component | Svelte component | An imported Svelte component | | componentOptions | Props or partial mount options | Options for how the component will be mounted | | setupOptions | SetupOptions | Optionally override baseElement or wrap the component |

| Result | Type | Description | Default | | ------------- | ------------------------------------------ | -------------------------------------------------- | ----------------------------------- | | baseElement | HTMLElement | The base element | document.body | | container | HTMLElement | The component's immediate parent element | <div> appended to document.body | | component | component exports | The component's exports from mount | N/A | | wrapper | component exports | The wrapper's exports, if a wrapper was provided | undefined | | rerender | (props: Partial<Props>) => Promise<void> | Update the component's props | N/A | | unmount | () => void | Unmount the component from the document | N/A |

[!TIP] Calling render is equivalent to calling setup followed by mount

const { baseElement, container, mountOptions } = setup(
  componentOptions,
  setupOptions
)
const { component, rerender, unmount } = mount(
  Component,
  mountOptions,
  setupOptions
)

setup

Validate options and prepare document elements for rendering.

const { baseElement, container, mountOptions } = setup(
  componentOptions,
  setupOptions
)

| Argument | Type | Description | | ------------------ | ------------------------------------------------------- | --------------------------------------------- | | componentOptions | Props or partial mount options | Options for how the component will be mounted | | setupOptions | SetupOptions | Configure the document and wrap the component |

setupOptions accepts the following fields, all optional:

| Field | Type | Description | Default | | -------------- | ----------------------------------------- | --------------------------------------------------------------------- | --------------- | | baseElement | HTMLElement | The base element to bind queries to | document.body | | wrapper | Svelte component | A component to wrap the component under test, e.g. a context provider | undefined | | wrapperProps | Props | Props to pass to the wrapper component | undefined |

[!IMPORTANT] Using the wrapper option requires awaiting wrapperSetup beforehand, e.g. in a beforeEach hook.

| Result | Type | Description | Default | | -------------- | ------------------------------------ | ---------------------------------------- | ----------------------------------- | | baseElement | HTMLElement | The base element | document.body | | container | HTMLElement | The component's immediate parent element | <div> appended to document.body | | mountOptions | mount options | Validated options to pass to mount | { target, props: {} } |

wrapperSetup

Load the wrapper scaffold for the installed version of Svelte. Await this before rendering with the wrapper option, e.g. in a beforeEach hook. Rendering with a wrapper before wrapperSetup resolves throws a WrapperNotSetupError.

await wrapperSetup()

The scaffold is loaded once and cached, so calling wrapperSetup repeatedly is cheap.

mount

Mount a Svelte component into the document.

const { component, wrapper, unmount, rerender } = mount(
  Component,
  mountOptions,
  setupOptions
)

| Argument | Type | Description | | -------------- | ----------------------------------------- | --------------------------------------------------------- | | Component | Svelte component | An imported Svelte component | | mountOptions | component options | Options to pass to Svelte's mount function | | setupOptions | SetupOptions | Optionally wrap the component (wrapper, wrapperProps) |

| Result | Type | Description | | ----------- | ------------------------------------------ | -------------------------------------------------- | | component | component exports | The component's exports from mount | | wrapper | component exports | The wrapper's exports, if a wrapper was provided | | unmount | () => void | Unmount the component from the document | | rerender | (props: Partial<Props>) => Promise<void> | Update the component's props |

cleanup

Cleanup rendered components and added elements. Call this when your tests are over.

cleanup()

addCleanupTask

Add a custom cleanup task to be called with cleanup()

addCleanupTask(() => {
  // ...reset something
})

removeCleanupTask

Remove a cleanup task from cleanup(). Useful if a cleanup task can only be run once and may be run outside of cleanup

const customCleanup = () => {
  // ...reset something
}

addCleanupTask(customCleanup)

const manuallyCleanupEarly = () => {
  customCleanup()
  removeCleanupTask(customCleanup)
}

Utility types

This module exports various utility types from @testing-library/svelte-core/types. They adapt to whatever Svelte version is installed, and can be used to get type signatures for imported components, props, exports, etc.

See ./types.d.ts for the full list of available types.