API

@testing-library/svelte 重新导出 @testing-library/dom 中的所有内容，以及

• 渲染
• act
• 清理
• fireEvent (异步)

render

使用 Svelte 将您的组件渲染到 DOM 中。默认情况下，组件将渲染到附加到 document.body 的 <div> 中。

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

const result = render(MyComponent, componentOptions, renderOptions)

组件选项

您可以自定义组件的创建和挂载方式。这些选项直接传递给 Svelte。

如果您只需要向组件发送道具，只要这些道具的名称与组件选项的名称不相同，就可以直接传递道具。

// 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')]]),
})

您最常需要的选项是

选项	描述	默认值
道具	传递给组件的道具。	N/A
上下文	一个包含上下文值的 Map，用于渲染组件。	N/A
目标	要将组件渲染到其中的 HTMLElement。	附加到 document.body 的 <div>

如果您指定了 target 选项，target 元素将 不会 自动附加到 document.body，并且它将用作 绑定查询 和 debug 的基本元素。

有关所有可用选项，请参考 Svelte 客户端组件 API 文档。

渲染选项

您还可以自定义 Svelte 测试库如何渲染您的组件。大多数情况下，您无需修改这些选项。

警告

在 @testing-library/[email protected] 之前，baseElement 选项名为 container。

选项	描述	默认值
baseElement	查询和 debug 的基本元素。	componentOptions.target ?? document.body
查询	自定义查询.	N/A

渲染结果

结果	描述
baseElement	用于查询的基本 DOM 元素。
组件	已挂载的 Svelte 组件。
容器	组件挂载到的 DOM 元素。
调试	使用 prettyDOM 记录元素。
重新渲染	更新组件的道具。
卸载	卸载并销毁组件。
...查询	绑定到 baseElement 的 查询函数。

baseElement

在 @testing-library/[email protected] 中添加

绑定查询的基准 DOM 元素。对应于 renderOptions.baseElement。如果您不使用 componentOptions.target 也不使用 renderOptions.baseElement，这将是 document.body。

container

组件挂载到的 DOM 元素。对应于 componentOptions.target。一般来说，避免直接使用 container 来查询元素；请改用 测试库查询。

提示

使用 container.firstChild 获取组件的第一个渲染元素。

警告

在 @testing-library/[email protected] 之前，container 设置为基本元素。在早期版本中，使用 container.firstChild.firstChild 获取组件的第一个渲染元素。

component

Svelte 组件实例。有关更多详细信息，请参见 Svelte 组件 API。

提示

避免使用 component，除非是测试面向开发者的 API，例如导出的函数。相反，与 DOM 进行交互。阅读 Kent C. Dodds 编写的 避免测试用户，了解 **最终用户** 和 **开发者用户** 之间的区别。

debug

使用 prettyDOM 记录 baseElement 或给定元素。

提示

如果您的 baseElement 是默认的 document.body，我们建议使用 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

更新组件的一个或多个道具，并等待 Svelte 更新。

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

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

警告

在 @testing-library/[email protected] 之前，调用 rerender 会销毁并重新挂载组件。在早期版本中，使用 component.$set 和 act 来更新道具

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

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

unmount

卸载并销毁 Svelte 组件。

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

unmount()

查询

绑定到 baseElement 的 查询函数。如果您将 自定义查询 传递给 render，这些查询将可用，而不是默认查询。

提示

如果您的 baseElement 是默认的 document.body，我们建议使用 screen 而不是绑定查询。

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

销毁所有组件，并删除添加到 document.body 的所有元素。

信息

如果您的测试框架添加了全局 afterEach 方法（例如 Mocha、Jest 或 Jasmine），或者如果您在 Vitest 设置文件 中使用 import '@testing-library/svelte/vitest'，则会自动调用 cleanup。通常，您无需自己调用 cleanup。

如果您想在使用全局 afterEach 方法的框架中禁用自动清理，请设置 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

确保 Svelte 的所有挂起更新都应用于 DOM。您可以选择传递一个函数，该函数将在应用更新之前被调用。如果该函数返回一个 Promise，则该 Promise 会先被解析。

使用 Svelte 的 tick 方法应用更新。

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

const {component} = render(MyComponent)

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

fireEvent (异步)

触发事件，并等待 Svelte 更新 DOM。DOM 测试库的 fireEvent 的异步包装器。

提示

在可能的情况下，我们建议使用 @testing-library/user-event，而不是 fireEvent。

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

render(MyComponent)

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