Skip to main content

API

@testing-library/svelte re-exports everything from @testing-library/dom, as well as:

render​

Render your component to the DOM with Svelte. By default, the component will be rendered into a <div> appended to document.body.

import {render} from '@testing-library/svelte'
import MyComponent from './MyComponent.svelte'

const result = render(MyComponent, componentOptions, renderOptions)

Component Options​

You may customize how the component is created and mounted. These options are passed directly to Svelte.

If you only need to send props to your component, you may pass props directly, as long as those props don't share a name with a component option.

// pass props to the component
render(YourComponent, {myProp: 'value'})

// pass props and other options to the component
render(YourComponent, {
 props: {myProp: 'value'},
 context: new Map([[('theme': 'dark')]]),
})

The most common options you will need are:

OptionDescriptionDefault
propsProps to pass to the component.N/A
contextA Map of context values to render the component with.N/A
targetAn HTMLElement to render the component into.<div> appended to document.body

If you specify the target option, the target element will not be appended to document.body automatically, and it will be used as the base element for bound queries and debug.

Refer to the Svelte client-side component API docs for all available options.

Render Options​

You may also customize how Svelte Testing Library renders your component. Most of the time, you shouldn't need to modify these options.

caution

Prior to @testing-library/svelte@5.0.0, the baseElement option was named container.

OptionDescriptionDefault
baseElementThe base element for queries and debug.componentOptions.target ?? document.body
queriesCustom Queries.N/A

Render Results​

ResultDescription
baseElementThe base DOM element used for queries.
componentThe mounted Svelte component.
containerThe DOM element the component is mounted to.
debugLog elements using prettyDOM.
rerenderUpdate the component's props.
unmountUnmount and destroy the component.
...queriesQuery functions bound to baseElement.

baseElement​

Added in @testing-library/svelte@5.0.0

The base DOM element that queries are bound to. Corresponds to renderOptions.baseElement. If you do not use componentOptions.target nor renderOptions.baseElement, this will be document.body.

container​

The DOM element the component is mounted in. Corresponds to componentOptions.target. In general, avoid using container directly to query for elements; use testing-library queries instead.

tip

Use container.firstChild to get the first rendered element of your component.

caution

Prior to @testing-library/svelte@5.0.0, container was set to the base element. Use container.firstChild.firstChild to get the first rendered element of the component in earlier versions.

component​

The Svelte component instance. See the Svelte component API for more details.

tip

Avoid using component except to test developer-facing APIs, like exported functions. Instead, interact with the DOM. Read Avoid the Test User by Kent C. Dodds to understand the difference between the end user and developer user.

debug​

Log the baseElement or a given element using prettyDOM.

tip

If your baseElement is the default document.body, we recommend using screen.debug.

import {render, screen} from '@testing-library/svelte'

const {debug} = render(MyComponent, {myProp: 'value'})

const button = screen.getByRole('button')

// log `document.body`
screen.debug()

// log your custom `target` or `baseElement`
debug()

// log a specific element
screen.debug(button)
debug(button)

rerender​

Update one or more of the component's props and wait for Svelte to update.

const {rerender} = render(MyComponent, {myProp: 'value'})

await rerender({myProp: 'new value'}))
caution

Prior to @testing-library/svelte@5.0.0, calling rerender would destroy and remount the component. Use component.$set and act to update props in earlier versions:

const {component} = render(MyComponent, {myProp: 'value'})

await act(() => component.$set({myProp: 'new value'}))

unmount​

Unmount and destroy the Svelte component.

const {unmount} = render(MyComponent, {myProp: 'value'})

unmount()

Queries​

Query functions bound to the baseElement. If you passed custom queries to render, those will be available instead of the default queries.

tip

If your baseElement is the default document.body, we recommend using screen rather than bound queries.

import {render, screen} from '@testing-library/svelte'

const {getByRole} = render(MyComponent, {myProp: 'value'})

// query `document.body`
const button = screen.getByRole('button')

// query using a custom `target` or `baseElement`
const button = getByRole('button')

cleanup​

Destroy all components and remove any elements added to document.body.

info

cleanup is called automatically if your testing framework adds a global afterEach method (e.g. Mocha, Jest, or Jasmine), or if you use import '@testing-library/svelte/vitest' in your Vitest setup file. Usually, you shouldn't need to call cleanup yourself.

If you'd like to disable automatic cleanup in a framework that uses a global afterEach method, set process.env.STL_SKIP_AUTO_CLEANUP.

import {render, cleanup} from '@testing-library/svelte'

// Default: runs after each test
afterEach(() => {
 cleanup()
})

render(YourComponent)

// Called manually for more control
cleanup()

act​

Ensure all pending updates from Svelte are applied to the DOM. Optionally, you may pass a function to be called before updates are applied. If the function returns a Promise, it will be resolved first.

Uses Svelte's tick method to apply updates.

import {act, render} from '@testing-library/svelte'

const {component} = render(MyComponent)

await act(() => {
 component.updateSomething()
})

fireEvent (async)​

Fire an event and wait for Svelte to update the DOM. An asynchronous wrapper of DOM Testing Library's fireEvent.

tip

Where possible, we recommend @testing-library/user-event instead of fireEvent.

import {fireEvent, render, screen} from '@testing-library/svelte'

render(MyComponent)

const button = screen.getByRole('button')
await fireEvent.click(button)