feat: add renderHook (#11)

* feat: add renderHook

* docs: update readme to add renderHook example

* Update README.md

* docs: lint README.md

---------

Co-authored-by: Vladimir <[email protected]>

Author: huijiewei

README.md

@@ -22,6 +22,24 @@ test('counter button increments the count', async () => {
 > 💡 This library doesn't expose React's `act` and uses it only to flush operations happening as part of `useEffect` during initial rendering and unmouting.
 Other use cases are handled by CDP and `expect.element` which both have built-in [retry-ability mechanism](https://vitest.dev/guide/browser/assertion-api).
 
+`vitest-browser-react` also exposes `renderHook` helper to test React hooks.
+
+```tsx
+import { renderHook } from 'vitest-browser-react'
+import { expect, test } from 'vitest'
+import { act } from 'react'
+
+test('should increment counter', async () => {
+  const { result } = renderHook(() => useCounter())
+
+  act(() => {
+    result.current.increment()
+  })
+
+  expect(result.current.count).toBe(1)
+})
+```
+
 `vitest-browser-react` also automatically injects `render` method on the `page`. Example:
 
 ```ts

src/index.ts

@@ -2,7 +2,7 @@ import { page } from '@vitest/browser/context'
 import { beforeEach } from 'vitest'
 import { cleanup, render } from './pure'
 
-export { render, cleanup } from './pure'
+export { render, renderHook, cleanup } from './pure'
 export type { ComponentRenderOptions, RenderResult } from './pure'
 
 page.extend({

src/pure.ts src/pure.tsx

@@ -112,6 +112,65 @@ export function render(
   }
 }
 
+export interface RenderHookOptions<Props> extends ComponentRenderOptions {
+  /**
+   * The argument passed to the renderHook callback. Can be useful if you plan
+   * to use the rerender utility to change the values passed to your hook.
+   */
+  initialProps?: Props | undefined
+}
+
+export interface RenderHookResult<Result, Props> {
+  /**
+   * Triggers a re-render. The props will be passed to your renderHook callback.
+   */
+  rerender: (props?: Props) => void
+  /**
+   * This is a stable reference to the latest value returned by your renderHook
+   * callback
+   */
+  result: {
+    /**
+     * The value returned by your renderHook callback
+     */
+    current: Result
+  }
+  /**
+   * Unmounts the test component. This is useful for when you need to test
+   * any cleanup your useEffects have.
+   */
+  unmount: () => void
+}
+
+export function renderHook<Props, Result>(renderCallback: (initialProps?: Props) => Result, options: RenderHookOptions<Props> = {}): RenderHookResult<Result, Props> {
+  const { initialProps, ...renderOptions } = options
+
+  const result = React.createRef<Result>() as unknown as { current: Result }
+
+  function TestComponent({ renderCallbackProps }: { renderCallbackProps?: Props }) {
+    const pendingResult = renderCallback(renderCallbackProps)
+
+    React.useEffect(() => {
+      result.current = pendingResult
+    })
+
+    return null
+  }
+
+  const { rerender: baseRerender, unmount } = render(
+    <TestComponent renderCallbackProps={initialProps} />,
+    renderOptions,
+  )
+
+  function rerender(rerenderCallbackProps?: Props) {
+    return baseRerender(
+      <TestComponent renderCallbackProps={rerenderCallbackProps} />,
+    )
+  }
+
+  return { result, rerender, unmount }
+}
+
 export function cleanup(): void {
   mountedRootEntries.forEach(({ root, container }) => {
     act(() => {
@@ -157,7 +216,9 @@ function strictModeIfNeeded(innerElement: React.ReactNode) {
     : innerElement
 }
 
-function wrapUiIfNeeded(innerElement: React.ReactNode, wrapperComponent?: React.JSXElementConstructor<{ children: React.ReactNode }>) {
+function wrapUiIfNeeded(innerElement: React.ReactNode, wrapperComponent?: React.JSXElementConstructor<{
+  children: React.ReactNode
+}>) {
   return wrapperComponent
     ? React.createElement(wrapperComponent, null, innerElement)
     : innerElement

test/fixtures/useCounter.ts

@@ -0,0 +1,12 @@
+import { useCallback, useState } from 'react'
+
+export function useCounter(): {
+  count: number
+  increment: () => void
+} {
+  const [count, setCount] = useState(0)
+
+  const increment = useCallback(() => setCount(x => x + 1), [])
+
+  return { count, increment }
+}

test/render-hook.test.tsx

@@ -0,0 +1,60 @@
+import { expect, test } from 'vitest'
+import type { PropsWithChildren } from 'react'
+import React, { act } from 'react'
+import { renderHook } from '../src/index'
+import { useCounter } from './fixtures/useCounter'
+
+test('should increment counter', () => {
+  const { result } = renderHook(() => useCounter())
+
+  act(() => {
+    result.current.increment()
+  })
+
+  expect(result.current.count).toBe(1)
+})
+
+test('allows rerendering', () => {
+  const { result, rerender } = renderHook(
+    (initialProps) => {
+      const [left, setLeft] = React.useState('left')
+      const [right, setRight] = React.useState('right')
+
+      switch (initialProps?.branch) {
+        case 'left':
+          return [left, setLeft]
+        case 'right':
+          return [right, setRight]
+
+        default:
+          throw new Error(
+            'No Props passed. This is a bug in the implementation',
+          )
+      }
+    },
+    { initialProps: { branch: 'left' } },
+  )
+
+  expect(result.current).toEqual(['left', expect.any(Function)])
+
+  rerender({ branch: 'right' })
+
+  expect(result.current).toEqual(['right', expect.any(Function)])
+})
+
+test('allows wrapper components', async () => {
+  const Context = React.createContext('default')
+  function Wrapper({ children }: PropsWithChildren) {
+    return <Context.Provider value="provided">{children}</Context.Provider>
+  }
+  const { result } = renderHook(
+    () => {
+      return React.useContext(Context)
+    },
+    {
+      wrapper: Wrapper,
+    },
+  )
+
+  expect(result.current).toEqual('provided')
+})