The problem

You want to write maintainable tests for your Preact components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

This solution

The preact-testing-library is a very light-weight solution for testing Preact components. It provides light utility functions on top of preact in a way that encourages better testing practices. It's primary guiding principle is:

[The more your tests resemble the way your software is used, the more confidence they can give you.][guiding-principle]

So rather than dealing with instances of rendered Preact components, your tests will work with actual DOM nodes. The utilities this library provides facilitate querying the DOM in the same way the user would. Finding for elements by their label text (just like a user would), finding links and buttons from their text (like a user would). It also exposes a recommended way to find elements by a data-testid as an "escape hatch" for elements where the text content and label do not make sense or is not practical.

This library encourages your applications to be more accessible and allows you to get your tests closer to using your components the way a user will, which allows your tests to give you more confidence that your application will work when a real user uses it.

This library is a replacement for enzyme. While you can follow these guidelines using enzyme itself, enforcing this is harder because of all the extra utilities that enzyme provides (utilities which facilitate testing implementation details). Read more about this in the FAQ below.

What this library is not:

1. A test runner or framework
2. Specific to a testing framework (though we recommend Jest as our preference, the library works with any framework)

NOTE: This library is built on top of dom-testing-library which is where most of the logic behind the queries is. Also this is inspired from react-testing-library

Table of Contents

• Installation
• Usage
  • render
  • cleanup
  • wait
  • fireEvent(node: HTMLElement, event: Event)
• debounceRenderingOff
• TextMatch
• query APIs
• FAQ
• Guiding Principles

Installation

This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's devDependencies:

npm install --save-dev preact-testing-library

You may also be interested in installing dom-testing-library so you can use the custom jest matchers

Usage

// __tests__/fetch.js
import preact from 'preact'
import {render, flushPromises, FireEvent} from '../'
import axiosMock from 'axios' // the mock lives in a __mocks__ directory
import Fetch from '../fetch' // see the tests for a full implementation

test('Fetch makes an API call and displays the greeting when load-greeting is clicked', async () => {
  // Arrange
  axiosMock.get.mockImplementationOnce(() =>
    Promise.resolve({
      data: {greeting: 'hello there'},
    }),
  )
  const url = '/greeting'
  const {getByText} = render(<Fetch url={url} />)

  // Act
  FireEvent.fireEvent(getByText('Fetch'), 'click')

  await flushPromises()

  // Assert
  expect(axiosMock.get).toHaveBeenCalledTimes(1)
  expect(axiosMock.get).toHaveBeenCalledWith(url)
  // this assertion is funny because if the textContent were not "hello there"
  // then the `getByText` would throw anyway... 🤔
  expect(getByText('hello there').textContent).toBe('hello there')
  // expect(container.firstChild).toMatchSnapshot()
})

render

Render into a container which is appended to document.body. It should be used with cleanup:

import {render, cleanup} from 'preact-testing-library'

afterEach(cleanup)

render(<div />)

In the example above, the render method returns an object that has a few properties:

container

The containing DOM node of your rendered Preact Element (rendered using Preact.render). It's a div. This is a regular DOM node, so you can call container.querySelector etc. to inspect the children.

Tip: To get the root element of your rendered element, use container.firstChild.

debug

This method is a shortcut for console.log(prettyDOM(container)).

import {render} from 'preact-testing-library'

const HelloWorld = () => <h1>Hello World</h1>
const {debug} = render(<HelloWorld />)
debug()
// <div>
//   <h1>Hello World</h1>
// </div>
// you can also pass an element: debug(getByTestId('messages'))

This is a simple wrapper around prettyDOM which is also exposed and comes from dom-testing-library.

rerender

It'd probably be better if you test the component that's doing the prop updating to ensure that the props are being updated correctly (see the Guiding Principles section). That said, if you'd prefer to update the props of a rendered component in your test, this function can be used to update props of the rendered component.

import {render} from 'preact-testing-library'

const {rerender} = render(<NumberDisplay number={1} />)

// re-render the same component with different props
rerender(<NumberDisplay number={2} />)

unmount

This will cause the rendered component to be unmounted. This is useful for testing what happens when your component is removed from the page (like testing that you don't leave event handlers hanging around causing memory leaks).

This method is a pretty small abstraction over render(ui, document.body, container)

const {container, unmount} = render(<Login />)
unmount()
// your component has been unmounted and now: container.innerHTML === ''

getByLabelText(text: TextMatch, options: {selector: string = '*'}): HTMLElement

This will search for the label that matches the given TextMatch, then find the element associated with that label.

const inputNode = getByLabelText('Username')

// this would find the input node for the following DOM structures:
// The "for" attribute (NOTE: in JSX with React you'll write "htmlFor" rather than "for")
// <label for="username-input">Username</label>
// <input id="username-input" />
//
// The aria-labelledby attribute
// <label id="username-label">Username</label>
// <input aria-labelledby="username-label" />
//
// Wrapper labels
// <label>Username <input /></label>
//
// It will NOT find the input node for this:
// <label><span>Username</span> <input /></label>
//
// For this case, you can provide a `selector` in the options:
const inputNode = getByLabelText('username', {selector: 'input'})
// and that would work
// Note that <input aria-label="username" /> will also work, but take
// care because this is not a label that users can see on the page. So
// the purpose of your input should be obvious for those users.

Note: This method will throw an error if it cannot find the node. If you don't want this behavior (for example you wish to assert that it doesn't exist), then use queryByLabelText instead.

getByPlaceholderText(text: TextMatch): HTMLElement

This will search for all elements with a placeholder attribute and find one that matches the given TextMatch.

// <input placeholder="Username" />
const inputNode = getByPlaceholderText('Username')

NOTE: a placeholder is not a good substitute for a label so you should generally use getByLabelText instead.

getByText(text: TextMatch): HTMLElement

This will search for all elements that have a text node with textContent matching the given TextMatch.

// <a href="/about">About ℹ️</a>
const aboutAnchorNode = getByText('about')

getByAltText(text: TextMatch): HTMLElement

This will return the element (normally an <img>) that has the given alt text. Note that it only supports elements which accept an alt attribute: <img>, <input>, and <area> (intentionally excluding <applet> as it's deprecated).

// <img alt="Incredibles 2 Poster" src="/incredibles-2.png" />
const incrediblesPosterImg = getByAltText(/incredibles.*poster$/i)

getByTestId(text: TextMatch): HTMLElement

A shortcut to container.querySelector(`[data-testid="${yourId}"]`) (and it also accepts a TextMatch).

// <input data-testid="username-input" />
const usernameInputElement = getByTestId('username-input')

In the spirit of the guiding principles, it is recommended to use this only after getByLabel, getByPlaceholderText or getByText don't work for your use case. Using data-testid attributes do not resemble how your software is used and should be avoided if possible. That said, they are way better than querying based on DOM structure. Learn more about data-testids from the blog post ["Making your UI tests resilient to change"][data-testid-blog-post]

cleanup

Unmounts Preact trees that were mounted with render.

afterEach(cleanup)

test('renders into document', () => {
  render(<div>)
  // ...
})

Failing to call cleanup when you've called render could result in a memory leak and tests which are not idempotent (which can lead to difficult to debug errors in your tests).

wait

Defined as:

function wait(
  callback?: () => void,
  options?: {
    timeout?: number
    interval?: number
  },
): Promise<void>

When in need to wait for non-deterministic periods of time you can use wait, to wait for your expectations to pass. The wait function is a small wrapper around the wait-for-expect module. Here's a simple example:

// ...
// wait until the callback does not throw an error. In this case, that means
// it'll wait until we can get a form control with a label that matches "username"
await wait(() => getByLabelText('username'))
getByLabelText('username').value = 'chucknorris'
// ...

This can be useful if you have a unit test that mocks API calls and you need to wait for your mock promises to all resolve. This can also be useful when (for example) you integration test your apollo-connected Preact components that go a couple level deep, with queries fired up in consequent components.

The default callback is a no-op function (used like await wait()). This can be helpful if you only need to wait for one tick of the event loop.

The default timeout is 4500ms which will keep you under Jest's default timeout of 5000ms.

The default interval is 50ms. However it will run your callback immediately on the next tick of the event loop (in a setTimeout) before starting the intervals.

fireEvent(node: HTMLElement, event: Event)

Fire DOM events.

You can fire events directly to your DOM. You can render into the document using the render utility.

import {cleanup, render, fireEvent} from 'preact-testing-library'

// don't forget to clean up the document.body
afterEach(cleanup)

test('clicks submit button', () => {
  const spy = jest.fn()
  const {getByText} = render(<button onClick={spy}>Submit</button>)

  fireEvent(
    getByText('Submit'),
    new MouseEvent('click', {
      bubbles: true, // click events must bubble for React to see it
      cancelable: true,
    }),
  )

  expect(spy).toHaveBeenCalledTimes(1)
})

fireEvent[eventName](node: HTMLElement, eventProperties: Object)

Convenience methods for firing DOM events. Check out dom-testing-library/src/events.js for a full list as well as default eventProperties.

// similar to the above example
// click will bubble for React to see it
const rightClick = {button: 2}
fireEvent.click(getElementByText('Submit'), rightClick)
// default `button` property for click events is set to `0` which is a left click.

debounceRenderingOff

Preact setState is debounced, which means any call setState, you have to use wait or flushPromise API to assert. However, there is a handy method for this debounceRenderingOff.

You can invoke this debounceRenderingOff to turn off the debounce feature of Preact.

test('testing different types of events with debounce off', () => {
  debounceRenderingOff() //turns off the debounce, no need for any waits!
  const {getByTestId, getByText, queryByText} = render(<MyForm />)
  const checkBox = getByTestId('checkbox')

  // Act
  fireEvent.click(checkBox)
  const textbox = getByTestId('textbox')
  textbox.value = 'test value'
  fireEvent.change(textbox)

  // Assert
  expect(queryByText('No')).not.toBeInTheDOM()
  expect(getByText('Yes')).toBeInTheDOM()
  expect(getByText('test value')).toBeInTheDOM()
})

TextMatch

Several APIs accept a TextMatch which can be a string, regex or a function which returns true for a match and false for a mismatch.

Here's an example

// <div>Hello World</div>
// all of the following will find the div
getByText('Hello World') // full match
getByText('llo worl') // substring match
getByText('hello world') // strings ignore case
getByText(/Hello W?oRlD/i) // regex
getByText((content, element) => content.startsWith('Hello')) // function

// all of the following will NOT find the div
getByText('Goodbye World') // non-string match
getByText(/hello world/) // case-sensitive regex with different case
// function looking for a span when it's actually a div
getByText((content, element) => {
  return element.tagName.toLowerCase() === 'span' && content.startsWith('Hello')
})

query APIs

Each of the get APIs listed in the render section above have a complimentary query API. The get APIs will throw errors if a proper node cannot be found. This is normally the desired effect. However, if you want to make an assertion that an element is not present in the DOM, then you can use the query API instead:

const submitButton = queryByText('submit')
expect(submitButton).toBeNull() // it doesn't exist

Feel free to contribute more!

FAQ

expect(queryByTestId('thing-that-does-not-exist')).toBeNull()

const firstLiInDiv = container.querySelector('div li')
const allLisInDiv = container.querySelectorAll('div li')
const rootElement = container.firstChild

const thirdLiInUl = container.querySelector('ul > li:nth-child(3)')

<li data-testid={`item-${item.id}`}>{item.text}</li>

const items = [
  /* your items */
]
const {getByTestId} = render(/* your component with the items */)
const thirdItem = getByTestId(`item-${items[2].id}`)

Guiding Principles

[The more your tests resemble the way your software is used, the more confidence they can give you.][guiding-principle]

We try to only expose methods and utilities that encourage you to write tests that closely resemble how your Preact components are used.

Utilities are included in this project based on the following guiding principles:

1. If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
2. It should be generally useful for testing individual Preact components or full Preact applications. While this library is focused on the actual dom, utilities could be included even if they don't directly relate to the actual dom.
3. Utility implementations and APIs should be simple and flexible.

At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.