Skip to content

Latest commit

 

History

History
154 lines (114 loc) · 4.64 KB

api-configuration.mdx

File metadata and controls

154 lines (114 loc) · 4.64 KB
id title
api-configuration
Configuration Options

import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem'

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.

<Tabs defaultValue="native" values={[ { label: 'Native', value: 'native', }, { label: 'React', value: 'react', }, { label: 'Cypress', value: 'cypress', }, ] }> 

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)
  },
})
import {configure} from '@testing-library/react'

configure({testIdAttribute: 'data-my-test-id'})
import {configure} from '@testing-library/cypress'

configure({testIdAttribute: 'data-my-test-id'})

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.

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 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.

queryElement & queryAllElements

If your application requires a specific way to query elements on the page, you can define a custom strategy used by the testing library.

For that register your strategy once:

configure({
  queryElement: (element, query) => element.querySelector(query),
  queryAllElements: (element, query) => element.querySelectorAll(query),
})

Defaults to element.querySelector and element.querySelectorAll.

The interface of the functions will take two arguments, element and query, which the wrapper can use. The expected return value is a single element (for queryElement) or a list of elements (for queryAllElements).

This can be used to extend queries to reach into the shadow dom or iframes. An example using the query-selector-shadow-dom library looks like the following:

import {
  querySelectorAllDeep,
  querySelectorDeep,
} from 'query-selector-shadow-dom'
configure({
  queryElement: querySelectorDeep,
  queryAllElements: querySelectorAllDeep,
})