From ae1f333fad570c31bd3aa2261bee8d7da15e4d7a Mon Sep 17 00:00:00 2001 From: Justice Mba Date: Tue, 12 Jun 2018 18:08:33 +0100 Subject: [PATCH 1/3] Add within API and document it --- .all-contributorsrc | 11 +++++++++++ README.md | 21 +++++++++++++++++++-- src/index.js | 5 ++++- 3 files changed, 34 insertions(+), 3 deletions(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index 9b286dd9..64b12e40 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -238,6 +238,17 @@ "contributions": [ "example" ] + }, + { + "login": "Dajust", + "name": "Justice Mba ", + "avatar_url": "https://avatars3.githubusercontent.com/u/8015514?v=4", + "profile": "https://github.com/Dajust", + "contributions": [ + "code", + "doc", + "ideas" + ] } ] } diff --git a/README.md b/README.md index 370d79be..3f162d42 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-23-orange.svg?style=flat-square)](#contributors) +[![All Contributors](https://img.shields.io/badge/all_contributors-24-orange.svg?style=flat-square)](#contributors) [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] @@ -88,6 +88,7 @@ when a real user uses it. - [TextMatch Examples](#textmatch-examples) - [`query` APIs](#query-apis) - [`queryAll` and `getAll` APIs](#queryall-and-getall-apis) +- [`within` API](#within-api) - [`getQueriesForElement`](#getqueriesforelement) - [Debugging](#debugging) - [`prettyDOM`](#prettydom) @@ -642,6 +643,22 @@ expect(submitButtons).toHaveLength(3) // expect 3 elements expect(submitButtons[0]).toBeInTheDOM() ``` +## `within` API + +Sometimes, there is no garauntee that the text, placeholder, or label you want to query is unique on the page. So you might want to explicity tell react-render-dom to get an element **only within** a particular section of the page. `within` is a helper function for this case. + +Example: To get the text 'hello' only within a section called 'messages', you could do: + +```javascript +import {render, within} from 'react-testing-library' + +// ... + +const {getByTestId} = render(/* stuff */) +const messagesSection = getByTestId('messages') +const hello = within(messagesSection).getByText('hello') +``` + ## `getQueriesForElement` `getQueriesForElement` takes a DOM element and binds it to the raw query functions, allowing them @@ -864,7 +881,7 @@ 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") | [
Sanghyeon Lee](https://github.com/yongdamsh)
[πŸ’‘](#example-yongdamsh "Examples") | +| [
Jonathan Stoye](http://jonathanstoye.de)
[πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=JonathanStoye "Documentation") | [
Sanghyeon Lee](https://github.com/yongdamsh)
[πŸ’‘](#example-yongdamsh "Examples") | [
Justice Mba ](https://github.com/Dajust)
[πŸ’»](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Code") [πŸ“–](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Documentation") [πŸ€”](#ideas-Dajust "Ideas, Planning, & Feedback") | diff --git a/src/index.js b/src/index.js index 59637f40..b77bab3b 100644 --- a/src/index.js +++ b/src/index.js @@ -16,4 +16,7 @@ export * from './pretty-dom' // The original name of bindElementToQueries was weird // The new name is better. Remove this in the next major version bump. -export {getQueriesForElement as bindElementToQueries} +export { + getQueriesForElement as bindElementToQueries, + getQueriesForElement as within, +} From c718e901fa48e231db7be5660dfc4fc80dbc675d Mon Sep 17 00:00:00 2001 From: Justice Mba Date: Tue, 12 Jun 2018 18:43:21 +0100 Subject: [PATCH 2/3] improve the `within` API example --- README.md | 11 +++++------ src/index.js | 4 ++-- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 3f162d42..a1f049f3 100644 --- a/README.md +++ b/README.md @@ -650,15 +650,14 @@ Sometimes, there is no garauntee that the text, placeholder, or label you want t Example: To get the text 'hello' only within a section called 'messages', you could do: ```javascript -import {render, within} from 'react-testing-library' +import {within} from 'dom-testing-library' -// ... - -const {getByTestId} = render(/* stuff */) -const messagesSection = getByTestId('messages') -const hello = within(messagesSection).getByText('hello') +const {getByText} = within(document.body.getElementById('messages')) +const helloMessage = getByText('hello') ``` +Fun fact, `within` is actually just an alias to the `getQueriesForElement` function! + ## `getQueriesForElement` `getQueriesForElement` takes a DOM element and binds it to the raw query functions, allowing them diff --git a/src/index.js b/src/index.js index b77bab3b..90f93233 100644 --- a/src/index.js +++ b/src/index.js @@ -14,9 +14,9 @@ export * from './events' export * from './get-queries-for-element' export * from './pretty-dom' -// The original name of bindElementToQueries was weird -// The new name is better. Remove this in the next major version bump. export { + // The original name of bindElementToQueries was weird + // The new name is better. Remove this in the next major version bump. getQueriesForElement as bindElementToQueries, getQueriesForElement as within, } From 23f86b04047778895d54bbc5b9fc2a27961e0b80 Mon Sep 17 00:00:00 2001 From: "Kent C. Dodds" Date: Tue, 12 Jun 2018 12:02:42 -0600 Subject: [PATCH 3/3] Update README.md --- README.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index a1f049f3..6c240495 100644 --- a/README.md +++ b/README.md @@ -643,9 +643,11 @@ expect(submitButtons).toHaveLength(3) // expect 3 elements expect(submitButtons[0]).toBeInTheDOM() ``` -## `within` API +## `within` and `getQueriesForElement` APIs -Sometimes, there is no garauntee that the text, placeholder, or label you want to query is unique on the page. So you might want to explicity tell react-render-dom to get an element **only within** a particular section of the page. `within` is a helper function for this case. +`within` (an alias to `getQueriesForElement`) takes a DOM element and binds it to the raw query functions, allowing them +to be used without specifying a container. It is the recommended approach for libraries built on this API +and is in use in `react-testing-library` and `vue-testing-library`. Example: To get the text 'hello' only within a section called 'messages', you could do: @@ -656,14 +658,6 @@ const {getByText} = within(document.body.getElementById('messages')) const helloMessage = getByText('hello') ``` -Fun fact, `within` is actually just an alias to the `getQueriesForElement` function! - -## `getQueriesForElement` - -`getQueriesForElement` takes a DOM element and binds it to the raw query functions, allowing them -to be used without specifying a container. It is the recommended approach for libraries built on this API -and is in use in `react-testing-library` and `vue-testing-library`. - ## Debugging When you use any `get` calls in your test cases, the current state of the `container`