Configuration

function configure(configDelta: ConfigFn | Partial<Config>): void;

type ConfigFn = (existingConfig: Config) => Partial<Config>;

interface Config {
  testIdAttribute: string;  // Default: 'data-testid'
  asyncUtilTimeout: number;  // Default: 1000ms
  computedStyleSupportsPseudoElements: boolean;
  defaultHidden: boolean;  // Default: false
  defaultIgnore: string;
  showOriginalStackTrace: boolean;  // Default: false
  throwSuggestions: boolean;  // Default: false
  asyncWrapper(cb: (...args: any[]) => any): Promise<any>;
  eventWrapper(cb: (...args: any[]) => any): void;
  getElementError: (message: string | null, container: Element) => Error;
  unstable_advanceTimersWrapper(cb: (...args: unknown[]) => unknown): unknown;
}

import {configure} from '@testing-library/dom';

// Change test ID attribute
configure({testIdAttribute: 'data-test-id'});

// Increase async timeout
configure({asyncUtilTimeout: 5000});

// Multiple options
configure({
  testIdAttribute: 'data-cy',
  asyncUtilTimeout: 3000,
  showOriginalStackTrace: true
});

// Function form
configure((existingConfig) => ({
  asyncUtilTimeout: existingConfig.asyncUtilTimeout * 2
}));

function getConfig(): Config;

import {getConfig, configure} from '@testing-library/dom';

// Get current config
const config = getConfig();
console.log('Test ID:', config.testIdAttribute);
console.log('Timeout:', config.asyncUtilTimeout);

// Use current config for changes
const currentTimeout = getConfig().asyncUtilTimeout;
configure({asyncUtilTimeout: currentTimeout * 2});

configure({testIdAttribute: 'data-test-id'});
const button = screen.getByTestId('submit');  // Looks for data-test-id

configure({asyncUtilTimeout: 5000});
const element = await screen.findByText('Content');  // Waits up to 5s

configure({defaultHidden: true});
const element = screen.getByRole('button');  // Includes hidden buttons

// Override per query
const visible = screen.getByRole('button', {hidden: false});

configure({
  defaultIgnore: 'script, style, [aria-hidden="true"]'
});

configure({showOriginalStackTrace: true});

configure({throwSuggestions: true});
try {
  screen.getByTestId('button');
} catch (error) {
  // Error includes suggestion to use getByRole
}

// test-utils.js
import {configure} from '@testing-library/dom';

configure({
  testIdAttribute: 'data-testid',
  asyncUtilTimeout: 3000,
  showOriginalStackTrace: true,
  throwSuggestions: true
});

const isCI = process.env.CI === 'true';

configure({
  asyncUtilTimeout: isCI ? 5000 : 1000,
  showOriginalStackTrace: !isCI,
  throwSuggestions: !isCI
});

test('slow test', async () => {
  const originalTimeout = getConfig().asyncUtilTimeout;
  
  configure({asyncUtilTimeout: 10000});
  
  // ... test code
  
  configure({asyncUtilTimeout: originalTimeout});
});