Merge branch 'master' into pr/pass-through-data-transfer-object

Author: johnjesse

.all-contributorsrc

@@ -1309,7 +1309,8 @@
       "profile": "https://codepen.io/ariperkkio/",
       "contributions": [
         "bug",
-        "code"
+        "code",
+        "doc"
       ]
     },
     {
@@ -1320,6 +1321,15 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "ph-fritsche",
+      "name": "Philipp Fritsche",
+      "avatar_url": "https://avatars.githubusercontent.com/u/39068198?v=4",
+      "profile": "https://github.com/ph-fritsche",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "repoHost": "https://github.com"

.github/workflows/validate.yml

@@ -26,6 +26,9 @@ jobs:
 
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v2
+        with:
+          # required by codecov/codecov-action
+          fetch-depth: 0
 
       - name: ⎔ Setup node
         uses: actions/setup-node@v1
@@ -42,6 +45,9 @@ jobs:
 
       - name: ⬆️ Upload coverage report
         uses: codecov/codecov-action@v1
+        with:
+          fail_ci_if_error: true
+          flags: node-${{ matrix.node }}
 
   release:
     needs: main

CONTRIBUTING.md

@@ -32,18 +32,6 @@ Please make sure to run the tests before you commit your changes. You can run
 `npm run test:update` which will update any snapshots that need updating. Make
 sure to include those changes (if they exist) in your commit.
 
-### opt into git hooks
-
-There are git hooks set up with this project that are automatically installed
-when you install dependencies. They're really handy, but are turned off by
-default (so as to not hinder new contributors). You can opt into these by
-creating a file called `.opt-in` at the root of the project and putting this
-inside:
-
-```
-pre-commit
-```
-
 ## Help needed
 
 Please checkout the [the open issues][issues]

README.md

@@ -300,10 +300,11 @@ Thanks goes to these people ([emoji key][emojis]):
     <td align="center"><a href="https://github.com/romain-trotard"><img src="https://avatars0.githubusercontent.com/u/17161484?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Romain Trotard</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/commits?author=romain-trotard" title="Code">💻</a></td>
     <td align="center"><a href="http://www.thomasmarshall.com"><img src="https://avatars0.githubusercontent.com/u/770763?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Thomas Marshall</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/commits?author=thomasmarshall" title="Code">💻</a> <a href="https://github.com/testing-library/dom-testing-library/commits?author=thomasmarshall" title="Tests">⚠️</a></td>
     <td align="center"><a href="https://github.com/johnjesse"><img src="https://avatars1.githubusercontent.com/u/6839660?v=4?s=100" width="100px;" alt=""/><br /><sub><b>johnjessewood</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/issues?q=author%3Ajohnjesse" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/dom-testing-library/commits?author=johnjesse" title="Code">💻</a></td>
-    <td align="center"><a href="https://codepen.io/ariperkkio/"><img src="https://avatars2.githubusercontent.com/u/14806298?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ari Perkkiö</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/issues?q=author%3AAriPerkkio" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/dom-testing-library/commits?author=AriPerkkio" title="Code">💻</a></td>
+    <td align="center"><a href="https://codepen.io/ariperkkio/"><img src="https://avatars2.githubusercontent.com/u/14806298?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ari Perkkiö</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/issues?q=author%3AAriPerkkio" title="Bug reports">🐛</a> <a href="https://github.com/testing-library/dom-testing-library/commits?author=AriPerkkio" title="Code">💻</a> <a href="https://github.com/testing-library/dom-testing-library/commits?author=AriPerkkio" title="Documentation">📖</a></td>
   </tr>
   <tr>
     <td align="center"><a href="https://github.com/nathanforce"><img src="https://avatars2.githubusercontent.com/u/6694194?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nathan Force</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/commits?author=nathanforce" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/ph-fritsche"><img src="https://avatars.githubusercontent.com/u/39068198?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Philipp Fritsche</b></sub></a><br /><a href="https://github.com/testing-library/dom-testing-library/commits?author=ph-fritsche" title="Code">💻</a></td>
   </tr>
 </table>
 

src/__tests__/helpers.js

@@ -5,10 +5,6 @@ import {
   runWithRealTimers,
 } from '../helpers'
 
-const globalObj = typeof window === 'undefined' ? global : window
-
-afterEach(() => jest.useRealTimers())
-
 test('returns global document if exists', () => {
   expect(getDocument()).toBe(document)
 })
@@ -21,6 +17,11 @@ describe('window retrieval throws when given something other than a node', () =>
       `"It looks like you passed a Promise object instead of a DOM node. Did you do something like \`fireEvent.click(screen.findBy...\` when you meant to use a \`getBy\` query \`fireEvent.click(screen.getBy...\`, or await the findBy query \`fireEvent.click(await screen.findBy...\`?"`,
     )
   })
+  test('Array as node', () => {
+    expect(() => getWindowFromNode([])).toThrowErrorMatchingInlineSnapshot(
+      `"It looks like you passed an Array instead of a DOM node. Did you do something like \`fireEvent.click(screen.getAllBy...\` when you meant to use a \`getBy\` query \`fireEvent.click(screen.getBy...\`?"`,
+    )
+  })
   test('unknown as node', () => {
     expect(() => getWindowFromNode({})).toThrowErrorMatchingInlineSnapshot(
       `"Unable to find the \\"window\\" object for the given node. Please file an issue with the code that's causing you to see this error: https://github.com/testing-library/dom-testing-library/issues/new"`,
@@ -53,42 +54,47 @@ describe('query container validation throws when validation fails', () => {
   })
 })
 
-test('should always use realTimers before using callback when timers are faked with useFakeTimers', () => {
-  const originalSetTimeout = globalObj.setTimeout
+describe('run with real timers', () => {
+  const realSetTimeout = global.setTimeout
 
-  // legacy timers use mocks and do not rely on a clock instance
-  jest.useFakeTimers('legacy')
-  runWithRealTimers(() => {
-    expect(originalSetTimeout).toEqual(globalObj.setTimeout)
+  afterEach(() => {
+    // restore timers replaced by jest.useFakeTimers()
+    jest.useRealTimers()
+    // restore setTimeout replaced by assignment
+    global.setTimeout = realSetTimeout
   })
-  expect(globalObj.setTimeout._isMockFunction).toBe(true)
-  expect(globalObj.setTimeout.clock).toBeUndefined()
-
-  jest.useRealTimers()
 
-  // modern timers use a clock instance instead of a mock
-  jest.useFakeTimers('modern')
-  runWithRealTimers(() => {
-    expect(originalSetTimeout).toEqual(globalObj.setTimeout)
+  test('use real timers when timers are faked with jest.useFakeTimers(legacy)', () => {
+    // legacy timers use mocks and do not rely on a clock instance
+    jest.useFakeTimers('legacy')
+    runWithRealTimers(() => {
+      expect(global.setTimeout).toBe(realSetTimeout)
+    })
+    expect(global.setTimeout._isMockFunction).toBe(true)
+    expect(global.setTimeout.clock).toBeUndefined()
   })
-  expect(globalObj.setTimeout._isMockFunction).toBeUndefined()
-  expect(globalObj.setTimeout.clock).toBeDefined()
-})
-
-test('should not use realTimers when timers are not faked with useFakeTimers', () => {
-  const originalSetTimeout = globalObj.setTimeout
 
-  // useFakeTimers is not used, timers are faked in some other way
-  const fakedSetTimeout = callback => {
-    callback()
-  }
-  fakedSetTimeout.clock = jest.fn()
+  test('use real timers when timers are faked with jest.useFakeTimers(modern)', () => {
+    // modern timers use a clock instance instead of a mock
+    jest.useFakeTimers('modern')
+    runWithRealTimers(() => {
+      expect(global.setTimeout).toBe(realSetTimeout)
+    })
+    expect(global.setTimeout._isMockFunction).toBeUndefined()
+    expect(global.setTimeout.clock).toBeDefined()
+  })
 
-  globalObj.setTimeout = fakedSetTimeout
+  test('do not use real timers when timers are not faked with jest.useFakeTimers', () => {
+    // useFakeTimers is not used, timers are faked in some other way
+    const fakedSetTimeout = callback => {
+      callback()
+    }
+    fakedSetTimeout.clock = jest.fn()
+    global.setTimeout = fakedSetTimeout
 
-  runWithRealTimers(() => {
-    expect(fakedSetTimeout).toEqual(globalObj.setTimeout)
+    runWithRealTimers(() => {
+      expect(global.setTimeout).toBe(fakedSetTimeout)
+    })
+    expect(global.setTimeout).toBe(fakedSetTimeout)
   })
-
-  globalObj.setTimeout = originalSetTimeout
 })

src/helpers.js

@@ -5,52 +5,52 @@ const TEXT_NODE = 3
 
 // Currently this fn only supports jest timers, but it could support other test runners in the future.
 function runWithRealTimers(callback) {
-  const fakeTimersType = getJestFakeTimersType()
-  if (fakeTimersType) {
-    jest.useRealTimers()
+  // istanbul ignore else
+  if (typeof jest !== 'undefined') {
+    return runWithJestRealTimers(callback).callbackReturnValue
   }
 
-  const callbackReturnValue = callback()
+  // istanbul ignore next
+  return callback()
+}
 
-  if (fakeTimersType) {
-    jest.useFakeTimers(fakeTimersType)
+function runWithJestRealTimers(callback) {
+  const timerAPI = {
+    clearImmediate,
+    clearInterval,
+    clearTimeout,
+    setImmediate,
+    setInterval,
+    setTimeout,
   }
 
-  return callbackReturnValue
-}
+  jest.useRealTimers()
 
-function getJestFakeTimersType() {
-  // istanbul ignore if
-  if (
-    typeof jest === 'undefined' ||
-    typeof globalObj.setTimeout === 'undefined'
-  ) {
-    return null
-  }
+  const callbackReturnValue = callback()
 
-  if (
-    typeof globalObj.setTimeout._isMockFunction !== 'undefined' &&
-    globalObj.setTimeout._isMockFunction
-  ) {
-    return 'legacy'
+  const usedFakeTimers = Object.entries(timerAPI).some(
+    ([name, func]) => func !== globalObj[name],
+  )
+
+  if (usedFakeTimers) {
+    jest.useFakeTimers(timerAPI.setTimeout?.clock ? 'modern' : 'legacy')
   }
 
-  if (
-    typeof globalObj.setTimeout.clock !== 'undefined' &&
-    typeof jest.getRealSystemTime !== 'undefined'
-  ) {
-    try {
-      // jest.getRealSystemTime is only supported for Jest's `modern` fake timers and otherwise throws
-      jest.getRealSystemTime()
-      return 'modern'
-    } catch {
-      // not using Jest's modern fake timers
-    }
+  return {
+    callbackReturnValue,
+    usedFakeTimers,
   }
-  return null
 }
 
-const jestFakeTimersAreEnabled = () => Boolean(getJestFakeTimersType())
+function jestFakeTimersAreEnabled() {
+  // istanbul ignore else
+  if (typeof jest !== 'undefined') {
+    return runWithJestRealTimers(() => {}).usedFakeTimers
+  }
+
+  // istanbul ignore next
+  return false
+}
 
 // we only run our tests in node, and setImmediate is supported in node.
 // istanbul ignore next
@@ -92,6 +92,10 @@ function getWindowFromNode(node) {
     throw new Error(
       `It looks like you passed a Promise object instead of a DOM node. Did you do something like \`fireEvent.click(screen.findBy...\` when you meant to use a \`getBy\` query \`fireEvent.click(screen.getBy...\`, or await the findBy query \`fireEvent.click(await screen.findBy...\`?`,
     )
+  } else if (Array.isArray(node)) {
+    throw new Error(
+      `It looks like you passed an Array instead of a DOM node. Did you do something like \`fireEvent.click(screen.getAllBy...\` when you meant to use a \`getBy\` query \`fireEvent.click(screen.getBy...\`?`,
+    )
   } else {
     // The user passed something unusual to a calling function
     throw new Error(

src/wait-for.js

@@ -52,8 +52,8 @@ function waitFor(
 
     const overallTimeoutTimer = setTimeout(handleTimeout, timeout)
 
-    const usingFakeTimers = jestFakeTimersAreEnabled()
-    if (usingFakeTimers) {
+    const usingJestFakeTimers = jestFakeTimersAreEnabled()
+    if (usingJestFakeTimers) {
       checkCallback()
       // this is a dangerous rule to disable because it could lead to an
       // infinite loop. However, eslint isn't smart enough to know that we're
@@ -107,7 +107,7 @@ function waitFor(
       finished = true
       clearTimeout(overallTimeoutTimer)
 
-      if (!usingFakeTimers) {
+      if (!usingJestFakeTimers) {
         clearInterval(intervalId)
         observer.disconnect()
       }