diff --git a/.all-contributorsrc b/.all-contributorsrc index 08ca11f2..df19302c 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -220,6 +220,15 @@ "code", "test" ] + }, + { + "login": "JonathanStoye", + "name": "Jonathan Stoye", + "avatar_url": "https://avatars2.githubusercontent.com/u/21689428?v=4", + "profile": "http://jonathanstoye.de", + "contributions": [ + "doc" + ] } ] } diff --git a/README.md b/README.md index 8b3171ac..1602f0ca 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ [![downloads][downloads-badge]][npmtrends] [![MIT License][license-badge]][license] -[![All Contributors](https://img.shields.io/badge/all_contributors-21-orange.svg?style=flat-square)](#contributors) +[![All Contributors](https://img.shields.io/badge/all_contributors-22-orange.svg?style=flat-square)](#contributors) [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] @@ -67,37 +67,36 @@ when a real user uses it. ## Table of Contents - -* [Installation](#installation) -* [Usage](#usage) - * [`getByLabelText`](#getbylabeltext) - * [`getByPlaceholderText`](#getbyplaceholdertext) - * [`getByText`](#getbytext) - * [`getByAltText`](#getbyalttext) - * [`getByTitle`](#getbytitle) - * [`getByValue`](#getbyvalue) - * [`getByTestId`](#getbytestid) - * [`wait`](#wait) - * [`waitForElement`](#waitforelement) - * [`fireEvent`](#fireevent) -* [Custom Jest Matchers](#custom-jest-matchers) - * [Using other assertion libraries](#using-other-assertion-libraries) -* [`TextMatch`](#textmatch) - * [Precision](#precision) - * [TextMatch Examples](#textmatch-examples) -* [`query` APIs](#query-apis) -* [`queryAll` and `getAll` APIs](#queryall-and-getall-apis) -* [`getQueriesForElement`](#getqueriesforelement) -* [Debugging](#debugging) - * [`prettyDOM`](#prettydom) -* [Implementations](#implementations) -* [FAQ](#faq) -* [Other Solutions](#other-solutions) -* [Guiding Principles](#guiding-principles) -* [Contributors](#contributors) -* [LICENSE](#license) +- [Installation](#installation) +- [Usage](#usage) + - [`getByLabelText`](#getbylabeltext) + - [`getByPlaceholderText`](#getbyplaceholdertext) + - [`getByText`](#getbytext) + - [`getByAltText`](#getbyalttext) + - [`getByTitle`](#getbytitle) + - [`getByValue`](#getbyvalue) + - [`getByTestId`](#getbytestid) + - [`wait`](#wait) + - [`waitForElement`](#waitforelement) + - [`fireEvent`](#fireevent) +- [Custom Jest Matchers](#custom-jest-matchers) + - [Using other assertion libraries](#using-other-assertion-libraries) +- [`TextMatch`](#textmatch) + - [Precision](#precision) + - [TextMatch Examples](#textmatch-examples) +- [`query` APIs](#query-apis) +- [`queryAll` and `getAll` APIs](#queryall-and-getall-apis) +- [`getQueriesForElement`](#getqueriesforelement) +- [Debugging](#debugging) + - [`prettyDOM`](#prettydom) +- [Implementations](#implementations) +- [FAQ](#faq) +- [Other Solutions](#other-solutions) +- [Guiding Principles](#guiding-principles) +- [Contributors](#contributors) +- [LICENSE](#license) @@ -114,8 +113,8 @@ npm install --save-dev dom-testing-library Note: -* Each of the `get` APIs below have a matching [`getAll`](#queryall-and-getall-apis) API that returns all elements instead of just the first one, and [`query`](#query-apis)/[`getAll`](#queryall-and-getall-apis) that return `null`/`[]` instead of throwing an error. -* See [TextMatch](#textmatch) for details on the `exact`, `trim`, and `collapseWhitespace` options. +- Each of the `get` APIs below have a matching [`getAll`](#queryall-and-getall-apis) API that returns all elements instead of just the first one, and [`query`](#query-apis)/[`getAll`](#queryall-and-getall-apis) that return `null`/`[]` instead of throwing an error. +- See [TextMatch](#textmatch) for details on the `exact`, `trim`, and `collapseWhitespace` options. ```javascript // src/__tests__/example.js @@ -262,6 +261,7 @@ getByText( container: HTMLElement, text: TextMatch, options?: { + selector?: string = '*', exact?: boolean = true, collapseWhitespace?: boolean = true, trim?: boolean = true, @@ -276,6 +276,8 @@ matching the given [`TextMatch`](#textmatch). const aboutAnchorNode = getByText(container, 'about') ``` +> NOTE: see [`getbylabeltext`](#getbylabeltext) for more details on how and when to use the `selector` option + ### `getByAltText` ```typescript @@ -559,7 +561,7 @@ If you're not using jest, you may be able to find a similar set of custom assertions for your library of choice. Here's a list of alternatives to jest-dom for other popular assertion libraries: -* [chai-dom](https://github.com/nathanboktae/chai-dom) +- [chai-dom](https://github.com/nathanboktae/chai-dom) If you're aware of some other alternatives, please [make a pull request][prs] and add it here! @@ -574,13 +576,13 @@ Several APIs accept a `TextMatch` which can be a `string`, `regex` or a Some APIs accept an object as the final argument that can contain options that affect the precision of string matching: -* `exact`: Defaults to `true`; matches full strings, case-sensitive. When false, +- `exact`: Defaults to `true`; matches full strings, case-sensitive. When false, matches substrings and is not case-sensitive. - * `exact` has no effect on `regex` or `function` arguments. - * In most cases using a regex instead of a string gives you more control over + - `exact` has no effect on `regex` or `function` arguments. + - In most cases using a regex instead of a string gives you more control over fuzzy matching and should be preferred over `{ exact: false }`. -* `trim`: Defaults to `true`; trim leading and trailing whitespace. -* `collapseWhitespace`: Defaults to `true`. Collapses inner whitespace (newlines, tabs, repeated spaces) into a single space. +- `trim`: Defaults to `true`; trim leading and trailing whitespace. +- `collapseWhitespace`: Defaults to `true`. Collapses inner whitespace (newlines, tabs, repeated spaces) into a single space. ### TextMatch Examples @@ -717,7 +719,7 @@ of these utilities was in the `react-testing-library`. Implementations include: -* [`react-testing-library`](https://github.com/kentcdodds/react-testing-library) +- [`react-testing-library`](https://github.com/kentcdodds/react-testing-library) ## FAQ @@ -862,6 +864,8 @@ Thanks goes to these people ([emoji key][emojis]): | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | [
Anto Aravinth](https://github.com/antoaravinth)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Tests") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=antoaravinth "Documentation") | [
Jonah Moses](https://github.com/JonahMoses)
[πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=JonahMoses "Documentation") | [
Łukasz Gandecki](http://team.thebrain.pro)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Tests") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=lgandecki "Documentation") | [
Ivan Babak](https://sompylasar.github.io)
[πŸ›](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Asompylasar "Bug reports") [πŸ€”](#ideas-sompylasar "Ideas, Planning, & Feedback") [πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=sompylasar "Code") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=sompylasar "Documentation") | [
Jesse Day](https://github.com/jday3)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=jday3 "Code") | [
Ernesto GarcΓ­a](http://gnapse.github.io)
[πŸ’¬](#question-gnapse "Answering Questions") [πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=gnapse "Code") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=gnapse "Documentation") | [
Josef Maxx Blake](http://jomaxx.com)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Code") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=jomaxx "Tests") | | [
Alex Cook](https://github.com/alecook)
[πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=alecook "Documentation") [πŸ’‘](#example-alecook "Examples") | [
Daniel Cook](https://github.com/dfcook)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Code") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=dfcook "Tests") | [
Thomas Chia](https://github.com/thchia)
[πŸ›](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Athchia "Bug reports") [πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=thchia "Code") | [
Tim Deschryver](https://github.com/tdeschryver)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=tdeschryver "Tests") | [
Alex Krolick](https://alexkrolick.com)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=alexkrolick "Code") | [
Maddi Joyce](http://www.maddijoyce.com)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=maddijoyce "Code") | [
Peter Kamps](https://github.com/npeterkamps)
[πŸ›](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Anpeterkamps "Bug reports") [πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=npeterkamps "Code") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=npeterkamps "Tests") | +| [
Jonathan Stoye](http://jonathanstoye.de)
[πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=JonathanStoye "Documentation") | + This project follows the [all-contributors][all-contributors] specification.