Skip to main content

API

@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​

OptionDescriptionDefault
containerThe HTML element the component is mounted into.document.body
queriesQueries to bind to the container. See within.null

Results​

ResultDescription
containerThe HTML element the component is mounted into.
componentThe 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.
debugLogs the container using prettyDom.
unmountUnmounts the component from the target by calling component.$destroy().
rerenderCalls render again destroying the old component, and mounting the new component on the original target with any new options passed in.
...queriesReturns 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, screen} from '@testing-library/svelte'

import Comp from '..'

test('count increments when button is clicked', async () => {
  render(Comp)
  const button = screen.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')
})