feat: add ability to configure

Author: NicholasBoll

.all-contributorsrc

@@ -6,7 +6,7 @@
   ],
   "imageSize": 100,
   "commit": false,
-  "skipCi": true,
+  "skipCi": false,
   "contributors": [
     {
       "login": "kentcdodds",
@@ -271,6 +271,15 @@
         "code",
         "test"
       ]
+    },
+    {
+      "login": "FlopieUtd",
+      "name": "FlopieUtd",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/23555863?v=4",
+      "profile": "https://github.com/FlopieUtd",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "repoType": "github",

README.md

@@ -61,6 +61,7 @@ This allows you to use all the useful
 - [Installation](#installation)
   - [With TypeScript](#with-typescript)
 - [Usage](#usage)
+  - [Differences from DOM Testing Library](#differences-from-dom-testing-library)
 - [Other Solutions](#other-solutions)
 - [Contributors](#contributors)
 - [LICENSE](#license)
@@ -95,7 +96,7 @@ and should be added as follows in `tsconfig.json`:
 
 Add this line to your project's `cypress/support/commands.js`:
 
-```
+```javascript
 import '@testing-library/cypress/add-commands'
 ```
 
@@ -105,14 +106,19 @@ and `queryAllBy` commands.
 
 You can find [all Library definitions here](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/testing-library__cypress/index.d.ts).
 
+To configure DOM Testing Library, use the following:
+```javascript
+cy.configureCypressTestingLibrary(config)
+```
+
 To show some simple examples (from
 [cypress/integration/query.spec.js](cypress/integration/query.spec.js) or [cypress/integration/find.spec.js](cypress/integration/find.spec.js)):
 
 ```javascript
 cy.queryAllByText('Button Text').should('exist')
 cy.queryAllByText('Non-existing Button Text').should('not.exist')
 cy.queryAllByLabelText('Label text', {timeout: 7000}).should('exist')
-cy.findAllByText('Jackie Chan').click({multiple: true})
+cy.findAllByText('Jackie Chan').click();
 
 // findAllByText _inside_ a form element
 cy.get('form').within(() => {
@@ -124,7 +130,7 @@ cy.get('form').then(subject => {
 cy.get('form').findAllByText('Button Text').should('exist')
 ```
 
-### Differences DOM Testing Library
+### Differences from DOM Testing Library
 
 `Cypress Testing Library` supports both jQuery elements and DOM nodes. This is
 necessary because Cypress uses jQuery elements, while `DOM Testing Library`
@@ -137,7 +143,8 @@ for the `DOM Testing Library` functions.
 built-in retryability using error messages from `get*` APIs to forward as error
 messages if a query fails. `query*` also uses `get*` APIs, but disables retryability.
 
-`findBy*` is less useful in Cypress compared to `findAllBy*`. If you intend to limit
+`findAll*` can select more than one element and is closer in functionality to how
+Cypress built-in commands work. is less useful in Cypress compared to `findAllBy*`. If you intend to limit
 to only 1 element, the following will work:
 
 ```javascript
@@ -199,6 +206,7 @@ Thanks goes to these people ([emoji key][emojis]):
     <td align="center"><a href="https://www.franck-abgrall.me/"><img src="https://avatars3.githubusercontent.com/u/9840435?v=4" width="100px;" alt=""/><br /><sub><b>Franck Abgrall</b></sub></a><br /><a href="https://github.com/testing-library/cypress-testing-library/pulls?q=is%3Apr+reviewed-by%3Akefranabg" title="Reviewed Pull Requests">👀</a></td>
     <td align="center"><a href="http://twitter.com/tlrobinson"><img src="https://avatars0.githubusercontent.com/u/18193?v=4" width="100px;" alt=""/><br /><sub><b>Tom Robinson</b></sub></a><br /><a href="https://github.com/testing-library/cypress-testing-library/commits?author=tlrobinson" title="Code">💻</a> <a href="https://github.com/testing-library/cypress-testing-library/commits?author=tlrobinson" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/NicholasBoll"><img src="https://avatars2.githubusercontent.com/u/338257?v=4" width="100px;" alt=""/><br /><sub><b>Nicholas Boll</b></sub></a><br /><a href="https://github.com/testing-library/cypress-testing-library/commits?author=NicholasBoll" title="Code">💻</a> <a href="https://github.com/testing-library/cypress-testing-library/commits?author=NicholasBoll" title="Tests">⚠️</a></td>
+    <td align="center"><a href="https://github.com/FlopieUtd"><img src="https://avatars3.githubusercontent.com/u/23555863?v=4" width="100px;" alt=""/><br /><sub><b>FlopieUtd</b></sub></a><br /><a href="https://github.com/testing-library/cypress-testing-library/commits?author=FlopieUtd" title="Documentation">📖</a></td>
   </tr>
 </table>
 

cypress/integration/configure.spec.js

@@ -0,0 +1,18 @@
+/// <reference types="cypress" />
+describe('configuring fallback globally', () => {
+  beforeEach(() => {
+    cy.visit('cypress/fixtures/test-app/')
+    cy.configureCypressTestingLibrary({ fallbackRetryWithoutPreviousSubject: false })
+  })
+
+  it('findByText with a previous subject', () => {
+    cy.get('#nested')
+      .findByText('Button Text 1')
+      .should('not.exist')
+    cy.get('#nested')
+      .findByText('Button Text 2')
+      .should('exist')
+  })
+})
+
+/* global cy */

cypress/integration/find.spec.js

@@ -1,3 +1,4 @@
+/// <reference types="cypress" />
 describe('find* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')
@@ -110,7 +111,7 @@ describe('find* dom-testing-library commands', () => {
 
   it('findByText with a previous subject', () => {
     cy.get('#nested')
-      .findByText('Button Text 1', { fallbackToPreviousFunctionality: false })
+      .findByText('Button Text 1', { fallbackRetryWithoutPreviousSubject: false })
       .should('not.exist')
     cy.get('#nested')
       .findByText('Button Text 2')
@@ -125,8 +126,6 @@ describe('find* dom-testing-library commands', () => {
   })
 
   it('findByText in container', () => {
-    // NOTE: Cypress' `then` doesn't actually return a promise
-    // eslint-disable-next-line jest/valid-expect-in-promise
     cy.get('#nested').then(subject => {
       cy.findByText('Button Text 1', {container: subject}).should('not.exist')
       cy.findByText('Button Text 2', {container: subject}).should('exist')

cypress/integration/query.spec.js

@@ -1,3 +1,4 @@
+/// <reference types="cypress" />
 describe('query* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')

src/__tests__/add-commands.js

@@ -7,7 +7,7 @@ test('adds commands to Cypress', () => {
 
   require('../add-commands')
 
-  expect(addMock).toHaveBeenCalledTimes(commands.length)
+  expect(addMock).toHaveBeenCalledTimes(commands.length + 1) // we're also adding a configuration command
   commands.forEach(({name}, index) => {
     expect(addMock.mock.calls[index]).toMatchObject([
       name,

src/add-commands.js

@@ -1,7 +1,11 @@
-import {commands} from './'
+import {configure, commands} from './'
 
 commands.forEach(({name, command, options = {}}) => {
   Cypress.Commands.add(name, options, command)
 })
 
+Cypress.Commands.add('configureCypressTestingLibrary', config => {
+  configure(config)
+})
+
 /* global Cypress */

src/index.js

@@ -1,6 +1,15 @@
 import {configure, queries} from '@testing-library/dom'
 import {getContainer} from './utils'
 
+let globalFallbackRetryWithoutPreviousSubject = true
+const configureFn = configDelta => {
+  if (configDelta.fallbackRetryWithoutPreviousSubject != null) {
+    globalFallbackRetryWithoutPreviousSubject = configDelta.fallbackRetryWithoutPreviousSubject
+    delete configDelta.fallbackRetryWithoutPreviousSubject
+  }
+  configure(configDelta)
+}
+
 const queryNames = Object.keys(queries)
 
 const getRegex = /^get/
@@ -42,8 +51,9 @@ function createCommand(queryName, implementationName) {
       const defaults = {
         // make the timeout extremely short to ensure `query*` commands pass or fail instantly
         timeout: queryRegex.test(queryName) ? 0 : Cypress.config().defaultCommandTimeout,
-        //
-        fallbackRetryWithoutPreviousSubject: true,
+        // setting this to false will disable the fallback to querying without a previous subject
+        // This is to prevent breaking changes, but also allow for prevSubject scoping
+        fallbackRetryWithoutPreviousSubject: globalFallbackRetryWithoutPreviousSubject,
         log: true,
       }
       const options =
@@ -93,9 +103,9 @@ function createCommand(queryName, implementationName) {
 
         consoleProps.elements = result.length
         if (result.length === 1) {
-          consoleProps.yielded = result.toArray()[0];
+          consoleProps.yielded = result.toArray()[0]
         } else if (result.length > 0) {
-          consoleProps.yielded = result.toArray();
+          consoleProps.yielded = result.toArray()
         }
 
         if (result.length > 1 && !/All/.test(queryName)) {
@@ -203,7 +213,7 @@ function queryArgument(args) {
 
 const commands = [...getCommands, ...findCommands, ...queryCommands]
 
-export {commands, configure}
+export {commands, configureFn as configure}
 
 /* eslint no-new-func:0, complexity:0 */
 /* globals Cypress, cy */