Configuration
Configuration
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']}))
Configuration options:
defaultHidden
: The default value for the hidden
option used by
getByRole
. Defaults to false
.
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.
Default 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
testIdAttribute
: The attribute used by getByTestId
and related queries. Defaults to data-testid
.
getElementError
: A function that returns the error used when
getBy*
or getAllBy*
fail. Takes
the error message and container object as arguments.
// 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)
},
})
// setup-tests.js
import { configure } from '@testing-library/react'
configure({ testIdAttribute: 'data-my-test-id' })
// setup-tests.js
import { configure } from '@testing-library/cypress'
configure({ testIdAttribute: 'data-my-test-id' })