GitHub - testing-library/dom-testing-library: ๐Ÿ™ Simple and complete DOM testing utilities that encourage good testing practices. (original) (raw)

DOM Testing Library

octopus

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

Read the docs |Edit the docs

Build Status Code Coverage version downloads MIT License All Contributors PRs Welcome Code of Conduct Discord

Watch on GitHub Star on GitHub Tweet

TestingJavaScript.com Learn the smart, efficient way to test any JavaScript application.

Table of Contents

The Problem

You want to write maintainable tests for your Web UI. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

This Solution

The DOM Testing Library is a very light-weight solution for testing DOM nodes (whether simulated with JSDOM as provided by default with Jest or in the browser). The main utilities it provides involve querying the DOM for nodes in a way that's similar to how the user finds elements on the page. In this way, the library helps ensure your tests give you confidence in your UI code. The DOM Testing Library's primary guiding principle is:

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

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install --save-dev @testing-library/dom

Docs

Documentation

Read the docs (and discover framework and tool-specific implementations) attesting-library.com

Guiding Principles

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

We try to only expose methods and utilities that encourage you to write tests that closely resemble how your web pages are used.

Utilities are included in this project based on the following guiding principles:

  1. If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
  2. It should be generally useful for testing the application components in the way the user would use it. We are making some trade-offs here because we're using a computer and often a simulated browser environment, but in general, utilities should encourage tests that use the components the way they're intended to be used.
  3. Utility implementations and APIs should be simple and flexible.

At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.

Contributors

Thanks goes to these people (emoji key):

Kent C. Dodds Kent C. Dodds๐Ÿ’ป ๐Ÿ“– ๐Ÿš‡ โš ๏ธ Greg Bergรฉ Greg Bergรฉ๐Ÿค” Ryan Castner Ryan Castner๐Ÿ“– Daniel Sandiego Daniel Sandiego๐Ÿ’ป Paweล‚ Mikoล‚ajczyk Paweล‚ Mikoล‚ajczyk๐Ÿ’ป Alejandro ร‘รกรฑez Ortiz Alejandro ร‘รกรฑez Ortiz๐Ÿ“– Matt Parrish Matt Parrish๐Ÿ› ๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Justin Hall Justin Hall๐Ÿ“ฆ Anto Aravinth Anto Aravinth๐Ÿ’ป โš ๏ธ ๐Ÿ“– Jonah Moses Jonah Moses๐Ÿ“– ลukasz Gandecki ลukasz Gandecki๐Ÿ’ป โš ๏ธ ๐Ÿ“– Ivan Babak Ivan Babak๐Ÿ› ๐Ÿค” ๐Ÿ’ป ๐Ÿ“– Jesse Day Jesse Day๐Ÿ’ป Ernesto Garcรญa Ernesto Garcรญa๐Ÿ’ฌ ๐Ÿ’ป ๐Ÿ“–
Josef Maxx Blake Josef Maxx Blake๐Ÿ’ป ๐Ÿ“– โš ๏ธ Alex Cook Alex Cook๐Ÿ“– ๐Ÿ’ก ๐Ÿ‘€ Daniel Cook Daniel Cook๐Ÿ’ป ๐Ÿ“– โš ๏ธ Thomas Chia Thomas Chia๐Ÿ› ๐Ÿ’ป Tim Deschryver Tim Deschryver๐Ÿ’ป โš ๏ธ ๐Ÿ‘€ Alex Krolick Alex Krolick๐Ÿ’ป Maddi Joyce Maddi Joyce๐Ÿ’ป
Peter Kamps Peter Kamps๐Ÿ› ๐Ÿ’ป โš ๏ธ Jonathan Stoye Jonathan Stoye๐Ÿ“– ๐Ÿ’ป Sanghyeon Lee Sanghyeon Lee๐Ÿ’ก Justice Mba Justice Mba ๐Ÿ’ป ๐Ÿ“– ๐Ÿค” Wayne Crouch Wayne Crouch๐Ÿ’ป Ben Elliott Ben Elliott๐Ÿ’ป Ruben Costa Ruben Costa๐Ÿ’ป
Robert Smith Robert Smith๐Ÿ› ๐Ÿค” ๐Ÿ“– dadamssg dadamssg๐Ÿ’ป Neil Kistner Neil Kistner๐Ÿ’ป โš ๏ธ Ben Chauvette Ben Chauvette๐Ÿ’ป Jeff Baumgardt Jeff Baumgardt๐Ÿ’ป ๐Ÿ“– Matan Kushner Matan Kushner๐Ÿ’ป ๐Ÿ“– ๐Ÿค” โš ๏ธ Alex Wendte Alex Wendte๐Ÿ’ป ๐Ÿ“– โš ๏ธ
Tamas Fodor Tamas Fodor๐Ÿ“– Benjamin Eckardt Benjamin Eckardt๐Ÿ’ป Ryan Campbell Ryan Campbell๐Ÿ“– Taylor Briggs Taylor Briggsโš ๏ธ John Gozde John Gozde๐Ÿ’ป C. T. Lin C. T. Lin๐Ÿ“– Terrence Wong Terrence Wong๐Ÿ’ป
Soo Jae Hwang Soo Jae Hwang๐Ÿ’ป Royston Shufflebotham Royston Shufflebotham๐Ÿ› ๐Ÿ’ป ๐Ÿ“– โš ๏ธ Vadim Brodsky Vadim Brodsky๐Ÿ’ป Eunjae Lee Eunjae Lee๐Ÿ’ป David Peter David Peter๐Ÿ’ป Shy Alter Shy Alter๐Ÿ’ป ๐Ÿ“– ลukasz Makuch ลukasz Makuch๐Ÿ“ฆ
Tyler Haas Tyler Haas๐Ÿ’ป โš ๏ธ Vesa Laakso Vesa Laakso๐Ÿ’ป โš ๏ธ Tulsi Sapkota Tulsi Sapkota๐Ÿ’ป Tiago Nunes Tiago Nunes๐Ÿ’ป โš ๏ธ JaxCavalera JaxCavalera๐Ÿ’ป ๐Ÿ‘€ bopfer bopferโš ๏ธ Jan Pfitzner Jan Pfitzner๐Ÿ’ป
David David๐Ÿ’ป Diego Hernandez Diego Hernandez๐Ÿ’ป โš ๏ธ Alex Young Alex Young๐Ÿ’ป Paul Armstrong Paul Armstrong๐Ÿ’ป โš ๏ธ Tamรกs Szabรณ Tamรกs Szabรณ๐Ÿ’ป โš ๏ธ Dylan Piercey Dylan Piercey๐Ÿ’ป โš ๏ธ Michael Lasky Michael Lasky๐Ÿ’ป โš ๏ธ ๐Ÿ“–
Sebastian Silbermann Sebastian Silbermann๐Ÿ’ป โš ๏ธ ๐Ÿ“– ๐Ÿš‡ ๐Ÿ‘€ Dylan Vann Dylan Vann๐Ÿ’ป Adriร  Fontcuberta Adriร  Fontcuberta๐Ÿ’ป โš ๏ธ ๐Ÿ“– Thomas Lombart Thomas Lombart๐Ÿ’ป Sam Horton Sam Horton๐Ÿ’ป โš ๏ธ Andrew Hill Andrew Hill๐Ÿ’ป Jan Amann Jan Amann๐Ÿ’ป โš ๏ธ
Brais Piรฑeiro Brais Piรฑeiro๐Ÿ’ป โš ๏ธ Dominykas Blyลพฤ— Dominykas Blyลพฤ—๐Ÿ’ป โš ๏ธ Olzhas Askar Olzhas Askar๐Ÿ’ป โš ๏ธ ๐Ÿ“– Max Belsky Max Belsky๐Ÿ’ป โš ๏ธ Michael Mantel Michael Mantelโš ๏ธ Tom Nagle Tom Nagle๐Ÿ’ป Westbrook Johnson Westbrook Johnson๐Ÿ’ป
Mohammad Aziz Mohammad Aziz๐Ÿ’ป โš ๏ธ seetdev seetdevโš ๏ธ ๐Ÿ’ป Xavier Garcia Buils Xavier Garcia Buils๐Ÿ’ป โš ๏ธ aw-davidson aw-davidson๐Ÿ’ป โš ๏ธ Michaรซl De Boey Michaรซl De Boey๐Ÿ’ป Minh Nguyen Minh Nguyen๐Ÿ’ป Egill Sveinbjรถrnsson Egill Sveinbjรถrnsson๐Ÿ’ป
Pavel Pustovalov Pavel Pustovalov๐Ÿ“– Adam Palaniuk Adam Palaniuk๐Ÿ’ป โš ๏ธ Yama-Tomo Yama-Tomo๐Ÿ’ป โš ๏ธ Aaron Pettengill Aaron Pettengill๐Ÿ’ป โš ๏ธ Kate W. Boyd Kate W. Boyd๐Ÿ’ป Rahul Suryakanth Rahul Suryakanth๐Ÿ’ป โš ๏ธ Jamie Jamie๐Ÿ’ป โš ๏ธ
Nicolas Stepien Nicolas Stepien๐Ÿ’ป Ken Powers Ken Powers๐Ÿ’ป Michaล‚ Zdunek Michaล‚ Zdunek๐Ÿ’ป Ali Nasserzadeh Ali Nasserzadeh๐Ÿ’ป Darek Kay Darek Kay๐Ÿ“– ๐Ÿ’ป โš ๏ธ Lukas Lukas๐Ÿ’ป โš ๏ธ Tom Crockett Tom Crockett๐Ÿ’ป โš ๏ธ
Kevin Brewer Kevin Brewer๐Ÿ’ป โš ๏ธ Ben Monro Ben Monro๐Ÿ’ป ๐Ÿค” โš ๏ธ ๐Ÿ“– Stephan Meijer Stephan Meijer๐Ÿค” ๐Ÿ’ป โš ๏ธ Joรฃo Forja Joรฃo Forja๐Ÿ’ป โš ๏ธ Nick McCurdy Nick McCurdy๐Ÿ“– ๐Ÿ’ป โš ๏ธ ๐Ÿ‘€ ๐Ÿš‡ Caleb Meredith Caleb Meredith๐Ÿ’ป Marco Moretti Marco Moretti๐Ÿ’ป โš ๏ธ ๐Ÿ‘€
Travis Jefferson Travis Jefferson๐Ÿ’ป โš ๏ธ Maciej Jastrzebski Maciej Jastrzebski๐Ÿ› Geoff Harcourt Geoff Harcourt๐Ÿ’ป Josh Goldberg Josh Goldberg๐Ÿ’ป โš ๏ธ Ken Gregory Ken Gregory๐Ÿ’ป โš ๏ธ Jacob Paris Jacob Paris๐Ÿ’ป โš ๏ธ keiya sasaki keiya sasaki๐Ÿ“–
Idan Entin Idan Entin๐Ÿ’ป โš ๏ธ Deniz Susman Deniz Susman๐Ÿ’ป Bianca Del Carretto Bianca Del Carrettoโš ๏ธ ๐Ÿ’ป Josh Lalonde Josh Lalonde๐Ÿ’ป โš ๏ธ Ioannis Papadopoulos Ioannis Papadopoulos๐Ÿ’ป โš ๏ธ Maxwell Newlands Maxwell Newlands๐Ÿ’ป โš ๏ธ Jared Luxenberg Jared Luxenberg๐Ÿ’ป โš ๏ธ
snizhana snizhana๐Ÿ’ป โš ๏ธ Michael van Engelshoven Michael van Engelshoven๐Ÿ‘€ Asher Tuggle Asher Tuggle๐Ÿ› Winter LaMon Winter LaMon๐Ÿ’ป โš ๏ธ Victor Cordova Victor Cordova๐Ÿ’ป โš ๏ธ slowselfip slowselfip๐Ÿ› Dmitry Semigradsky Dmitry Semigradsky๐Ÿ’ป
Adam Adam๐Ÿ’ป โš ๏ธ balavishnuvj balavishnuvj๐Ÿ’ป Chris Colborne Chris Colborne๐Ÿ’ป Romain Trotard Romain Trotard๐Ÿ’ป Thomas Marshall Thomas Marshall๐Ÿ’ป โš ๏ธ johnjessewood johnjessewood๐Ÿ› ๐Ÿ’ป Ari Perkkiรถ Ari Perkkiรถ๐Ÿ› ๐Ÿ’ป ๐Ÿ“–
Nathan Force Nathan Force๐Ÿ’ป Philipp Fritsche Philipp Fritsche๐Ÿ’ป Renato Alencar Renato Alencar๐Ÿ’ป โš ๏ธ Simen Bekkhus Simen Bekkhus๐Ÿ› Dan Abramov Dan Abramov๐Ÿ› ๐Ÿ‘€ Matan Borenkraout Matan Borenkraout๐Ÿ’ป simcha90 simcha90๐Ÿ’ป
Amit Miran Amit Miran๐Ÿš‡ Dominik Lesch Dominik Lesch๐Ÿ“– Gareth Jones Gareth Jones๐Ÿ’ป โš ๏ธ Rayat Rahman Rayat Rahman๐Ÿ’ป Nik Savchenko Nik Savchenko๐Ÿ’ป Kevin Fleischman Kevin Fleischman๐Ÿ’ป โš ๏ธ Beth Hitch Beth Hitch๐Ÿ’ป
Jack Laurence Jack Laurence๐Ÿ’ป SantoJambit SantoJambit๐Ÿ’ป Yashu Mittal Yashu Mittal๐Ÿ“– Ian VanSchooten Ian VanSchooten๐Ÿ’ป Vanya Prokopovich Vanya Prokopovich๐Ÿ› James Nail James Nail๐Ÿ› Rob Caldecott Rob Caldecott๐Ÿ›
Dennis273 Dennis273๐Ÿ’ป Jackson Hardaker Jackson Hardakerโš ๏ธ Robin Drexler Robin Drexler๐Ÿ’ป Omer Dolev Omer Dolev๐Ÿ’ป Lirlev48 Lirlev48๐Ÿ’ป Tarnay Kรกlmรกn Tarnay Kรกlmรกn๐Ÿ’ป Than Hutchins Than Hutchins๐Ÿ’ป
Raphaรซl LEMIEUX Raphaรซl LEMIEUX๐Ÿ’ป Arthur Lauck Vilas Boas Arthur Lauck Vilas Boas๐Ÿ“– Daniel Acuรฑa Daniel Acuรฑa๐Ÿ’ป Craig Morten Craig Morten๐Ÿ’ป ๐Ÿ’ฌ Naor Peled Naor Peled๐Ÿ’ป Julien Wajsberg Julien Wajsberg๐Ÿ’ป ๐Ÿ› Kevin BON Kevin BON๐Ÿ’ป ๐Ÿ›
sieem sieem๐Ÿ’ป

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT