What is the fundamental principle of Kent C. Dodds regarding component testing?

The principle states: 'The more your tests resemble the way your software is used, the more confidence they can give you.' This means moving away from testing implementation details (private variables, hooks, state, shallow rendering) in favor of testing the interface contract through the real DOM and accessibility tree — exactly as an end user or assistive technology would.

Why does getByRole have the highest priority among all selectors in React Testing Library?

getByRole validates not just the presence of an HTML tag, but its semantic role in the Accessibility Tree (AOM). Using getByRole guarantees the element is accessible to screen reader users and complies with W3C WAI-ARIA specifications. If a developer replaces a semantic button tag with a non-semantic div without role='button' and tabIndex, the test with getByRole will fail, protecting the application from an accessibility regression.

What is the difference between getByText, queryByText, and findByText?

getByText synchronously searches for an element in the DOM and throws an error if the node is not found or if more than one match is found. queryByText synchronously searches for an element but returns null instead of throwing when the node is not found — ideal for asserting absence: expect(queryByText(...)).toBeNull(). findByText returns a Promise and asynchronously polls the DOM via MutationObserver until the element appears or a timeout expires (default 1000 ms).

When is it appropriate to use the data-testid attribute and getByTestId?

getByTestId is considered an Escape Hatch — a last resort. Its use is justified when an element has no natural semantic role and contains no unique text: for example, an empty dynamic canvas container ( ), a complex decorative SVG with interactive paths, or when the element's text is composed entirely of unpredictable dynamic content from a third-party script.

How does the logRoles(container) utility assist in debugging failing tests?

The logRoles function inspects the given DOM container and prints to the test runner console a complete map of available ARIA roles and their associated accessible names computed for that tree. This allows you to instantly see what role the browser has assigned to an element and what name RTL expects, eliminating guesswork in selector construction.

What is an Accessible Name and what algorithm computes it?

The Accessible Name is the text associated with an element in the browser's accessibility tree. The browser computes it by following a strict W3C specification: 1) the value of the aria-labelledby attribute; 2) if absent — the aria-label value; 3) for form elements — the text of the associated ; 4) for links and buttons — the inner text content (subtree text); 5) a placeholder or title as a last resort.

Why is testing component state (e.g., via enzyme's wrapper.state()) considered an architectural antipattern?

Because state is a private implementation detail. The user doesn't care about the variable name inside useState — they care about what changed on screen (text appeared, a button became disabled, a modal opened). Testing state makes tests brittle: any refactoring of internal logic breaks the tests even when the external behavior is unchanged, generating false-positive failures.

Why is it recommended to use screen rather than destructuring methods from the render() call?

Using screen.getBy* eliminates the need to destructure a long list of methods from every render() call, keeping the code clean. Furthermore, screen is automatically bound to document.body, which guarantees correct element lookup even with React Portals (e.g., modals and tooltips) that render outside the component's root container.

React Testing Library (RTL) Philosophy — Testing & QA Automation

Architectural Foundation#

Historically, component testing in the React ecosystem relied on libraries like Enzyme, which promoted a shallow rendering methodology and direct inspection of component internals: checking state (wrapper.state()), inspecting the props passed to child nodes, or calling private instance methods.

This approach carried a fundamental architectural flaw — tight coupling between tests and implementation details. When refactoring a component (for example, migrating from a class component to hooks, splitting a monolithic hook into several sub-hooks, or changing the internal DOM tree structure), tests would fail even when the visual behavior and the public contract of the component remained 100% correct. This created the problem of false positives, which undermined the value of automation.

Behavior-Driven Testing lies at the core of the React Testing Library (RTL) philosophy, articulated by Kent C. Dodds:

«The more your tests resemble the way your software is used, the more confidence they can give you.»

In the standards of modern web development and React 19, the interface is tested at the intersection of the DOM tree and the Accessibility Tree (AOM). This guarantees that a passing test validates not only business logic but also the digital accessibility (a11y) of the interface for all categories of users.

Mental Model#

In the React Testing Library paradigm, a component is mounted into a real or virtual DOM environment (jsdom or happy-dom). The test runner (Vitest 4+) has no direct access to the internal closure variables of React Fiber, useRef references, or the internal state of useState.

Instead, the test interacts with the interface through two key channels:

Perception (Queries): Finding interactive nodes by their semantic role, accessible name, form labels, and text content.
Action (Interactions): Generating user events through the physical event chains of the @testing-library/user-event library.

text

+-----------------------------------------------------------------------+
|                         User / Screen Reader                          |
+-----------------------------------------------------------------------+
                                    │
                                    ▼ (Perception via UI & ARIA)
+-----------------------------------------------------------------------+
|               Accessibility Tree (AOM) & DOM Tree                    |
|  - role: "button", name: "Checkout"                                   |
|  - role: "textbox", name: "Email address"                             |
|  - role: "status", aria-live: "polite"                                |
+-----------------------------------------------------------------------+
                                    ▲
                                    │ (RTL semantic selectors)
+-----------------------------------------------------------------------+
|           React Testing Library (screen.getByRole / findBy)          |
+-----------------------------------------------------------------------+
                                    ▲
                                    │ (Isolation: black-box render)
+-----------------------------------------------------------------------+
|         React 19 Component (Fiber / Hooks / Private State)            |
+-----------------------------------------------------------------------+

The Split: Implementation Details vs. Public Contract#

When writing tests, it is critical to classify the architectural elements of a component:

Syntax and API#

1. RTL Selector Hierarchy (Query Priority)#

RTL enforces a strict element-selection priority. Lower-priority selectors should only be used when the semantic capabilities of the WAI-ARIA standard have been exhausted.

text

+-----------------------------------------------------------------------+
| PRIORITY 1: Accessible to Everyone                                    |
|  ├── getByRole(role, { name, pressed, expanded, hidden })             |
|  ├── getByLabelText(text, { selector })                               |
|  ├── getByPlaceholderText(text)                                       |
|  ├── getByText(text, { selector })                                    |
|  └── getByDisplayValue(value)                                         |
+-----------------------------------------------------------------------+
                                    │
                                    ▼
+-----------------------------------------------------------------------+
| PRIORITY 2: Semantic Visual Attributes                                 |
|  ├── getByAltText(altText)                                            |
|  └── getByTitle(titleText)                                            |
+-----------------------------------------------------------------------+
                                    │
                                    ▼
+-----------------------------------------------------------------------+
| PRIORITY 3: Last Resort (Escape Hatch)                                |
|  └── getByTestId('checkout-submit-btn')                               |
+-----------------------------------------------------------------------+

2. Query Prefix Matrix: `get`, `query`, `find`#

Each selector exists in 6 variants, determining synchronicity and behavior on absence or multiple matches:

3. The `screen` Object and Debug Utilities#

Instead of destructuring methods from the render() result, the standard prescribes using the global screen object, bound to document.body:

typescript

import { render, screen, logRoles } from '@testing-library/react';

// Render the tree
const { container } = render(<CheckoutForm />);

// Print current DOM state to the test runner console
screen.debug();

// Print available ARIA semantic roles for the given container
logRoles(container);

Practical Patterns#

Pattern 1: Selection with `getByRole` and Accessible Name Computation#

When querying with getByRole, the second argument is an options object with a name field. The Accessible Name is computed by the browser according to the W3C specification: from text content, the aria-label attribute, or an aria-labelledby association.

typescriptsrc/components/OrderSummary.test.tsx

import { describe, it, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import React, { useState } from 'react';

interface OrderItem {
  readonly id: string;
  readonly title: string;
  readonly price: number;
}

interface OrderProps {
  readonly items: readonly OrderItem[];
  readonly onCheckout: (total: number) => void;
}

function OrderSummary({ items, onCheckout }: OrderProps) {
  const [promoApplied, setPromoApplied] = useState(false);
  const total = items.reduce((sum, item) => sum + item.price, 0);
  const finalPrice = promoApplied ? total * 0.9 : total;

  return (
    <section aria-labelledby="order-heading">
      <h2 id="order-heading">Order Summary</h2>

      <ul aria-label="Item list">
        {items.map((item) => (
          <li key={item.id}>
            <span>{item.title}</span> — <span>{item.price} USD</span>
          </li>
        ))}
      </ul>

      <label>
        <input
          type="checkbox"
          checked={promoApplied}
          onChange={(e) => setPromoApplied(e.target.checked)}
        />
        Apply 10% discount
      </label>

      <div role="status" aria-live="polite">
        Total due: {finalPrice} USD
      </div>

      <button
        type="button"
        disabled={items.length === 0}
        onClick={() => onCheckout(finalPrice)}
      >
        Confirm and Pay
      </button>
    </section>
  );
}

describe('OrderSummary Component', () => {
  const mockItems: readonly OrderItem[] = [
    { id: '1', title: 'React 19 Architecture Guide', price: 49 },
    { id: '2', title: 'Vitest Deep Dive', price: 39 },
  ];

  it('correctly finds elements via the ARIA tree and calculates the total price', async () => {
    const user = userEvent.setup();
    const handleCheckout = vi.fn();

    render(<OrderSummary items={mockItems} onCheckout={handleCheckout} />);

    // 1. Find structural headings and lists by role and accessible name
    expect(
      screen.getByRole('region', { name: 'Order Summary' })
    ).toBeInTheDocument();

    expect(
      screen.getByRole('list', { name: 'Item list' })
    ).toBeInTheDocument();

    // 2. Find interactive form elements
    const discountCheckbox = screen.getByRole('checkbox', {
      name: /apply 10% discount/i,
    });
    expect(discountCheckbox).not.toBeChecked();

    // 3. Verify the dynamic status region
    expect(screen.getByRole('status')).toHaveTextContent('Total due: 88 USD');

    // 4. Interact via user event
    await user.click(discountCheckbox);

    expect(discountCheckbox).toBeChecked();
    expect(screen.getByRole('status')).toHaveTextContent('Total due: 79.2 USD');

    // 5. Activate the checkout button
    const submitBtn = screen.getByRole('button', {
      name: /confirm and pay/i,
    });
    await user.click(submitBtn);

    expect(handleCheckout).toHaveBeenCalledTimes(1);
    expect(handleCheckout).toHaveBeenCalledWith(79.2);
  });
});

Pattern 2: Verifying Interactive ARIA States (`pressed`, `expanded`)#

Accordion, dropdown, and toggle-button components must communicate their state to assistive technologies via the aria-expanded, aria-pressed, and aria-selected attributes. RTL allows filtering queries by these attributes.

typescriptsrc/components/CollapsibleFilter.test.tsx

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import React, { useState, useId } from 'react';

interface CollapsibleProps {
  readonly title: string;
  readonly children: React.ReactNode;
}

function CollapsibleFilter({ title, children }: CollapsibleProps) {
  const [isExpanded, setIsExpanded] = useState(false);
  const panelId = useId();

  return (
    <div className="filter-wrapper">
      <button
        type="button"
        aria-expanded={isExpanded}
        aria-controls={panelId}
        onClick={() => setIsExpanded((prev) => !prev)}
      >
        {title}
      </button>

      {isExpanded && (
        <div id={panelId} role="region" aria-label={title}>
          {children}
        </div>
      )}
    </div>
  );
}

describe('CollapsibleFilter Accessibility States', () => {
  it('synchronizes aria-expanded with the physical visibility of the content', async () => {
    const user = userEvent.setup();

    render(
      <CollapsibleFilter title="Product Categories">
        <p>Electronics, Books, Software</p>
      </CollapsibleFilter>
    );

    // Initial state: button is collapsed
    const toggleButton = screen.getByRole('button', {
      name: 'Product Categories',
      expanded: false,
    });
    expect(toggleButton).toBeInTheDocument();

    // Content region is absent from the DOM
    expect(
      screen.queryByRole('region', { name: 'Product Categories' })
    ).not.toBeInTheDocument();

    // Expand the panel
    await user.click(toggleButton);

    // Verify ARIA state changed to expanded: true
    expect(
      screen.getByRole('button', {
        name: 'Product Categories',
        expanded: true,
      })
    ).toBeInTheDocument();

    // Verify the region is now visible
    expect(
      screen.getByRole('region', { name: 'Product Categories' })
    ).toHaveTextContent('Electronics, Books, Software');
  });
});

Pattern 3: Asserting Element Absence — `queryBy*` vs. `waitForElementToBeRemoved`#

A common beginner mistake is using getBy* to assert a node's disappearance. The getBy* family immediately throws a fatal exception. Use queryBy* for synchronous absence checks, and waitForElementToBeRemoved to track asynchronous disappearance.

typescriptsrc/components/NotificationBanner.test.tsx

import { describe, it, expect } from 'vitest';
import { render, screen, waitForElementToBeRemoved } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import React, { useState } from 'react';

function DismissibleBanner({ message }: { readonly message: string }) {
  const [visible, setVisible] = useState(true);

  if (!visible) return null;

  return (
    <aside role="alert">
      <span>{message}</span>
      <button
        type="button"
        aria-label="Dismiss notification"
        onClick={() => setVisible(false)}
      >
        &times;
      </button>
    </aside>
  );
}

describe('DismissibleBanner LifeCycle', () => {
  it('correctly removes the alert from the DOM when the close button is clicked', async () => {
    const user = userEvent.setup();

    render(<DismissibleBanner message="Your session expires in 5 minutes" />);

    // 1. Confirm the alert is present via getByRole
    const alertElement = screen.getByRole('alert');
    expect(alertElement).toHaveTextContent('Your session expires in 5 minutes');

    const closeBtn = screen.getByRole('button', {
      name: 'Dismiss notification',
    });

    // 2. Initiate dismissal
    await user.click(closeBtn);

    // 3. Synchronous absence check: queryByRole returns null
    expect(screen.queryByRole('alert')).not.toBeInTheDocument();

    // 4. Alternative for async animations/transitions:
    // await waitForElementToBeRemoved(() => screen.queryByRole('alert'));
  });
});

Pattern 4: Inspecting the Accessibility Tree with `logRoles`#

When a test fails with «Unable to find an accessible element with the role...», the logRoles utility lets you print the computed AOM tree to understand how the element is perceived by assistive technologies.

typescriptsrc/components/NavigationMenu.test.tsx

import { describe, it, expect } from 'vitest';
import { render, screen, logRoles } from '@testing-library/react';
import React from 'react';

function UserNavigation() {
  return (
    <header>
      <nav aria-label="Main menu">
        <a href="/profile">My Profile</a>
        <a href="/settings">Settings</a>
        <button type="button" aria-label="Sign out">
          <svg aria-hidden="true" focusable="false"><path d="M0 0h24v24H0z" /></svg>
        </button>
      </nav>
    </header>
  );
}

describe('UserNavigation Diagnostic', () => {
  it('prints the roles tree for precise selector tuning', () => {
    const { container } = render(<UserNavigation />);

    // Logs the role structure to stdout:
    // banner:
    //   navigation "Main menu":
    //     link "My Profile"
    //     link "Settings"
    //     button "Sign out"
    logRoles(container);

    // Precise selector based on the log
    expect(screen.getByRole('navigation', { name: 'Main menu' })).toBeInTheDocument();
    expect(screen.getByRole('button', { name: 'Sign out' })).toBeInTheDocument();
  });
});

Common Pitfalls#

Ошибка: Finding Elements by CSS Classes or DOM Tags

Using container.querySelector('.btn-primary') or container.getElementsByTagName('input') tightly couples the test to presentation styles and markup. If a designer replaces the class with a Tailwind utility or wraps the button in an auxiliary <span>, the test fails even though the component continues to work correctly.

typescript

// ❌ ANTIPATTERN: Coupled to a styling CSS class
const button = container.querySelector('.submit-button-active');
expect(button).toBeDefined();

// ✅ SOLUTION: Query by semantic role and accessible name
const button = screen.getByRole('button', { name: /save/i });
expect(button).toBeInTheDocument();

Ошибка: Overusing data-testid as the First Choice

The data-testid attribute is invisible to users and screen readers. If a developer accidentally removes the text from a button or breaks keyboard focus, a test using getByTestId will continue to pass, letting a critical accessibility defect through to production.

typescript

// ❌ ANTIPATTERN: Hides semantic and accessibility defects
render(<div onClick={handleClick} data-testid="fake-submit">Submit</div>);
const el = screen.getByTestId('fake-submit'); // Test passes, but this is not a button!

// ✅ SOLUTION: Forces the use of accessible HTML
render(<button type="submit">Submit</button>);
const el = screen.getByRole('button', { name: /submit/i });

Ошибка: Using getBy* Instead of queryBy* to Assert Node Absence

The getBy* family immediately throws a TestingLibraryElementError if the element is not found in the DOM. The construct expect(screen.getByText('Error')).not.toBeInTheDocument() will crash at the getByText call itself, never reaching the expect matcher.

typescript

// ❌ ANTIPATTERN: Test fails with an unhandled exception in getBy
expect(screen.getByText('Authorization error')).not.toBeInTheDocument();

// ✅ SOLUTION: queryBy returns null when the node is absent
expect(screen.queryByText('Authorization error')).not.toBeInTheDocument();

Ошибка: Inspecting Internal Hook State or Fiber Nodes

Attempts to access internal variables via wrapper.state() (an Enzyme habit) or inspecting _reactFiber strip the test of refactoring resilience. Only changes in the rendered DOM should be tested.

typescript

// ❌ ANTIPATTERN: Inspects private component state
expect(componentInstance.state.isOpen).toBe(true);

// ✅ SOLUTION: Tests the UI's response to the state change
expect(screen.getByRole('dialog', { name: /edit/i })).toBeVisible();

RTL Selector Composition Algorithm

Identify the ARIA RoleRole

Determine the element's semantic role in the Accessibility Tree: button, textbox, heading, link, dialog, status, listbox.

Compute the Accessible NameName

Determine how the element is announced by a screen reader: text inside the tag, aria-label, an h1-h6 heading, or an associated label with htmlFor.

Select the Method by Assertion TypeQuery Type

Use getByRole to assert presence, queryByRole to assert absence, and findByRole for async waiting.

Refine with State FiltersState Filter

Add options to check interactive state: { expanded: true, pressed: false, hidden: false }.

Escape Hatch (when no alternative exists)Fallback

Only if the node is a purely dynamic canvas or a complex SVG, use data-testid.

Interview Questions#

Interview Questions8 questions

React Testing Library (RTL) Philosophy

Architectural Foundation#

Mental Model#

The Split: Implementation Details vs. Public Contract#

Syntax and API#

1. RTL Selector Hierarchy (Query Priority)#

2. Query Prefix Matrix: get, query, find#

3. The screen Object and Debug Utilities#

Practical Patterns#

Pattern 1: Selection with getByRole and Accessible Name Computation#

Pattern 2: Verifying Interactive ARIA States (pressed, expanded)#

Pattern 3: Asserting Element Absence — queryBy* vs. waitForElementToBeRemoved#

Pattern 4: Inspecting the Accessibility Tree with logRoles#

Common Pitfalls#

Ошибка: Finding Elements by CSS Classes or DOM Tags

Ошибка: Overusing data-testid as the First Choice

Ошибка: Using getBy* Instead of queryBy* to Assert Node Absence

Ошибка: Inspecting Internal Hook State or Fiber Nodes

Interview Questions#

Related Topics#

Architectural Foundation#

Mental Model#

The Split: Implementation Details vs. Public Contract#

Syntax and API#

1. RTL Selector Hierarchy (Query Priority)#

2. Query Prefix Matrix: get, query, find#

3. The screen Object and Debug Utilities#

Practical Patterns#

Pattern 1: Selection with getByRole and Accessible Name Computation#

Pattern 2: Verifying Interactive ARIA States (pressed, expanded)#

Pattern 3: Asserting Element Absence — queryBy* vs. waitForElementToBeRemoved#

Pattern 4: Inspecting the Accessibility Tree with logRoles#

Common Pitfalls#

Ошибка: Finding Elements by CSS Classes or DOM Tags

Ошибка: Overusing data-testid as the First Choice

Ошибка: Using getBy* Instead of queryBy* to Assert Node Absence

Ошибка: Inspecting Internal Hook State or Fiber Nodes

Interview Questions#

Related Topics#

2. Query Prefix Matrix: `get`, `query`, `find`#

3. The `screen` Object and Debug Utilities#

Pattern 1: Selection with `getByRole` and Accessible Name Computation#

Pattern 2: Verifying Interactive ARIA States (`pressed`, `expanded`)#

Pattern 3: Asserting Element Absence — `queryBy*` vs. `waitForElementToBeRemoved`#

Pattern 4: Inspecting the Accessibility Tree with `logRoles`#

2. Query Prefix Matrix: `get`, `query`, `find`#

3. The `screen` Object and Debug Utilities#

Pattern 1: Selection with `getByRole` and Accessible Name Computation#

Pattern 2: Verifying Interactive ARIA States (`pressed`, `expanded`)#

Pattern 3: Asserting Element Absence — `queryBy*` vs. `waitForElementToBeRemoved`#

Pattern 4: Inspecting the Accessibility Tree with `logRoles`#