tessl/npm-testing-library--dom

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

—

Pending

Overview

Eval results

Files

Screen

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

Global query object bound to document.body for convenient document-wide queries without passing containers.

Screen Object

const screen: Screen;

interface Screen {
  // All query methods without container parameter
  // Signature: method(text, options?, waitOptions?) => element
  
  // Role queries
  getByRole(role, options?): HTMLElement;
  getAllByRole(role, options?): HTMLElement[];
  queryByRole(role, options?): HTMLElement | null;
  queryAllByRole(role, options?): HTMLElement[];
  findByRole(role, options?, waitOptions?): Promise<HTMLElement>;
  findAllByRole(role, options?, waitOptions?): Promise<HTMLElement[]>;
  
  // All other query types follow same pattern
  getByLabelText, queryByLabelText, findByLabelText, ...
  getByPlaceholderText, queryByPlaceholderText, findByPlaceholderText, ...
  getByText, queryByText, findByText, ...
  getByAltText, queryByAltText, findByAltText, ...
  getByTitle, queryByTitle, findByTitle, ...
  getByDisplayValue, queryByDisplayValue, findByDisplayValue, ...
  getByTestId, queryByTestId, findByTestId, ...
  
  // Debug utilities
  debug(element?, maxLength?, options?): void;
  logTestingPlaygroundURL(element?): string;
}

Usage:

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

// Query entire document
const button = screen.getByRole('button', {name: /submit/i});
const heading = screen.getByRole('heading', {level: 1});
const input = screen.getByLabelText('Email');

// Async queries
const message = await screen.findByText('Success');

// Debug
screen.debug();  // Pretty print document.body

When to Use Screen vs Container

Use screen (preferred):

Querying entire document
Simple test cases
Readable, concise code

Use container queries:

Scoping to specific regions with within
Multiple similar elements need disambiguation
Testing components in isolation

Comparison:

// Using screen
const button = screen.getByRole('button', {name: /submit/i});

// Using container (equivalent but verbose)
import {getByRole} from '@testing-library/dom';
const button = getByRole(document.body, 'button', {name: /submit/i});

// Use screen + within for scoping
const form = screen.getByRole('form');
const email = within(form).getByLabelText('Email');

Debug Methods

// Pretty print entire document
screen.debug();

// Debug specific element
const form = screen.getByRole('form');
screen.debug(form);

// Debug multiple elements
const buttons = screen.getAllByRole('button');
screen.debug(buttons);

// With options
screen.debug(form, 10000, {
  filterNode: (node) => node.nodeType === 1  // Only show elements
});

Testing Playground

// Get URL for query suggestions
const url = screen.logTestingPlaygroundURL();
console.log('Open in browser:', url);

// For specific element
const container = screen.getByTestId('app');
const url = screen.logTestingPlaygroundURL(container);

Install with Tessl CLI

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

docs