tessl/npm-testing-library--dom

Simple and complete DOM testing utilities that encourage good testing practices.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/npm-testing-library--dom
Author: tessl

Configure global library behavior including test ID attributes, async timeouts, and error handling.

configure

Set global configuration options.

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;
}

Usage:

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

getConfig

Get current configuration.

function getConfig(): Config;

Usage:

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

Configuration Options

testIdAttribute

Change the attribute used for test ID queries.

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

asyncUtilTimeout

Set default timeout for async utilities.

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

defaultHidden

Include hidden elements by default in role queries.

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

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

defaultIgnore

Elements to ignore by default in text queries.

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

showOriginalStackTrace

Include full stack traces in errors.

configure({showOriginalStackTrace: true});

throwSuggestions

Enable query suggestions in error messages.

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

Common Patterns

Global Setup

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

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

Environment-Specific

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

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

Per-Test Configuration

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

Install with Tessl CLI

npx tessl i tessl/npm-testing-library--dom

docs