API

@testing-library/svelte 重新匯出所有來自 @testing-library/dom 的內容，以及

• render
• act
• cleanup
• fireEvent (async)

render

使用 Svelte 將您的元件渲染到 DOM 中。預設情況下，元件將被渲染到附加到 document.body 的 <div> 中。

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

const result = render(MyComponent, componentOptions, renderOptions)

元件選項

您可以自訂元件的建立和掛載方式。這些選項將直接傳遞給 Svelte。

如果您只需要將 props 傳遞給您的元件，您可以直接傳遞 props，只要這些 props 不與元件選項共享名稱。

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

您最常需要使用的選項是

選項	描述	預設值
props	要傳遞給元件的 Props。	不適用
context	一個 Map 的上下文值，用於渲染元件。	不適用
target	一個 HTMLElement，用於將元件渲染到其中。	附加到 document.body 的 <div>

如果您指定 target 選項，target 元素將不會自動附加到 document.body，並且它將用作綁定查詢和debug的基礎元素。

有關所有可用選項，請參閱 Svelte 客戶端元件 API 文件。

渲染選項

您也可以自訂 Svelte 測試庫渲染元件的方式。大多數情況下，您不需要修改這些選項。

注意

在 @testing-library/svelte@5.0.0 之前，baseElement 選項被命名為 container。

選項	描述	預設值
baseElement	查詢和 debug 的基礎元素。	componentOptions.target ?? document.body
查詢	自訂查詢.	不適用

渲染結果

結果	描述
baseElement	用於查詢的基礎 DOM 元素。
component	掛載的 Svelte 元件。
container	元件掛載到的 DOM 元素。
debug	使用 prettyDOM 記錄元素。
rerender	更新元件的 props。
unmount	卸載並銷毀元件。
...queries	綁定到 baseElement 的 查詢函式。

baseElement

在 @testing-library/svelte@5.0.0 中新增

查詢綁定的基礎 DOM 元素。對應於 renderOptions.baseElement。如果您未使用 componentOptions.target 或 renderOptions.baseElement，則此值將為 document.body。

container

元件掛載到的 DOM 元素。對應於 componentOptions.target。一般來說，避免直接使用 container 查詢元素；請改用測試庫查詢。

提示

使用 container.firstChild 取得元件的第一個渲染元素。

注意

在 @testing-library/svelte@5.0.0 之前，container 被設定為基礎元素。在較早版本中，使用 container.firstChild.firstChild 取得元件的第一個渲染元素。

component

Svelte 元件實例。有關更多詳細資訊，請參閱 Svelte 元件 API。

提示

除非要測試開發人員面對的 API，例如匯出的函式，否則請避免使用 component。請改為與 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

更新元件的一個或多個 props，並等待 Svelte 更新。

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

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

注意

在 @testing-library/svelte@5.0.0 之前，呼叫 rerender 會銷毀並重新掛載元件。在較早版本中使用 component.$set 和 act 更新 props

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，則會先解析該函式。

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

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

const {component} = render(MyComponent)

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

fireEvent (async)

觸發事件並等待 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)