@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
  • 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(() => {
  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 | { baseElement?: HTMLElement } | Optionally override baseElement |

| 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 | | 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)

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 | { baseElement?: HTMLElement } | Optionally override baseElement |

| 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: {} } |

mount

Mount a Svelte component into the document.

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

| Argument | Type | Description | | -------------- | ----------------------------------------- | -------------------------------------------- | | Component | Svelte component | An imported Svelte component | | mountOptions | component options | Options to pass to Svelte's mount function |

| Result | Type | Description | | ----------- | ------------------------------------------ | --------------------------------------- | | component | component exports | The component's exports from mount | | 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.