api.mdx

id	title	sidebar_label
api	API	API

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

• render
• act
• cleanup
• fireEvent (async)

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:

Option	Description	Default
props	Props to pass to the component.	N/A
context	A Map of context values to render the component with.	N/A
target	An 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/[email protected], the baseElement option was named container.

:::

Option	Description	Default
baseElement	The base element for queries and debug.	componentOptions.target ?? document.body
queries	Custom Queries.	N/A

Render Results

Result	Description
baseElement	The base DOM element used for queries.
component	The mounted Svelte component.
container	The DOM element the component is mounted to.
debug	Log elements using prettyDOM.
rerender	Update the component's props.
unmount	Unmount and destroy the component.
...queries	Query functions bound to baseElement.

baseElement

Added in @testing-library/[email protected]

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/[email protected], 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/[email protected], 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)