API

[Traduction Bêta Non Officielle]

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

@testing-library/svelte réexporte tous les éléments de @testing-library/dom, ainsi que :

• render

• act

• cleanup

• fireEvent (async)

render

Rend votre composant dans le DOM avec Svelte. Par défaut, le composant sera rendu dans une <div> ajoutée à document.body.

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

const result = render(MyComponent, componentOptions, renderOptions)

Options du composant

Vous pouvez personnaliser la création et le montage du composant. Ces options sont transmises directement à Svelte.

Si vous devez uniquement envoyer des props à votre composant, vous pouvez les passer directement, à condition qu'elles ne portent pas le même nom qu'une option de composant.

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

Les options les plus couramment utilisées sont :

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

Si vous spécifiez l'option target, l'élément target ne sera pas ajouté automatiquement à document.body, et servira d'élément de base pour les requêtes liées et debug.

Consultez la documentation de l'API des composants côté client Svelte pour toutes les options disponibles.

Options de rendu

Vous pouvez également personnaliser la manière dont Svelte Testing Library rend votre composant. La plupart du temps, vous ne devriez pas avoir besoin de modifier ces options.

attention

Avant @testing-library/svelte@5.0.0, l'option baseElement s'appelait container.

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

Résultats du rendu

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

Ajouté dans @testing-library/svelte@5.0.0

L'élément DOM de base auquel les requêtes sont liées. Correspond à renderOptions.baseElement. Si vous n'utilisez ni componentOptions.target ni renderOptions.baseElement, ce sera document.body.

container

L'élément DOM dans lequel le composant est monté. Correspond à componentOptions.target. En général, évitez d'utiliser container directement pour interroger des éléments ; utilisez plutôt les requêtes de testing-library.

astuce

Utilisez container.firstChild pour obtenir le premier élément rendu de votre composant.

attention

Avant @testing-library/svelte@5.0.0, container correspondait à l'élément de base. Utilisez container.firstChild.firstChild pour obtenir le premier élément rendu du composant dans les versions antérieures.

component

L'instance du composant Svelte. Voir la documentation de l'API des composants Svelte pour plus de détails.

astuce

Évitez d'utiliser component sauf pour tester des API destinées aux développeurs, comme des fonctions exportées. Interagissez plutôt avec le DOM. Lisez Avoid the Test User de Kent C. Dodds pour comprendre la différence entre l'utilisateur final et l'utilisateur développeur.

debug

Journalise le baseElement ou un élément donné en utilisant prettyDOM.

astuce

Si votre baseElement est le document.body par défaut, nous recommandons d'utiliser 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

Met à jour une ou plusieurs propriétés du composant et attend la mise à jour par Svelte.

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

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

attention

Avant @testing-library/svelte@5.0.0, appeler rerender détruisait et remontait le composant. Utilisez component.$set avec act pour mettre à jour les propriétés dans les versions antérieures :

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

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

unmount

Démonte et détruit le composant Svelte.

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

unmount()

Requêtes

Les fonctions de requête liées au baseElement. Si vous avez passé des requêtes personnalisées à render, celles-ci seront disponibles à la place des requêtes par défaut.

astuce

Si votre baseElement est le document.body par défaut, nous recommandons d'utiliser screen plutôt que les requêtes liées.

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

Détruit tous les composants et supprime les éléments ajoutés à document.body.

info

cleanup est appelé automatiquement si votre framework de test ajoute une méthode globale afterEach (ex. Mocha, Jest ou Jasmine), ou si vous utilisez import '@testing-library/svelte/vitest' dans votre fichier de configuration Vitest. Généralement, vous ne devriez pas avoir besoin d'appeler cleanup manuellement.

Pour désactiver le nettoyage automatique dans un framework utilisant une méthode globale afterEach, définissez 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

Garantit que toutes les mises à jour en attente de Svelte sont appliquées au DOM. Optionnellement, vous pouvez passer une fonction à exécuter avant l'application des mises à jour. Si la fonction retourne une Promise, celle-ci sera résolue au préalable.

Utilise la méthode tick de Svelte pour appliquer les mises à jour.

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

const {component} = render(MyComponent)

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

fireEvent (async)

Déclenche un événement et attend la mise à jour du DOM par Svelte. Un wrapper asynchrone de fireEvent de DOM Testing Library.

astuce

Lorsque possible, nous recommandons @testing-library/user-event plutôt que fireEvent.

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

render(MyComponent)

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