Manage React Hook Tests Skill

This skill helps you create or update test files for React hooks. Tests follow a specific pattern with vitest,

renderHook

from React Testing Library, and Fake context providers for controlled testing.

When to Use This Skill

Use this skill when you need to:

• Create a new test file for a React hook
• Update an existing test file when the hook changes
• Generate test coverage for hook logic and return values

The skill will generate/update:

• A test file with vitest and React Testing Library imports
• A

  renderMyHook

  helper function using

  renderHook

• Individual test cases for different hook behaviors and branches
• Proper setup with Fake context providers when needed

Usage

Invoke this skill when the user asks to:

• "Create tests for [useMyHook]"
• "Generate a test file for [useMyHook]"
• "I need tests for [useMyHook]"
• "Update tests for [useMyHook]"
• "The [useMyHook] changed, update its tests"
• "Test [useMyHook]"

Core Principles

Testing Philosophy

1. Hook-Driven: Test the hook's behavior, return values, and side effects
2. Context Isolation: Use Fake context providers to isolate the hook from external dependencies
3. Controlled Testing: Use Fake builders to control all dependencies and return values
4. Single Responsibility: Each

   it

   block should test one specific scenario
5. Avoid vi.mock for Internal: Use Fakes for internal dependencies; only use

   vi.mock

   for external libraries

Prerequisites

Before creating/updating hook tests:

1. Verify the hook exists - The hook you're testing must already be defined
2. Check for existing test file - Use Glob to search for existing

   .spec.tsx

   file
3. Identify hook dependencies - Determine what contexts or other hooks it uses
4. Locate Fake providers - Find available Fake context providers (usually in the same package under

   /fakes

   )
5. Check for @testing-library/react - Verify that

   @testing-library/react

   is installed (for

   renderHook

   )

Create vs Update Decision

If test file exists: Update mode

• Read the existing test file
• Read the hook definition
• Compare and identify what's missing or outdated
• Update the test to match current implementation

If test file does NOT exist: Create mode

• Read the hook definition
• Identify all dependencies and context requirements
• Generate complete test file from scratch

Test File Location

CRITICAL: Test files MUST be in the

__tests__

folder, which is a SIBLING of the

/src

folder, NOT inside it.

Directory Structure

packages/
  my-package/
    src/
      hooks/
        useMyHook.ts
    __tests__/              # Sibling to src/, NOT inside src/
      useMyHook.spec.tsx    # .tsx extension for React components

Naming Convention

For a hook named

useMyHook

:

• Test file:

  useMyHook.spec.tsx

  (matches hook name exactly, with

  .tsx

  extension)
• Located in:

  packages/my-package/__tests__/useMyHook.spec.tsx

Test File Structure

1. Imports

Import Rules:

• Import React (required for this project's JSX transform)
• Import vitest utilities from

  'vitest'

• Import

  renderHook

  (and

  act

  if needed) from

  '@testing-library/react'

• Import the hook being tested
• Import Fake context providers from

  /fakes

  subpath
• Import Fake builders for services/dependencies when needed

Example:

import React from 'react';
import { describe, it, expect, vi } from 'vitest';
import { renderHook, act } from '@testing-library/react';
import { useMyHook } from '../src/hooks/useMyHook';
import { FakeMyContextProvider } from '../fakes';
import { FakeServiceBuilder } from '@someScope/some-library/fakes';
import type { IService } from '@someScope/some-library';

2. Main Describe Block

describe('useMyHook', () => {
  // Helper function
  function renderMyHook(/* overrides */): { /* return type */ } {
    // ...
  }

  // Test cases
  it('should return initial state', () => {
    // Test...
  });
});

Structure Rules:

• Main describe uses the hook name (e.g.,

  'useMyHook'

  )
• Contains one

  renderMyHook

  helper function at the top
• All test cases use the

  renderMyHook

  helper
• Tests cover all branches and return values

3. renderMyHook Helper Function

Purpose: Factory function that renders the hook with all necessary context providers and dependencies, allowing for easy overrides in tests.

Pattern with Context:

function renderMyHook(overrides?: {
  service?: IService;
}) {
  const service = overrides?.service ?? new FakeServiceBuilder().build();

  const hookRenderResult = renderHook(() => useMyHook(), {
    wrapper: ({ children }) => (
      <FakeMyContextProvider service={service}>
        {children}
      </FakeMyContextProvider>
    ),
  });

  return {
    hookRenderResult,
    service,
  };
}

Pattern without Context:

function renderMyHook(params?: {
  initialValue?: string;
}) {
  const hookRenderResult = renderHook(() => useMyHook(params?.initialValue ?? 'default'));

  return {
    hookRenderResult,
  };
}

Rules:

• Accept

  overrides

  parameter for context dependencies
• Accept

  params

  parameter for hook arguments
• Use nullish coalescing (

  ??

  ) for default Fake instances
• Use

  renderHook

  with

  wrapper

  option for context providers
• Return object with

  hookRenderResult

  and all dependencies

4. Finding Context Dependencies

How to Identify:

1. Read the hook file and look for

   useContext

   calls or other context hooks
2. Search for the context provider in the codebase
3. Check if a Fake version exists in

   /fakes

   folder
4. If no Fake exists, create one or use

   vi.mock

   for external dependencies

Multiple Contexts: Nest providers in the wrapper:

wrapper: ({ children }) => (
  <FakeContextA>
    <FakeContextB>
      {children}
    </FakeContextB>
  </FakeContextA>
)

5. Writing Test Cases

Structure:

• Use descriptive test names explaining the expected behavior
• Follow Arrange-Act-Assert pattern
• Access hook result via

  hookRenderResult.result.current

• Use

  act()

  for state updates
• Use

  await act(async () => ...)

  for async operations

Example:

it('should return expected value', () => {
  const { hookRenderResult } = renderMyHook({
    service: new FakeServiceBuilder()
      .withGetDataReturnValue({ id: '123' })
      .build()
  });

  expect(hookRenderResult.result.current.data).toEqual({ id: '123' });
});

6. Testing State Updates

Always wrap state changes in

act()

:

it('should update state when action is called', () => {
  const { hookRenderResult } = renderMyHook();

  act(() => {
    hookRenderResult.result.current.updateValue('new value');
  });

  expect(hookRenderResult.result.current.value).toBe('new value');
});

7. Testing Async Operations

Use

await act(async () => ...)

:

it('should save successfully', async () => {
  const { hookRenderResult } = renderMyHook();

  await act(async () => {
    await hookRenderResult.result.current.save();
  });

  expect(hookRenderResult.result.current.isSaving).toBe(false);
});

8. Mocking Dependencies

Preferred (Fake Providers):

const { hookRenderResult } = renderMyHook({
  service: new FakeServiceBuilder()
    .withFetchDataReturnValue(Promise.resolve({ success: true }))
    .build()
});

When to use vi.mock:

• External React hooks from 3rd party libraries
• Browser APIs
• Modules without Fake implementations

Workflow

Create Workflow

1. Identify the hook - Determine which hook to test
2. Locate the hook file - Use Glob to find the hook definition
3. Read the hook - Understand behavior, return values, context usage
4. Identify dependencies - Look for context hooks and other dependencies
5. Locate Fakes - Find Fake providers and builders
6. Ensure

   __tests__

   exists - Create folder if needed (sibling to

   /src

   )
7. Verify @testing-library/react - Check package.json
8. Create test file in

   __tests__/useMyHook.spec.tsx

   with:
   • All required imports (including React)
   • Main describe block

   • renderMyHook

     helper function
   • Test cases covering all scenarios

Update Workflow

1. Read existing test and hook - Compare current state
2. Identify changes:
   • New return values → Add test cases
   • Changed logic → Update test cases
   • New dependencies → Update

     renderMyHook

     and imports
   • Removed functionality → Remove tests
3. Apply updates using Edit tool - Targeted changes only
4. Verify coverage - Ensure all logic branches tested

Update Guidelines

• Preserve structure - Use Edit tool, not Write
• Maintain consistency - Follow existing patterns
• Keep descriptive names - Clear, behavior-focused
• Don't delete passing tests - Only update broken/obsolete tests
• Add missing coverage - Test new logic

Best Practices

1. Test Behavior, Not Implementation - Focus on return values and side effects
2. Descriptive Test Names - Explain expected behavior clearly
3. Arrange-Act-Assert - Structure tests consistently
4. Use act() for Updates - Always wrap state changes
5. Test Edge Cases - Null, undefined, empty values, errors
6. Appropriate Matchers - Use correct expect matchers for the assertion

Common Pitfalls to Avoid

1. ❌ Don't Render Hook Directly - Always use

   renderHook()

2. ❌ Don't Forget React Import - Required for JSX in this project
3. ❌ Don't Forget act() - State updates need to be wrapped
4. ❌ Don't Use vi.mock for Internal - Use Fake providers instead
5. ❌ Don't Forget async/await - Async operations need proper handling

Example Reference

See

examples.md

in the same directory for complete working examples of:

• Simple hooks returning context values
• Hooks with complex logic and multiple return values
• Hooks with parameters
• Hooks with state management
• Standalone hooks without context
• Hooks using multiple contexts

Important Notes

File Organization

• Tests in

  __tests__/

  at package root (sibling to

  /src

  )
• Use

  .tsx

  extension
• Match hook name exactly

Dependencies

• Ensure

  @testing-library/react

  is installed
• Use Fake providers from

  /fakes

  subpath
• Create Fakes if they don't exist

Test Quality

• Many small tests > few large tests
• Test happy path and error cases
• Test edge cases and boundaries
• Descriptive test names
• Simple, focused tests

Running Tests

After creating/updating:

1. Run

   pnpm test

   to verify tests pass
2. Run

   pnpm lint

   to check linting
3. Run

   pnpm build

   to verify TypeScript compiles