feat: add mountHook function for testing React hooks (#335)

Author: bahmutov

README.md

@@ -92,6 +92,12 @@ See [Recipes](./docs/recipes.md) for more examples.
 }
 ```
 
+## API
+
+- `mount` is the most important function, allows to mount a given React component as a mini web application and interact with it using Cypress commands
+- `unmount` removes previously mounted component, mostly useful to test how the component cleans up after itself
+- `mountHook` mounts a given React Hook in a test component for full testing, see `hooks` example
+
 ## Examples
 
 ```js
@@ -107,7 +113,7 @@ describe('HelloWorld component', () => {
 })
 ```
 
-Look at the examples in [cypress/component](cypress/component) folder. Here is the list in progress
+Look at the examples in [cypress/component](cypress/component) folder. Here is the list of examples showing various testing scenarios.
 
 ### Basic examples
 

cypress/component/advanced/hooks/README.md

@@ -0,0 +1,8 @@
+# testing React hooks
+
+- [counter-with-hooks.spec.js](counter-with-hooks.spec.js) and [counter2-with-hooks.spec.js](counter2-with-hooks.spec.js) test React components that uses hooks
+- [use-counter.spec.js](use-counter.spec.js) shows how to test a React hook using `mountHook` function
+
+![Hook test](images/hook.png)
+
+Note: hooks are mounted inside a test component following the approach shown in [react-hooks-testing-library](https://github.com/testing-library/react-hooks-testing-library/blob/master/src/pure.js)

cypress/component/advanced/hooks/images/hook.png

@@ -0,0 +1,25 @@
+// @ts-check
+/// <reference types="cypress" />
+import React, { useState, useCallback } from 'react'
+// @ts-ignore
+import { mountHook } from 'cypress-react-unit-test'
+
+// testing example hook function from
+// https://dev.to/jooforja/12-recipes-for-testing-react-applications-using-testing-library-1bh2#hooks
+function useCounter() {
+  const [count, setCount] = useState(0)
+  const increment = useCallback(() => setCount(x => x + 1), [])
+  return { count, increment }
+}
+
+describe('useCounter hook', function() {
+  it('increments the count', function() {
+    mountHook(() => useCounter()).then(result => {
+      expect(result.current.count).to.equal(0)
+      result.current.increment()
+      expect(result.current.count).to.equal(1)
+      result.current.increment()
+      expect(result.current.count).to.equal(2)
+    })
+  })
+})

cypress/component/advanced/hooks/use-counter.spec.js

@@ -166,4 +166,77 @@ export const unmount = () => {
   })
 }
 
+// mounting hooks inside a test component mostly copied from
+// https://github.com/testing-library/react-hooks-testing-library/blob/master/src/pure.js
+function resultContainer() {
+  let value: any = null
+  let error: Error | null = null
+  const resolvers: any[] = []
+
+  const result = {
+    get current() {
+      if (error) {
+        throw error
+      }
+      return value
+    },
+    get error() {
+      return error
+    },
+  }
+
+  const updateResult = (val: any, err: Error | null = null) => {
+    value = val
+    error = err
+    resolvers.splice(0, resolvers.length).forEach(resolve => resolve())
+  }
+
+  return {
+    result,
+    addResolver: (resolver: any) => {
+      resolvers.push(resolver)
+    },
+    setValue: (val: any) => updateResult(val),
+    setError: (err: Error) => updateResult(undefined, err),
+  }
+}
+
+// @ts-ignore
+function TestHook({ callback, onError, children }) {
+  try {
+    children(callback())
+  } catch (err) {
+    if (err.then) {
+      throw err
+    } else {
+      onError(err)
+    }
+  }
+
+  // TODO decide what the test hook component should show
+  // maybe nothing, or maybe useful information about the hook?
+  // maybe its current properties?
+  // return <div>TestHook</div>
+  return null
+}
+
+/**
+ * Mounts a React hook function in a test component for testing.
+ *
+ * @see https://github.com/bahmutov/cypress-react-unit-test#advanced-examples
+ */
+export const mountHook = (hookFn: Function) => {
+  const { result, setValue, setError } = resultContainer()
+
+  return mount(
+    React.createElement(TestHook, {
+      callback: hookFn,
+      onError: setError,
+      children: setValue,
+    }),
+  ).then(() => {
+    cy.wrap(result)
+  })
+}
+
 export default mount