api.mdx

id	title	sidebar_label
api	API	API

• @testing-library/dom
• render
• cleanup
• act
• fireEvent

---

@testing-library/dom

This library re-exports everything from the DOM Testing Library (@testing-library/dom). See the documentation to see what goodies you can use.

📝 fireEvent is an async method when imported from @testing-library/svelte. This is because it calls tick which tells Svelte to apply any new changes to the DOM.

render

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

const {results} = render(YourComponent, {ComponentOptions}, {RenderOptions})

Component Options

These are the options you pass when instantiating your Svelte Component. Please refer to the Client-side component API.

📝 If the only option you're passing in is props, then you can just pass them in directly.

// With options.
const {results} = render(YourComponent, {
  target: MyTarget,
  props: {myProp: 'value'},
})

// Props only.
const {results} = render(YourComponent, {myProp: 'value'})

Render Options

Option	Description	Default
container	The HTML element the component is mounted into.	document.body
queries	Queries to bind to the container. See getQueriesForElement.	null

Results

Result	Description
container	The HTML element the component is mounted into.
component	The newly created Svelte component. Generally, this should only be used when testing exported functions, or when you're testing developer facing API's. Outside of said cases avoid using the component directly to build tests, instead of interacting with the rendered Svelte component, work with the DOM. Have a read of Avoid the Test User by Kent C. Dodds to understand the difference between the end user and developer user.
debug	Logs the container using prettyDom.
unmount	Unmounts the component from the target by calling component.$destroy().
rerender	Calls render again destroying the old component, and mounting the new component on the original target with any new options passed in.
...queries	Returns all query functions that are bound to the container. If you pass in query arguments than this will be those, otherwise all.

cleanup

You don't need to import or use this, it's done automagically for you!

Unmounts the component from the container and destroys the container.

📝 When you import anything from the library, this automatically runs after each test. If you'd like to disable this then set process.env.STL_SKIP_AUTO_CLEANUP to true or import dont-clean-up-after-each from the library.

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

afterEach(() => {
  cleanup()
}) // Default on import: runs it after each test.

render(YourComponent)

cleanup() // Or like this for more control.

act (async)

An async helper method that takes in a function or Promise that is immediately called/resolved, and then calls tick so all pending state changes are flushed, and the view now reflects any changes made to the DOM.

fireEvent (async)

Calls @testing-library/dom fireEvent. It is an async method due to calling tick which tells Svelte to flush all pending state changes, basically it updates the DOM to reflect the new changes.

Component

<script>
  let count = 0

  function handleClick() {
    count += 1
  }
</script>

<button on:click="{handleClick}">Count is {count}</button>

Test

import '@testing-library/jest-dom'

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

import Comp from '..'

test('count increments when button is clicked', async () => {
  const {getByText} = render(Comp)
  const button = getByText('Count is 0')

  // Option 1.
  await fireEvent.click(button)
  expect(button).toHaveTextContent('Count is 1')

  // Option 2.
  await fireEvent(
    button,
    new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
    }),
  )
  expect(button).toHaveTextContent('Count is 2')
})