配置选项

简介

库可以通过 configure 函数配置，该函数接受

• 一个纯 JS 对象；这将被合并到现有配置中。例如 configure({testIdAttribute: 'not-data-testid'})
• 一个函数；该函数将获得现有配置，并应返回一个纯 JS 对象，该对象将如上合并，例如 configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))

注意

React Testing Library 等框架特定包装器可能会在下面显示的选项中添加更多选项。

原生

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)
  },
})

React

setup-tests.js

import {configure} from '@testing-library/react'

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

Angular

setup-tests.ts

import {configure} from '@testing-library/angular'

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

Cypress

setup-tests.js

import {configure} from '@testing-library/cypress'

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

选项

computedStyleSupportsPseudoElements

如果 window.getComputedStyle 支持伪元素，即第二个参数，则设置为 true。如果您在浏览器中使用测试库，则几乎总是希望将其设置为 true。只有非常旧的浏览器不支持此属性（例如 IE 8 及更早版本）。但是，jsdom 目前不支持第二个参数。这包括 16.4.0 之前的 jsdom 版本以及在调用 getComputedStyle 时使用第二个参数记录 not implemented 警告的任何版本，例如 window.getComputedStyle(document.createElement('div'), '::after')。默认值为 false

defaultHidden

由 getByRole 使用的 hidden 选项的默认值。默认值为 false。

defaultIgnore

由 getByText 使用的 ignore 选项 的默认值。还确定在打印错误时被忽略的节点。

默认值为 script, style。

showOriginalStackTrace

默认情况下，waitFor 将确保清理和缩短 Testing Library 抛出的错误的堆栈跟踪，以便您更容易识别导致错误的代码部分（异步堆栈跟踪难以调试）。如果您想禁用此功能，请将 showOriginalStackTrace 设置为 false。您也可以在传递给 waitFor 的选项中禁用特定调用的此功能。

throwSuggestions（实验性）

启用后，如果 更好的查询 可用，则测试将失败并提供建议的查询以供替代。默认值为 false。

要禁用单个查询的建议，只需添加 {suggest:false} 作为选项。

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

注意

启用此选项时，它可能会提供缺乏直观实现的建议。通常，这种情况发生在 无法命名的角色 中，最显着的是段落。例如，如果您尝试使用 getByText，您可能会遇到以下错误

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

但是，没有直接的方法可以使用配置对象参数查询段落，例如在 getByRole('paragraph', { name: 'Hello World' }) 中。

为了解决此问题，您可以利用自定义函数来验证元素的结构，如下面的示例所示。有关更多信息，请参见 GitHub 问题

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

testIdAttribute

由 getByTestId 及其相关查询使用的属性。默认值为 data-testid。

getElementError

当 get 或 find 查询 失败时返回错误的函数。接受错误消息和容器对象作为参数。

asyncUtilTimeout

waitFor 实用程序使用的全局超时值，以毫秒为单位。默认值为 1000 毫秒。