From c67414de3d9e09b4db256d253a51d17daa6a6cc5 Mon Sep 17 00:00:00 2001
From: Nicholas Boll <nicholas.boll@workday.com>
Date: Thu, 30 Jan 2020 10:13:14 -0700
Subject: [PATCH 1/7] feat: add more helpful debugging information to queries *
 Add element selector information for debugging (outlines element when you
 click on command) (fixes #103) * Add @testing-library/dom errors (from `get*`
 queries) to failure messages - these are more helpful than the generic
 `find*('input') does not exist` messages (fixes #103) * Add retryability to
 `findBy*` when multiple elements are found (fixes #83) * Add option to
 disable logging of all commands * `query*` and `find*` have a consistent code
 path and error messaging (fixes #103) * Remove usage of Cypress commands in
 queries (fixes #103)

---
 README.md                            |  35 ++++++-
 cypress/fixtures/test-app/index.html |  21 ++++
 cypress/integration/find.spec.js     |  63 +++++++++++-
 cypress/integration/query.spec.js    |  57 +++++++++--
 package.json                         |   2 +-
 src/index.js                         | 139 ++++++++++++++++++---------
 6 files changed, 250 insertions(+), 67 deletions(-)

diff --git a/README.md b/README.md
index ba56524..eaf7cfc 100644
--- a/README.md
+++ b/README.md
@@ -109,24 +109,49 @@ 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.queryByText('Button Text').should('exist')
-cy.queryByText('Non-existing Button Text').should('not.exist')
-cy.queryByLabelText('Label text', {timeout: 7000}).should('exist')
+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})
+
+// findAllByText _inside_ a form element
 cy.get('form').within(() => {
-  cy.findByText('Button Text').should('exist')
+  cy.findAllByText('Button Text').should('exist')
 })
 cy.get('form').then(subject => {
-  cy.findByText('Button Text', {container: subject}).should('exist')
+  cy.findAllByText('Button Text', {container: subject}).should('exist')
 })
+cy.get('form').findAllByText('Button Text').should('exist')
 ```
 
+### Differences 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`
 expects DOM nodes. When you pass a jQuery element as `container`, it will get
 the first DOM node from the collection and use that as the `container` parameter
 for the `DOM Testing Library` functions.
 
+`get*` queries are disabled. `find*` queries do not use the Promise API of
+`DOM Testing Library`, but instead forward to the `get*` queries and use Cypress'
+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
+to only 1 element, the following will work:
+
+```javascript
+cy.findAllByText('Some Text').should('have.length', 1)
+```
+
+Cypress handles actions when there is only one element found. For example, the following
+will work without having to limit to only 1 returned element. The `cy.click` will
+automatically fail if more than 1 element is returned by the `findAllByText`:
+
+```javascript
+cy.findAllByText('Some Text').click()
+```
+
 ## Other Solutions
 
 I'm not aware of any, if you are please [make a pull request][prs] and add it
diff --git a/cypress/fixtures/test-app/index.html b/cypress/fixtures/test-app/index.html
index 42a4b7e..36a3fc3 100644
--- a/cypress/fixtures/test-app/index.html
+++ b/cypress/fixtures/test-app/index.html
@@ -29,6 +29,9 @@ <h2>*ByLabel and *ByPlaceholder</h2>
 
     <label for="by-text-input-2">Label 2</label>
     <input type="text" placeholder="Input 2" id="by-text-input-2" />
+
+    <p>Intentionally inaccessible label for error checking</p>
+    <label>Label 3</label>
   </section>
   <section>
     <h2>*ByText</h2>
@@ -89,6 +92,24 @@ <h2>*AllByText</h2>
     <h2>*ByText on another page</h2>
     <a onclick='setTimeout(function() { window.location = "/cypress/fixtures/test-app/next-page.html"; }, 100);'>Next Page</a>
   </section>
+  <section>
+    <h2>Eventual existence</h2>
+    <button id="eventually-will-exist"></button>
+    <script>
+      setTimeout(() => {
+        document.querySelector('#eventually-will-exist').innerHTML = 'Eventually Exists'
+      }, 500)
+    </script>
+  </section>
+  <section>
+    <h2>Eventual non-existence</h2>
+    <button id="eventually-will-not-exist">Eventually not exists</button>
+    <script>
+      setTimeout(() => {
+        document.querySelector('#eventually-will-not-exist').remove()
+      }, 500)
+    </script>
+  </section>
 <!-- Prettier unindents the script tag below -->
 <script>
 document
diff --git a/cypress/integration/find.spec.js b/cypress/integration/find.spec.js
index 378e4b2..dc4825f 100644
--- a/cypress/integration/find.spec.js
+++ b/cypress/integration/find.spec.js
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines-per-function */
+
 describe('find* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')
@@ -86,6 +88,21 @@ describe('find* dom-testing-library commands', () => {
 
   /* Test the behaviour around these queries */
 
+  it('findByText should handle non-existence', () => {
+    cy.findByText('Does Not Exist')
+      .should('not.exist')
+  })
+
+  it('findByText should handle eventual existence', () => {
+    cy.findByText('Eventually Exists')
+      .should('exist')
+  })
+
+  it('findByText should handle eventual non-existence', () => {
+    cy.findByText('Eventually Not exists')
+      .should('not.exist')
+  })
+
   it("findByText with should('not.exist')", () => {
     cy.findAllByText(/^Button Text \d$/).should('exist')
     cy.findByText('Non-existing Button Text', {timeout: 100}).should(
@@ -123,23 +140,59 @@ describe('find* dom-testing-library commands', () => {
     cy.findByText('New Page Loaded').should('exist')
   })
 
+  it('findByText should set the Cypress element to the found element', () => {
+    // This test is a little strange since snapshots show what element
+    // is selected, but snapshots themselves don't give access to those
+    // elements. I had to make the implementation specific so that the `$el`
+    // is the `subject` when the log is added and the `$el` is the `value`
+    // when the log is changed. It would be better to extract the `$el` from
+    // each snapshot
+
+    cy.on('log:changed', (attrs, log) => {
+      if (log.get('name') === 'findByText') {
+        expect(log.get('$el')).to.have.text('Button Text 1')
+      }
+    })
+
+    cy.findByText('Button Text 1')
+  })
+
   it('findByText should error if no elements are found', () => {
     const regex = /Supercalifragilistic/
-    const errorMessage = `Timed out retrying: Expected to find element: 'findByText(${regex})', but never found it.`
+    const errorMessage = `Unable to find an element with the text: /Supercalifragilistic/`
+    cy.on('fail', err => {
+      expect(err.message).to.contain(errorMessage)
+    })
+
+    cy.findByText(regex, {timeout: 100}) // Every find query is implicitly a `.should('exist')
+  })
+
+  it('findByText should default to Cypress non-existence error message', () => {
+    const errorMessage = `Expected <button> not to exist in the DOM, but it was continuously found.`
+    cy.on('fail', err => {
+      expect(err.message).to.contain(errorMessage)
+    })
+
+    cy.findByText('Button Text 1', {timeout: 100})
+      .should('not.exist')
+  })
+
+  it('findByLabelText should forward useful error messages from @testing-library/dom', () => {
+    const errorMessage = `Found a label with the text of: Label 3, however no form control was found associated to that label.`
     cy.on('fail', err => {
-      expect(err.message).to.eq(errorMessage)
+      expect(err.message).to.contain(errorMessage)
     })
 
-    cy.findByText(regex, {timeout: 100}) // Doesn't explicitly need .should('exist') if it's the last element?
+    cy.findByLabelText('Label 3', {timeout: 100}).should('exist')
   })
 
   it('findByText finding multiple items should error', () => {
     const errorMessage = `Found multiple elements with the text: /^Button Text/i\n\n(If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).`
     cy.on('fail', err => {
-      expect(err.message).to.eq(errorMessage)
+      expect(err.message).to.contain(errorMessage)
     })
 
-    cy.findByText(/^Button Text/i)
+    cy.findByText(/^Button Text/i, {timeout: 100})
   })
 })
 
diff --git a/cypress/integration/query.spec.js b/cypress/integration/query.spec.js
index 912c3dd..7525ba3 100644
--- a/cypress/integration/query.spec.js
+++ b/cypress/integration/query.spec.js
@@ -1,3 +1,5 @@
+/* eslint-disable max-lines-per-function */
+
 describe('query* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')
@@ -95,12 +97,30 @@ describe('query* dom-testing-library commands', () => {
     })
   })
 
+  it('queryByText should set the Cypress element to the found element', (done) => {
+    // This test is a little strange since snapshots show what element
+    // is selected, but snapshots themselves don't give access to those
+    // elements. I had to make the implementation specific so that the `$el`
+    // is the `subject` when the log is added and the `$el` is the `value`
+    // when the log is changed. It would be better to extract the `$el` from
+    // each snapshot
+
+    cy.on('log:changed', (attrs, log) => {
+      if (log.get('name') === 'queryByText') {
+        expect(log.get('$el')).to.have.text('Button Text 1')
+        done()
+      }
+    })
+
+    cy.queryByText('Button Text 1')
+  })
+
   it('query* will return immediately, and never retry', () => {
     cy.queryByText('Next Page').click()
 
-    const errorMessage = `expected 'queryByText(\`New Page Loaded\`)' to exist in the DOM`
+    const errorMessage = `Unable to find an element with the text: New Page Loaded.`
     cy.on('fail', err => {
-      expect(err.message).to.eq(errorMessage)
+      expect(err.message).to.contain(errorMessage)
     })
 
     cy.queryByText('New Page Loaded', { timeout: 300 }).should('exist')
@@ -129,23 +149,42 @@ describe('query* dom-testing-library commands', () => {
       .and('not.exist')
   })
 
-  it('queryAllByText with a should(\'exist\') must provide selector error message', () => {
+  it('queryAllByText should forward existence error message from @testing-library/dom', () => {
     const text = 'Supercalifragilistic'
-    const errorMessage = `expected 'queryAllByText(\`${text}\`)' to exist in the DOM`
+    const errorMessage = `Unable to find an element with the text: Supercalifragilistic.`
+    cy.on('fail', err => {
+      expect(err.message).to.contain(errorMessage)
+    })
+
+    cy.queryAllByText(text, {timeout: 100}).should('exist')
+  })
+
+  it('queryByLabelText should forward useful error messages from @testing-library/dom', () => {
+    const errorMessage = `Found a label with the text of: Label 3, however no form control was found associated to that label.`
+    cy.on('fail', err => {
+      expect(err.message).to.contain(errorMessage)
+    })
+
+    cy.queryByLabelText('Label 3', {timeout: 100}).should('exist')
+  })
+
+  it('queryAllByText should default to Cypress non-existence error message', () => {
+    const errorMessage = `Expected <button> not to exist in the DOM, but it was continuously found.`
     cy.on('fail', err => {
-      expect(err.message).to.eq(errorMessage)
+      expect(err.message).to.contain(errorMessage)
     })
 
-    cy.queryAllByText(text, {timeout: 100}).should('exist') // NOT POSSIBLE WITH QUERYALL?
+    cy.queryAllByText('Button Text 1', {timeout: 100})
+      .should('not.exist')
   })
 
   it('queryByText finding multiple items should error', () => {
-    const errorMessage = `Found multiple elements with the text: /^queryByText/i\n\n(If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).`
+    const errorMessage = `Found multiple elements with the text: /^Button Text/i\n\n(If this is intentional, then use the \`*AllBy*\` variant of the query (like \`queryAllByText\`, \`getAllByText\`, or \`findAllByText\`)).`
     cy.on('fail', err => {
-      expect(err.message).to.eq(errorMessage)
+      expect(err.message).to.contain(errorMessage)
     })
 
-    cy.queryByText(/^queryByText/i)
+    cy.queryByText(/^Button Text/i)
   })
 })
 
diff --git a/package.json b/package.json
index 67c72fb..3d2a6f0 100644
--- a/package.json
+++ b/package.json
@@ -15,7 +15,7 @@
     "test:cypress:run": "cypress run",
     "test:cypress:open": "cypress open",
     "test:cypress": "npm run test:cypress:run",
-    "test:cypress:dev": "test:cypress:open",
+    "test:cypress:dev": "npm run test:cypress:open",
     "validate": "kcd-scripts validate build,lint,test",
     "setup": "npm install && npm run validate -s"
   },
diff --git a/src/index.js b/src/index.js
index 85c7713..7021bfc 100644
--- a/src/index.js
+++ b/src/index.js
@@ -4,6 +4,7 @@ import {getContainer} from './utils'
 const getDefaultCommandOptions = () => {
   return {
     timeout: Cypress.config().defaultCommandTimeout,
+    log: true,
   }
 }
 
@@ -32,14 +33,14 @@ const getCommands = getQueryNames.map(queryName => {
 })
 
 const queryCommands = queryQueryNames.map(queryName => {
-  return createCommand(queryName, queryName)
+  return createCommand(queryName, queryName.replace(queryRegex, 'get'))
 })
 
 const findCommands = findQueryNames.map(queryName => {
   // dom-testing-library find* queries use a promise to look for an element, but that doesn't work well with Cypress retryability
   // Use the query* commands so that we can lean on Cypress to do the retry for us
   // When it does return a null or empty array, Cypress will retry until the assertions are satisfied or the command times out
-  return createCommand(queryName, queryName.replace(findRegex, 'query'))
+  return createCommand(queryName, queryName.replace(findRegex, 'get'))
 })
 
 function createCommand(queryName, implementationName) {
@@ -49,13 +50,13 @@ function createCommand(queryName, implementationName) {
     command: (prevSubject, ...args) => {
       const lastArg = args[args.length - 1]
       const defaults = getDefaultCommandOptions()
-      const waitOptions =
+      const options =
         typeof lastArg === 'object' ? {...defaults, ...lastArg} : defaults
 
       const queryImpl = queries[implementationName]
       const baseCommandImpl = doc => {
         const container = getContainer(
-          waitOptions.container || prevSubject || doc,
+          options.container || prevSubject || doc,
         )
         return queryImpl(container, ...args)
       }
@@ -63,59 +64,103 @@ function createCommand(queryName, implementationName) {
 
       const inputArr = args.filter(filterInputs)
 
+      const getSelector = () => `${queryName}(${queryArgument(args)})`
+
+      const win = cy.state('window')
+
       const consoleProps = {
         // TODO: Would be good to completely separate out the types of input into their own properties
         input: inputArr,
+        Selector: getSelector(),
+        'Applied To': getContainer(
+          options.container || prevSubject || win.document,
+        )
       }
 
-      Cypress.log({
-        $el: inputArr,
-        name: queryName,
-        message: inputArr,
-        consoleProps: () => consoleProps,
-      })
+      if (options.log) {
+        options._log = Cypress.log({
+          name: queryName,
+          message: inputArr,
+          consoleProps: () => consoleProps,
+        })
+      }
 
-      return cy
-        .window({log: false})
-        .then({timeout: waitOptions.timeout + 100}, thenArgs => {
-          const getValue = () => {
-            const value = commandImpl(thenArgs.document)
-            const result = Cypress.$(value)
-
-            // Overriding the selector of the jquery object because it's displayed in the long message of .should('exist') failure message
-            // Hopefully it makes it clearer, because I find the normal response of "Expected to find element '', but never found it" confusing
-            result.selector = `${queryName}(${queryArgument(args)})`
-
-            if (result.length > 0) {
-              consoleProps.yielded = result.toArray()
-            }
-
-            return result
-          }
-
-          const resolveValue = () => {
-            // retry calling "getValue" until following assertions pass or this command times out
-            return Cypress.Promise.try(getValue).then(value => {
-              return cy.verifyUpcomingAssertions(value, waitOptions, {
-                onRetry: resolveValue,
-              })
-            })
-          }
+      const getValue = () => {
+        const value = commandImpl(win.document)
+
+        const result = Cypress.$(value)
+        if (value && options._log) {
+          options._log.set('$el', result)
+        }
 
-          if (queryRegex.test(queryName)) {
-            // For get* queries, do not retry
-            return getValue()
-          }
+        // Overriding the selector of the jquery object because it's displayed in the long message of .should('exist') failure message
+        // Hopefully it makes it clearer, because I find the normal response of "Expected to find element '', but never found it" confusing
+        result.selector = getSelector()
 
-          return resolveValue().then(subject => {
-            // Remove the error that occurred because it is irrelevant now
-            if (consoleProps.error) {
-              delete consoleProps.error
-            }
+        consoleProps.elements = result.length
+        if (result.length === 1) {
+          consoleProps.yielded = result.toArray()[0];
+        } else if (result.length > 0) {
+          consoleProps.yielded = result.toArray();
+        }
 
-            return subject
-          })
+        if (result.length > 1 && !/all/i.test(queryName)) {
+          // Is this useful?
+          throw Error(`Found multiple elements with the text: ${queryArgument(args)}`)
+        }
+
+        return result
+      }
+
+      if (queryRegex.test(queryName)) {
+        // make the timeout extremely short to ensure `query*` commands pass or fail instantly
+        options.timeout = 0
+      }
+
+      let error
+      // Errors will be thrown by @testing-library/dom, but a query might be followed by `.should('not.exist')`
+      // We just need to capture the error thrown by @testing-library/dom and return an empty jQuery NodeList
+      // to allow Cypress assertions errors to happen naturally. If an assertion fails, we'll have a helpful
+      // error message handy to pass on to the user
+      const catchQueryError = err => {
+        error = err
+        const result = Cypress.$()
+        result.selector = getSelector()
+        return result
+      }
+
+      const resolveValue = () => {
+        // retry calling "getValue" until following assertions pass or this command times out
+        return Cypress.Promise.try(getValue)
+          .catch(catchQueryError)
+          .then(value => {
+            return cy.verifyUpcomingAssertions(value, options, {
+              onRetry: resolveValue,
+              onFail: () => {
+                // We want to override Cypress's normal non-existence message with @testing-library/dom's more helpful ones
+                if (error) {
+                  options.error = error
+                }
+              }
+            })
         })
+      }
+
+      return resolveValue().then(subject => {
+        // Remove the error that occurred because it is irrelevant now
+        if (consoleProps.error) {
+          delete consoleProps.error
+        }
+        if (options._log) {
+          options._log.snapshot()
+        }
+
+        return subject
+      }).finally(() => {
+        if (options._log) {
+          options._log.end()
+        }
+      })
     },
   }
 }

From b58f74779499d1e09b87e566a95e0805f8254cb5 Mon Sep 17 00:00:00 2001
From: Nicholas Boll <nicholas.boll@workday.com>
Date: Thu, 30 Jan 2020 22:34:52 -0700
Subject: [PATCH 2/7] feat: add ability for queries to inherit previous subject
 * Fixes #109 without breaking change caused by #100

---
 cypress/integration/find.spec.js | 25 ++++++++++++++++---
 src/__tests__/add-commands.js    |  1 +
 src/add-commands.js              |  4 ++--
 src/index.js                     | 41 ++++++++++++++++++++++----------
 4 files changed, 54 insertions(+), 17 deletions(-)

diff --git a/cypress/integration/find.spec.js b/cypress/integration/find.spec.js
index 4540547..6258825 100644
--- a/cypress/integration/find.spec.js
+++ b/cypress/integration/find.spec.js
@@ -110,15 +110,28 @@ describe('find* dom-testing-library commands', () => {
     )
   })
 
+  it('findByText with a previous subject', () => {
+    cy.get('#nested')
+      .findByText('Button Text 1', { fallbackToPreviousFunctionality: false })
+      .should('not.exist')
+    cy.get('#nested')
+      .findByText('Button Text 2')
+      .should('exist')
+  })
+
   it('findByText within', () => {
     cy.get('#nested').within(() => {
-      cy.findByText('Button Text 2').click()
+      cy.findByText('Button Text 1').should('not.exist')
+      cy.findByText('Button Text 2').should('exist')
     })
   })
 
   it('findByText in container', () => {
-    return cy.get('#nested').then(subject => {
-      cy.findByText(/^Button Text/, {container: subject}).click()
+    // 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')
     })
   })
 
@@ -181,6 +194,12 @@ describe('find* dom-testing-library commands', () => {
 
     cy.findByText(/^Button Text/i, {timeout: 100})
   })
+
+  it('findByText should not break existing code', () => {
+    cy.window()
+      .findByText('Button Text 1')
+      .should('exist')
+  })
 })
 
 /* global cy */
diff --git a/src/__tests__/add-commands.js b/src/__tests__/add-commands.js
index e754820..0a9e590 100644
--- a/src/__tests__/add-commands.js
+++ b/src/__tests__/add-commands.js
@@ -11,6 +11,7 @@ test('adds commands to Cypress', () => {
   commands.forEach(({name}, index) => {
     expect(addMock.mock.calls[index]).toMatchObject([
       name,
+      {},
       // We get a new function that is `command.bind(null, cy)` i.e. global `cy` passed into the first argument.
       // The commands themselves will be tested separately in the Cypress end-to-end tests.
       expect.any(Function),
diff --git a/src/add-commands.js b/src/add-commands.js
index 43e8f14..1b2171c 100644
--- a/src/add-commands.js
+++ b/src/add-commands.js
@@ -1,7 +1,7 @@
 import {commands} from './'
 
-commands.forEach(({name, command}) => {
-  Cypress.Commands.add(name, command)
+commands.forEach(({name, command, options = {}}) => {
+  Cypress.Commands.add(name, options, command)
 })
 
 /* global Cypress */
diff --git a/src/index.js b/src/index.js
index 8beb5e0..8c5f28d 100644
--- a/src/index.js
+++ b/src/index.js
@@ -4,6 +4,7 @@ import {getContainer} from './utils'
 const getDefaultCommandOptions = () => {
   return {
     timeout: Cypress.config().defaultCommandTimeout,
+    fallbackToPreviousFunctionality: true,
     log: true,
   }
 }
@@ -37,27 +38,24 @@ const queryCommands = queryQueryNames.map(queryName => {
 })
 
 const findCommands = findQueryNames.map(queryName => {
-  // dom-testing-library find* queries use a promise to look for an element, but that doesn't work well with Cypress retryability
-  // Use the query* commands so that we can lean on Cypress to do the retry for us
-  // When it does return a null or empty array, Cypress will retry until the assertions are satisfied or the command times out
   return createCommand(queryName, queryName.replace(findRegex, 'get'))
 })
 
 function createCommand(queryName, implementationName) {
   return {
     name: queryName,
-    command: (...args) => {
+    options: {prevSubject: ['optional', 'document', 'element', 'window']},
+    command: (prevSubject, ...args) => {
       const lastArg = args[args.length - 1]
       const defaults = getDefaultCommandOptions()
       const options =
         typeof lastArg === 'object' ? {...defaults, ...lastArg} : defaults
 
       const queryImpl = queries[implementationName]
-      const baseCommandImpl = doc => {
-        const container = getContainer(options.container || doc)
-        return queryImpl(container, ...args)
+      const baseCommandImpl = container => {
+        return queryImpl(getContainer(container), ...args)
       }
-      const commandImpl = doc => baseCommandImpl(doc)
+      const commandImpl = container => baseCommandImpl(container)
 
       const inputArr = args.filter(filterInputs)
 
@@ -70,7 +68,7 @@ function createCommand(queryName, implementationName) {
         input: inputArr,
         Selector: getSelector(),
         'Applied To': getContainer(
-          options.container || win.document,
+          options.container || prevSubject || win.document,
         )
       }
 
@@ -82,8 +80,8 @@ function createCommand(queryName, implementationName) {
         })
       }
 
-      const getValue = () => {
-        const value = commandImpl(win.document)
+      const getValue = (container = options.container || prevSubject || win.document) => {
+        const value = commandImpl(container)
 
         const result = Cypress.$(value)
         if (value && options._log) {
@@ -115,20 +113,35 @@ function createCommand(queryName, implementationName) {
       }
 
       let error
+      let failedNewFunctionality = false
+      let failedOldFunctionality = false
       // Errors will be thrown by @testing-library/dom, but a query might be followed by `.should('not.exist')`
       // We just need to capture the error thrown by @testing-library/dom and return an empty jQuery NodeList
       // to allow Cypress assertions errors to happen naturally. If an assertion fails, we'll have a helpful
       // error message handy to pass on to the user
       const catchQueryError = err => {
         error = err
+        failedOldFunctionality = true
         const result = Cypress.$()
         result.selector = getSelector()
         return result
       }
 
+      // Before https://github.com/testing-library/cypress-testing-library/pull/100,
+      // queries were run without being scoped to previous subjects. There is code now that depends
+      // on functionality before #100. See if we can succeed using old functionality before finally failing
+      // This function can be removed as a breaking change
+      const catchAndTryOldFunctionality = err => {
+        error = err
+        failedNewFunctionality = true
+        const container = options.fallbackToPreviousFunctionality ? options.container || win.document : undefined
+        return getValue(container)
+      }
+
       const resolveValue = () => {
         // retry calling "getValue" until following assertions pass or this command times out
         return Cypress.Promise.try(getValue)
+          .catch(catchAndTryOldFunctionality)
           .catch(catchQueryError)
           .then(value => {
             return cy.verifyUpcomingAssertions(value, options, {
@@ -155,7 +168,11 @@ function createCommand(queryName, implementationName) {
         return subject
       }).finally(() => {
         if (options._log) {
-          options._log.end()
+          if (failedNewFunctionality && !failedOldFunctionality) {
+            options._log.error(Error(`@testing-library/cypress will soon only use previous subjects when queries are added to a chain of commands. We've detected an instance where the this functionality failed, but the old functionality passed. Please use cy.${queryName}(${queryArgument(args)}) instead of continuing from a previous chain.`))
+          } else {
+            options._log.end()
+          }
         }
       })
     },

From 1f14ce132f1a422cd9a6508f609c9fefec3d5309 Mon Sep 17 00:00:00 2001
From: Nicholas Boll <nicholas.boll@workday.com>
Date: Thu, 30 Jan 2020 22:40:05 -0700
Subject: [PATCH 3/7] feat: add parent/child log type detection

---
 cypress/integration/find.spec.js | 22 ++++++++++++++++++++++
 src/index.js                     |  1 +
 2 files changed, 23 insertions(+)

diff --git a/cypress/integration/find.spec.js b/cypress/integration/find.spec.js
index 6258825..efa5652 100644
--- a/cypress/integration/find.spec.js
+++ b/cypress/integration/find.spec.js
@@ -200,6 +200,28 @@ describe('find* dom-testing-library commands', () => {
       .findByText('Button Text 1')
       .should('exist')
   })
+
+  it('findByText should show as a parent command if it starts a chain', () => {
+    const assertLog = (attrs, log) => {
+      if(log.get('name') === 'findByText') {
+        expect(log.get('type')).to.equal('parent')
+        cy.off('log:added', assertLog)
+      }
+    }
+    cy.on('log:added', assertLog)
+    cy.findByText('Button Text 1')
+  })
+
+  it('findByText should show as a child command if it continues a chain', () => {
+    const assertLog = (attrs, log) => {
+      if(log.get('name') === 'findByText') {
+        expect(log.get('type')).to.equal('child')
+        cy.off('log:added', assertLog)
+      }
+    }
+    cy.on('log:added', assertLog)
+    cy.get('body').findByText('Button Text 1')
+  })
 })
 
 /* global cy */
diff --git a/src/index.js b/src/index.js
index 8c5f28d..14c49b9 100644
--- a/src/index.js
+++ b/src/index.js
@@ -74,6 +74,7 @@ function createCommand(queryName, implementationName) {
 
       if (options.log) {
         options._log = Cypress.log({
+          type: prevSubject ? 'child' : 'parent',
           name: queryName,
           message: inputArr,
           consoleProps: () => consoleProps,

From 217a2898123aa50f6c1bfad95cb0751b90474b18 Mon Sep 17 00:00:00 2001
From: Nicholas Boll <nicholas.boll@workday.com>
Date: Fri, 31 Jan 2020 12:30:02 -0700
Subject: [PATCH 4/7] chore: implement feedback

---
 cypress/.eslintrc                 |  6 ++++++
 cypress/integration/find.spec.js  |  6 ++----
 cypress/integration/query.spec.js |  2 --
 src/index.js                      | 32 ++++++++++++++-----------------
 4 files changed, 22 insertions(+), 24 deletions(-)
 create mode 100644 cypress/.eslintrc

diff --git a/cypress/.eslintrc b/cypress/.eslintrc
new file mode 100644
index 0000000..352fd0c
--- /dev/null
+++ b/cypress/.eslintrc
@@ -0,0 +1,6 @@
+{
+  "rules": {
+    "max-lines-per-function": "off",
+    "jest/valid-expect-in-promise": "off"
+  }
+}
diff --git a/cypress/integration/find.spec.js b/cypress/integration/find.spec.js
index efa5652..29c0554 100644
--- a/cypress/integration/find.spec.js
+++ b/cypress/integration/find.spec.js
@@ -1,5 +1,3 @@
-/* eslint-disable max-lines-per-function */
-
 describe('find* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')
@@ -164,7 +162,7 @@ describe('find* dom-testing-library commands', () => {
       expect(err.message).to.contain(errorMessage)
     })
 
-    cy.findByText(regex, {timeout: 100}) // Every find query is implicitly a `.should('exist')
+    cy.findByText(regex, {timeout: 100})
   })
 
   it('findByText should default to Cypress non-existence error message', () => {
@@ -183,7 +181,7 @@ describe('find* dom-testing-library commands', () => {
       expect(err.message).to.contain(errorMessage)
     })
 
-    cy.findByLabelText('Label 3', {timeout: 100}).should('exist')
+    cy.findByLabelText('Label 3', {timeout: 100})
   })
 
   it('findByText finding multiple items should error', () => {
diff --git a/cypress/integration/query.spec.js b/cypress/integration/query.spec.js
index 7525ba3..d39342d 100644
--- a/cypress/integration/query.spec.js
+++ b/cypress/integration/query.spec.js
@@ -1,5 +1,3 @@
-/* eslint-disable max-lines-per-function */
-
 describe('query* dom-testing-library commands', () => {
   beforeEach(() => {
     cy.visit('cypress/fixtures/test-app/')
diff --git a/src/index.js b/src/index.js
index 14c49b9..e210cb4 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,14 +1,6 @@
 import {configure, queries} from '@testing-library/dom'
 import {getContainer} from './utils'
 
-const getDefaultCommandOptions = () => {
-  return {
-    timeout: Cypress.config().defaultCommandTimeout,
-    fallbackToPreviousFunctionality: true,
-    log: true,
-  }
-}
-
 const queryNames = Object.keys(queries)
 
 const getRegex = /^get/
@@ -47,7 +39,13 @@ function createCommand(queryName, implementationName) {
     options: {prevSubject: ['optional', 'document', 'element', 'window']},
     command: (prevSubject, ...args) => {
       const lastArg = args[args.length - 1]
-      const defaults = getDefaultCommandOptions()
+      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,
+        log: true,
+      }
       const options =
         typeof lastArg === 'object' ? {...defaults, ...lastArg} : defaults
 
@@ -100,7 +98,7 @@ function createCommand(queryName, implementationName) {
           consoleProps.yielded = result.toArray();
         }
 
-        if (result.length > 1 && !/all/i.test(queryName)) {
+        if (result.length > 1 && !/All/.test(queryName)) {
           // Is this useful?
           throw Error(`Found multiple elements with the text: ${queryArgument(args)}`)
         }
@@ -108,14 +106,12 @@ function createCommand(queryName, implementationName) {
         return result
       }
 
-      if (queryRegex.test(queryName)) {
-        // make the timeout extremely short to ensure `query*` commands pass or fail instantly
-        options.timeout = 0
-      }
-
-      let error
+      // This state tracking is not ideal, but it allows detection of compatibility mode for a warning message
       let failedNewFunctionality = false
       let failedOldFunctionality = false
+
+      let error
+
       // Errors will be thrown by @testing-library/dom, but a query might be followed by `.should('not.exist')`
       // We just need to capture the error thrown by @testing-library/dom and return an empty jQuery NodeList
       // to allow Cypress assertions errors to happen naturally. If an assertion fails, we'll have a helpful
@@ -135,7 +131,7 @@ function createCommand(queryName, implementationName) {
       const catchAndTryOldFunctionality = err => {
         error = err
         failedNewFunctionality = true
-        const container = options.fallbackToPreviousFunctionality ? options.container || win.document : undefined
+        const container = options.fallbackRetryWithoutPreviousSubject ? options.container || win.document : undefined
         return getValue(container)
       }
 
@@ -170,7 +166,7 @@ function createCommand(queryName, implementationName) {
       }).finally(() => {
         if (options._log) {
           if (failedNewFunctionality && !failedOldFunctionality) {
-            options._log.error(Error(`@testing-library/cypress will soon only use previous subjects when queries are added to a chain of commands. We've detected an instance where the this functionality failed, but the old functionality passed. Please use cy.${queryName}(${queryArgument(args)}) instead of continuing from a previous chain.`))
+            options._log.error(Error(`@testing-library/cypress will eventually only use previous subjects when queries are added to a chain of commands. We've detected an instance where the this functionality failed, but the old functionality passed (so your test may break in a future version). Please use cy.${queryName}(${queryArgument(args)}) instead of continuing from a previous chain.`))
           } else {
             options._log.end()
           }

From aa76c5023b5844e34a63d6891464d78e7fa53bd9 Mon Sep 17 00:00:00 2001
From: Nicholas Boll <nicholas.boll@workday.com>
Date: Fri, 31 Jan 2020 17:17:34 -0700
Subject: [PATCH 5/7] docs: update readme to complete my thought process

---
 README.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 897ab2d..36cb80e 100644
--- a/README.md
+++ b/README.md
@@ -144,12 +144,10 @@ 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.
 
 `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
-cy.findAllByText('Some Text').should('have.length', 1)
-```
+Cypress built-in commands work. `findAll*` is preferred to `find*` queries.
+`find*` commands will fail if more than one element is found that matches the criteria
+which is not how built-in Cypress commands work, but is provided for closer compatibility
+to other Testing Libraries.
 
 Cypress handles actions when there is only one element found. For example, the following
 will work without having to limit to only 1 returned element. The `cy.click` will
@@ -159,6 +157,14 @@ automatically fail if more than 1 element is returned by the `findAllByText`:
 cy.findAllByText('Some Text').click()
 ```
 
+If you intend to enforce only 1 element is returned by a selector, the following
+examples will both fail if more than one element is found.
+
+```javascript
+cy.findAllByText('Some Text').should('have.length', 1)
+cy.findByText('Some Text').should('exist')
+```
+
 ## Other Solutions
 
 I'm not aware of any, if you are please [make a pull request][prs] and add it

From a5bfc6f89e379c6ce0b42ed43ae184c9cee33eca Mon Sep 17 00:00:00 2001
From: "Kent C. Dodds" <me+github@kentcdodds.com>
Date: Sat, 1 Feb 2020 20:40:20 -0700
Subject: [PATCH 6/7] slightly simplify config fn

---
 src/index.js | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/src/index.js b/src/index.js
index 23bd681..8b92fbc 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,13 +1,12 @@
-import {configure, queries} from '@testing-library/dom'
+import {configure as configureDTL, 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
+function configure({fallbackRetryWithoutPreviousSubject, ...config}) {
+  if (fallbackRetryWithoutPreviousSubject != null) {
+    globalFallbackRetryWithoutPreviousSubject = fallbackRetryWithoutPreviousSubject
   }
-  configure(configDelta)
+  return configureDTL(config)
 }
 
 const queryNames = Object.keys(queries)
@@ -213,7 +212,7 @@ function queryArgument(args) {
 
 const commands = [...getCommands, ...findCommands, ...queryCommands]
 
-export {commands, configureFn as configure}
+export {commands, configure}
 
 /* eslint no-new-func:0, complexity:0 */
 /* globals Cypress, cy */

From d85d918196703050df93eda73ca256b25a327068 Mon Sep 17 00:00:00 2001
From: "Kent C. Dodds" <me+github@kentcdodds.com>
Date: Sat, 1 Feb 2020 20:40:54 -0700
Subject: [PATCH 7/7] Update README.md

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 36cb80e..19d9bce 100644
--- a/README.md
+++ b/README.md
@@ -106,7 +106,8 @@ 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:
+To configure DOM Testing Library, use the following custom command:
+
 ```javascript
 cy.configureCypressTestingLibrary(config)
 ```