Skip to main content

Configuration Options

Introduction​

The library can be configured via the configure function, which accepts:

  • a plain JS object; this will be merged into the existing configuration. e.g. configure({testIdAttribute: 'not-data-testid'})
  • a function; the function will be given the existing configuration, and should return a plain JS object which will be merged as above, e.g. configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))

Note

Framework-specific wrappers like React Testing Library may add more options to the ones shown below.

setup-tests.js
import {configure} from '@testing-library/dom'
import serialize from 'my-custom-dom-serializer'

configure({
  testIdAttribute: 'data-my-test-id',
  getElementError: (message, container) => {
    const customMessage = [message, serialize(container.firstChild)].join(
      '\n\n',
    )
    return new Error(customMessage)
  },
})

Options​

computedStyleSupportsPseudoElements​

Set to true if window.getComputedStyle supports pseudo-elements i.e. a second argument. If you're using testing-library in a browser you almost always want to set this to true. Only very old browser don't support this property (such as IE 8 and earlier). However, jsdom does not support the second argument currently. This includes versions of jsdom prior to 16.4.0 and any version that logs a not implemented warning when calling getComputedStyle with a second argument e.g. window.getComputedStyle(document.createElement('div'), '::after'). Defaults to false

defaultHidden​

The default value for the hidden option used by getByRole. Defaults to false.

defaultIgnore​

The default value for the ignore option used by getByText. Also determines the nodes that are being ignored when errors are printed.

Defaults to script, style.

showOriginalStackTrace​

By default, waitFor will ensure that the stack trace for errors thrown by Testing Library is cleaned up and shortened so it's easier for you to identify the part of your code that resulted in the error (async stack traces are hard to debug). If you want to disable this, then setshowOriginalStackTrace to false. You can also disable this for a specific call in the options you pass to waitFor.

throwSuggestions (experimental)​

When enabled, if better queries are available, the test will fail and provide a suggested query to use instead. Defaults to false.

To disable a suggestion for a single query just add {suggest:false} as an option.

screen.getByTestId('foo', {suggest: false}) // will not throw a suggestion
note

When this option is enabled, it may provide suggestions that lack an intuitive implementation. Typically this happens for roles which cannot be named, most notably paragraphs. For instance, if you attempt to use getByText, you may encounter the following error:

TestingLibraryElementError: A better query is available, try this:
    getByRole('paragraph')

However, there is no direct way to query paragraphs using the config object parameter, such as in getByRole('paragraph', { name: 'Hello World' }).

To address this issue, you can leverage a custom function to validate the element's structure, as shown in the example below. More information can be found in the GitHub issue

getByRole('paragraph', {
  name: (_, element) => element.textContent === 'Hello world',
})

testIdAttribute​

The attribute used by getByTestId and related queries. Defaults to data-testid.

getElementError​

A function that returns the error used when get or find queries fail. Takes the error message and container object as arguments.

asyncUtilTimeout​

The global timeout value in milliseconds used by waitFor utilities. Defaults to 1000ms.