DOCSEARCHbyAlgolia
Submit Docs

Testing Library Documentation

repository·main·Indexed 19 days ago

https://github.com/testing-library/testing-library-docs

Documentation for the Testing Library ecosystem, including core tools like dom-testing-library, user-event, and jest-dom, as well as framework wrappers for React, Angular, Vue, React Native, Cypress, ReasonReact, TestCafe, and Puppeteer. Includes detailed API references for Angular Testing Library, covering rendering methods, component configuration, and RenderResult utilities.

Tokens
100K
Snippets
321
Records
415
Agent score
66%

What's inside Testing Library

  1. What is DOM Testing Library and its ecosystem

    main

    The core of the ecosystem is DOM Testing Library, a lightweight solution for testing web pages by querying and interacting with DOM nodes. It works in environments that provide DOM APIs, such as JSDOM (often used with Jest) or in a real browser.

    DOM Testing Library is wrapped to provide ergonomic APIs for various frameworks and platforms:

    • React: react-testing-library
    • Angular: angular-testing-library
    • Vue: vue-testing-library
    • React Native: react-native-testing-library
    • Cypress: A plugin to use testing-library queries for end-to-end tests.

  3. Introduction to Marko Testing Library

    main

    Marko Testing Library is a lightweight utility built on top of DOM Testing Library specifically for working with Marko components.

    Instead of interacting with component instances, this library encourages you to work with actual DOM nodes. This approach follows the guiding principle: "The more your tests resemble the way your software is used, the more confidence they can give you."

    Key characteristics:

    • User-Centric Queries: Facilitates querying the DOM the way a user would (e.g., finding elements by label text, or finding links and buttons by their visible text).
    • Implementation Agnostic: Focuses on functionality rather than implementation details, making tests more resilient to refactors.
    • Accessibility Focused: Encourages building more accessible applications by prioritizing queries that rely on accessible roles and labels.

    Important Distinctions:

    • It is not a test runner or framework.
    • It is compatible with various test runners like Jest or Mocha.
    • Most query logic is inherited from @testing-library/dom.

  4. Introduction to Qwik Testing Library

    main

    Qwik Testing Library is a lightweight library designed for testing Qwik components. It provides utilities built on top of qwik and @testing-library/dom to allow you to mount Qwik components and query their rendered output in the DOM.

    It follows the core Testing Library guiding principle: "The more your tests resemble the way your software is used, the more confidence they can give you."

    Important Distinctions:

    • It is not a test runner or a testing framework.
    • It is not specific to any single testing framework (it can be used with various runners).

  5. What is DOM Testing Library

    main

    DOM Testing Library is a lightweight utility for testing DOM nodes, whether they are simulated in a environment like JSDOM (common with Jest) or running in a real browser.

    Its primary purpose is to provide querying utilities that allow you to find elements in the DOM in a way that mimics how a real user interacts with the page (e.g., finding a button by its text or a form field by its label). This approach helps ensure that tests focus on functionality rather than implementation details, making them more resilient to refactors.

    Key Characteristics:

    • User-Centric Querying: Encourages finding elements by labels, text, and roles to promote accessibility.
    • Escape Hatch: Provides data-testid as a way to select elements when text content or labels are not practical.
    • Framework Agnostic: It is NOT a test runner or framework itself; it is a utility library that works with any testing framework (though Jest is recommended).

  6. What is React Native Testing Library?

    main

    React Native Testing Library (RNTL) is a testing library for React Native inspired by React Testing Library.

    Unlike other wrappers that use DOM Testing Library as a base, RNTL implements its core queries independently because React Native does not run in a browser environment. It provides utility functions on top of react-test-renderer to encourage testing practices that focus on user behavior rather than implementation details.

    Key Principles:

    • Avoid implementation details: Tests should focus on functionality to ensure they don't break during refactors.
    • User-centric testing: "The more your tests resemble the way your software is used, the more confidence they can give you."

    Compatibility:

    • Primarily tested with Jest, but compatible with other test runners.

  7. Explore the Testing Library ecosystem

    main

    The Testing Library family of tools is managed under a single GitHub organization to group projects that share the same philosophy: 'The more your tests resemble the way your software is used, the more confidence they can give you.'

    Available libraries and wrappers include:

    • Core/DOM: dom-testing-library, user-event, jest-dom
    • Framework Wrappers:
      • react-testing-library (React)
      • vue-testing-library (Vue)
      • native-testing-library (React Native)
      • cypress-testing-library (Cypress)
      • bs-react-testing-library (ReasonReact)
      • testcafe-testing-library (TestCafe)
      • pptr-testing-library (Puppeteer)
    • Utilities:
      • jest-native (Jest for Native platforms)

  8. Use eslint-plugin-testing-library to enforce best practices

    main

    The eslint-plugin-testing-library is an ESLint plugin designed to help developers follow Testing Library best practices and avoid common mistakes during test authoring.

    It provides:

    • Specific linting rules for Testing Library code.
    • A shareable configuration for recommended rules.
    • Framework-specific shareable configurations for Angular, React, and Vue.
    • Support for autofixable rules to automatically correct common issues.

  9. Explore the DOM Testing Library ecosystem

    main

    The following companion libraries work well with DOM Testing Library to enhance your testing experience:

    • user-event: For browser event simulation.
    • jest-dom: Provides custom Jest matchers.
    • bs-jest-dom: Companion library for bs-react-testing-library.
    • react-select-event: Companion library for React Testing Library.
    • eslint-plugin-testing-library: ESLint plugin for Testing Library.
    • eslint-plugin-jest-dom: ESLint plugin for Jest DOM.
    • riot-testing-library: Adds APIs for working with Riot.js components.

  10. What is Angular Testing Library and how does it work?

    main

    Angular Testing Library (ATL) is a lightweight utility built on top of DOM Testing Library. It provides APIs specifically designed for working with Angular components while encouraging testing best practices.

    Core Principles

    ATL follows the guiding principle: "The more your tests resemble the way your software is used, the more confidence they can give you."

    Instead of interacting with Angular component instances, your tests interact with actual DOM nodes. This ensures tests focus on functionality rather than implementation details, making them more resilient to refactors.

    Key Features

    • User-Centric Querying: Facilitates finding elements the way a user would (e.g., finding form elements by label text, or links and buttons by their text content).
    • Escape Hatch: Provides a recommended way to find elements using data-testid when text content is not practical.
    • Automatic Change Detection: Encapsulates fireEvent functions to automatically call detectChanges() after an event occurs, reducing boilerplate.
    • Framework Agnostic: Works with any test framework.
    • DOM Testing Library Integration: Re-exports query and fireEvent utilities from DOM Testing Library.

  11. What React Testing Library is and is not

    main

    It is important to understand the scope of React Testing Library to avoid misconfiguration:

    What it IS:

    • A lightweight solution for testing React components built on top of DOM Testing Library.
    • A replacement for Enzyme that encourages testing functionality over implementation details.

    What it IS NOT:

    • A test runner or framework: It does not execute tests; it only provides utilities for testing. While Jest is recommended, it works with any framework.
    • A testing framework itself: It is a utility library that integrates into your existing test runner.

  12. Understand the difference between interactions and fireEvent

    main
    While fireEvent is sufficient for most testing scenarios, it does not perfectly replicate real user interactions. fireEvent.click(element) only dispatches a single click event. In a real browser environment, a user click triggers a sequence of events including mouseOver, mouseMove, mouseDown, potential focus, and mouseUp before the click event itself. Additionally, fireEvent does not automatically handle side effects like a label element moving focus to its associated form control. For higher-fidelity testing that captures this full sequence, consider using user-event.