Hooks

docs/example-react-hooks.md

@@ -0,0 +1,202 @@
+---
+id: example-react-hooks
+title: React Hooks
+---
+
+`react-testing-library` provides the
+[`testHook`](/docs/react-testing-library/api#testhook) utility to test custom
+hooks.
+
+> **Note**
+>
+> This is the recommended way to test reusable custom react hooks. It is not
+> however recommended to use the testHook utility to test single-use custom
+> hooks. Typically those are better tested by testing the component that is
+> using it.
+
+## Using `result`
+
+Testing the last returned value of a hook using the `result` ref
+
+```jsx
+function useCounter({ initialCount = 0, step = 1 } = {}) {
+ const [count, setCount] = React.useState(initialCount)
+ const increment = () => setCount(c => c + step)
+ const decrement = () => setCount(c => c - step)
+ return { count, increment, decrement }
+}
+```
+
+```jsx
+test('returns result ref with latest result from hook execution', () => {
+ const { result } = testHook(useCounter)
+ expect(result.current.count).toBe(0)
+ act(() => {
+ result.current.increment()
+ })
+ expect(result.current.count).toBe(1)
+})
+```
+
+## State
+
+Testing a hook that provides state
+
+```jsx
+import { useState } from 'react'
+
+export function useCounter({ initialCount = 0, step = 1 } = {}) {
+ const [count, setCount] = useState(initialCount)
+ const increment = () => setCount(c => c + step)
+ const decrement = () => setCount(c => c - step)
+ return { count, increment, decrement }
+}
+```
+
+```jsx
+import { testHook, act, cleanup } from 'react-testing-library'
+afterEach(cleanup)
+
+describe('useCounter', () => {
+ test('accepts default initial values', () => {
+ let count
+ testHook(() => ({ count } = useCounter()))
+
+ expect(count).toBe(0)
+ })
+
+ test('accepts a default initial value for `count`', () => {
+ let count
+ testHook(() => ({ count } = useCounter({})))
+
+ expect(count).toBe(0)
+ })
+
+ test('provides an `increment` function', () => {
+ let count, increment
+ testHook(() => ({ count, increment } = useCounter({ step: 2 })))
+
+ expect(count).toBe(0)
+ act(() => {
+ increment()
+ })
+ expect(count).toBe(2)
+ })
+
+ test('provides an `decrement` function', () => {
+ let count, decrement
+ testHook(() => ({ count, decrement } = useCounter({ step: 2 })))
+
+ expect(count).toBe(0)
+ act(() => {
+ decrement()
+ })
+ expect(count).toBe(-2)
+ })
+
+ test('accepts a default initial value for `step`', () => {
+ let count, increment
+ testHook(() => ({ count, increment } = useCounter({})))
+
+ expect(count).toBe(0)
+ act(() => {
+ increment()
+ })
+ expect(count).toBe(1)
+ })
+})
+```
+
+## Unmount Side-Effects
+
+Using the `unmount` function to check useEffect behavior when unmounting
+
+```jsx
+import { useState, useEffect } from 'react'
+
+export function useDocumentTitle(title) {
+ const [originalTitle, setOriginalTitle] = useState(document.title)
+ useEffect(() => {
+ setOriginalTitle(document.title)
+ document.title = title
+ return () => {
+ document.title = originalTitle
+ }
+ }, [title])
+}
+```
+
+```jsx
+describe('useDocumentTitle', () => {
+ test('sets a title', () => {
+ document.title = 'original title'
+ testHook(() => {
+ useDocumentTitle('modified title')
+ })
+
+ expect(document.title).toBe('modified title')
+ })
+
+ test('returns to original title when component is unmounted', () => {
+ document.title = 'original title'
+ const { unmount } = testHook(() => {
+ useDocumentTitle('modified title')
+ })
+
+ unmount()
+ expect(document.title).toBe('original title')
+ })
+})
+```
+
+## Rerender Side-Effects
+
+Using the `rerender` function to test calling useEffect multiple times
+
+```jsx
+import { useEffect } from 'react'
+
+export function useCall(callback, deps) {
+ useEffect(() => {
+ callback()
+ }, deps)
+}
+```
+
+```jsx
+describe('useCall', () => {
+ test('calls once on render', () => {
+ const spy = jest.fn()
+ testHook(() => {
+ useCall(spy, [])
+ })
+ expect(spy).toHaveBeenCalledTimes(1)
+ })
+
+ test('calls again if deps change', () => {
+ let deps = [false]
+ const spy = jest.fn()
+ const { rerender } = testHook(() => {
+ useCall(spy, deps)
+ })
+ expect(spy).toHaveBeenCalledTimes(1)
+
+ deps = [true]
+ rerender()
+ expect(spy).toHaveBeenCalledTimes(2)
+ })
+
+ test('does not call again if deps are the same', () => {
+ let deps = [false]
+ const spy = jest.fn()
+ const { rerender } = testHook(() => {
+ useCall(spy, deps)
+ })
+ expect(spy).toHaveBeenCalledTimes(1)
+
+ deps = [false]
+ rerender()
+ expect(spy).toHaveBeenCalledTimes(1)
+ })
+})
+```

docs/react-testing-library/api.md

@@ -254,3 +254,69 @@ This is a light wrapper around the
 [`react-dom/test-utils` `act` function](https://reactjs.org/docs/test-utils.html#act).
 All it does is forward all arguments to the act function if your version of
 react supports `act`.
+
+## `testHook`
+
+`testHook` is a utility to test custom hooks. It is designed to help test
+reusable hooks in isolation.
+
+You should also write integration tests for components using custom hooks, and
+one-off hooks should be tested as part of the component instead.
+
+**Usage**
+
+```jsx
+import { testHook } from 'react-testing-libary'
+
+testHook(hook[, renderOptions])
+```
+
+**Arguments**
+
+- `hook` customHook to test
+- `renderOptions` options object to pass to the underlying `render`. See
+ [render options](#render-options). This is mostly useful for wrapping the hook
+ with a context provider.
+
+**Returns**
+
+```jsx
+const { rerender, unmount, result } = testHook(hook)
+```
+
+- `rerender` Call this function to render the wrapper again, i.e., to test that
+ the hook handles props changes
+- `unmount` Call this to unmount the component, i.e., to test side-effects and
+ cleanup behavior
+- `result` An object that acts like a React ref with a `current` property
+ pointing to the last value the hook returned. For example:
+ `expect(result.current.count).toBe(0)`
+
+**Example**
+
+```jsx
+// Example custom hook
+function useCounter({ initialCount = 0, step = 1 } = {}) {
+ const [count, setCount] = React.useState(initialCount)
+ const increment = () => setCount(c => c + step)
+ const decrement = () => setCount(c => c - step)
+ return { count, increment, decrement }
+}
+```
+
+```jsx
+// Test using the `result` ref
+test('returns result ref with latest result from hook execution', () => {
+ const { result } = testHook(useCounter)
+
+ expect(result.current.count).toBe(0)
+ act(() => result.current.increment())
+ expect(result.current.count).toBe(1)
+})
+```
+
+**More**
+
+- [More Examples](/docs/example-react-hooks)
+- [Tests](https://github.com/kentcdodds/react-testing-library/blob/master/src/__tests__/test-hook.js)
+- [Types](https://github.com/kentcdodds/react-testing-library/blob/master/typings/index.d.ts)

website/blog/2019-02-06-react-hooks.md

@@ -0,0 +1,16 @@
+---
+title: React Hooks Are Supported
+author: Alex Krolick
+authorURL: http://github.com/alexkrolick
+---
+
+[Hooks have been released in React 16.8](https://reactjs.org/blog/2019/02/06/react-v16.8.0.html#testing-hooks)
+and they are supported out of the box by `react-testing-library`!
+
+Because `react-testing-library` only uses the external interface of your React
+components, hooks work right away! If you rewrite a class component with hooks
+your tests should still pass.
+
+For unit testing custom hooks, we've also added a `testHook` utility. Check out
+the [docs for `testHook`](/docs/react-testing-library/api#testhook). Thanks to
+[@donavon](https://github.com/donavon) for the PR.

website/sidebars.json

@@ -12,6 +12,7 @@
  "example-input-event",
  "example-update-props",
  "example-react-context",
+ "example-react-hooks",
  "example-react-redux",
  "example-react-router",
  "example-reach-router",

website/siteConfig.js

@@ -95,7 +95,7 @@ const siteConfig = {
  /* Colors for website */
  colors: {
  primaryColor: '#292422',
- secondaryColor: '#3344bb',
+ secondaryColor: '#2468e5',
  },
 
  // Add custom scripts here that would be placed in <script> tags.