react-bugfix

React Bug Diagnosis Protocol

Quality Gate Thresholds (ENFORCED)

Gate	Threshold	Status
TypeScript	0 type errors	REQUIRED
Tests	100% pass (0 failures)	REQUIRED
Coverage	≥ 80% line coverage	REQUIRED
ESLint	0 errors (warnings OK)	REQUIRED
Build	must pass	REQUIRED

⛔ BLOCKING: Bug fix is NOT complete until ALL gates pass.

Step 0: Verify Coverage Configuration ⚠️ PREREQUISITE

Before fixing ANY bug, verify Vitest coverage is configured:

grep -l "thresholds" vitest.config.ts

If NOT configured, update vitest.config.ts first (see react-testing skill for full configuration):

// vitest.config.ts - coverage section
coverage: {
  provider: 'v8',
  reporter: ['text', 'text-summary', 'html', 'lcov'],
  thresholds: {
    lines: 80,
    branches: 70,
    functions: 80,
    statements: 80,
  },
}

The Reproduce-First Workflow

┌─────────────────────────────────────────────────────────────┐
│  STEP 0: VERIFY COVERAGE CONFIGURATION                       │
│  - Check: grep "thresholds" vitest.config.ts                 │
│  - If missing → Configure coverage thresholds FIRST          │
│  - ⛔ Do NOT proceed without coverage configuration          │
│                                                              │
│  STEP 1: UNDERSTAND                                          │
│  - Read bug report / error description / Jira ticket        │
│  - Identify: EXPECTED behavior vs ACTUAL behavior            │
│  - Note: browser, screen size, user actions, console errors  │
│                                                              │
│  STEP 2: REPRODUCE                                           │
│  - Write a test that exercises the exact bug scenario        │
│  - Run the test → it MUST FAIL                               │
│  - If it passes → you haven't reproduced the bug yet         │
│  - The failing test IS your proof the bug exists             │
│                                                              │
│  STEP 3: DIAGNOSE                                            │
│  - Identify component and state involved                     │
│  - Classify: RENDER / STATE / EVENT / ASYNC / TYPE issue    │
│  - Use React DevTools patterns                               │
│  - Form hypothesis → verify → don't guess                    │
│                                                              │
│  STEP 4: FIX                                                 │
│  - Fix the ROOT CAUSE (not the symptom)                      │
│  - Minimal change that addresses the actual problem          │
│                                                              │
│  STEP 5: VERIFY                                              │
│  - Run reproducing test → must now PASS                      │
│  - Run FULL test suite → zero regressions                    │
│  - All existing tests must still pass                        │
│                                                              │
│  STEP 6: COVERAGE VERIFICATION ⚠️ MANDATORY                  │
│  - Run: npm test -- --coverage --run                         │
│  - Check coverage ≥ 80%                                      │
│  - If < 80% → add more tests → repeat                        │
│  - ⛔ Do NOT mark complete if coverage < 80%                 │
└─────────────────────────────────────────────────────────────┘

Bug Classification

RENDER Issues

Symptoms:

• Component not showing
• Wrong content displayed
• Layout broken
• Styling incorrect

Diagnosis:

// Add debug output
console.log('Render data:', data);
console.log('Render condition:', shouldShow);

// Check in test
screen.debug(); // prints DOM

// Check if element exists
expect(screen.queryByText('Content')).not.toBeInTheDocument();

Common causes:

• Conditional rendering logic wrong
• Data not passed correctly
• CSS/Tailwind classes wrong
• Component not imported

STATE Issues

Symptoms:

• State not updating
• Stale data showing
• Race conditions
• State resets unexpectedly

Diagnosis:

// Add state logging
useEffect(() => {
  console.log('State changed:', state);
}, [state]);

// Check for stale closures
const handleClick = useCallback(() => {
  console.log('Current value:', value); // Is this stale?
}, [value]); // Missing dependency?

Common causes:

• Missing useCallback/useMemo dependencies
• Stale closure (using old value)
• State update batching issues
• Async state update after unmount

EVENT Issues

Symptoms:

• Click not working
• Form not submitting
• Event fires multiple times
• Wrong element receives event

Diagnosis:

// Log event firing
const handleClick = (e) => {
  console.log('Click event:', e.target);
  console.log('Current target:', e.currentTarget);
};

// Check event propagation
onClick={(e) => {
  e.stopPropagation();
  handleClick(e);
}}

Common causes:

• Event handler not bound
• Wrong event type
• Event bubbling/capturing
• Disabled or pointer-events: none
• Element covered by another element

ASYNC Issues

Symptoms:

• Loading state wrong
• Data not fetched
• Race condition
• Memory leak warning

Diagnosis:

// Log async flow
useEffect(() => {
  console.log('Effect starting fetch');
  let cancelled = false;

  async function fetchData() {
    console.log('Fetch started');
    const data = await api.get();
    console.log('Fetch completed, cancelled:', cancelled);
    if (!cancelled) {
      setData(data);
    }
  }

  fetchData();
  return () => {
    console.log('Cleanup running');
    cancelled = true;
  };
}, []);

Common causes:

• Missing cleanup in useEffect
• Race condition between requests
• State update after unmount
• Error not handled

TYPE Issues

Symptoms:

• TypeScript errors
• Runtime type errors
• Prop mismatch

Diagnosis:

// Check prop types at runtime
console.log('Props received:', typeof value, value);

// Add type guards
if (typeof value !== 'string') {
  console.error('Expected string, got:', typeof value);
}

Common causes:

• API response shape changed
• Optional property accessed without check
• Type assertion (as) hiding real issue

Common React Bug Patterns

Pattern 1: Stale Closure

// BUG: count is always 0 in the callback
function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const interval = setInterval(() => {
      console.log(count); // Always 0!
      setCount(count + 1); // Always sets to 1
    }, 1000);
    return () => clearInterval(interval);
  }, []); // Empty deps = stale closure
}

// FIX: Use functional update
useEffect(() => {
  const interval = setInterval(() => {
    setCount(c => c + 1); // Uses current value
  }, 1000);
  return () => clearInterval(interval);
}, []);

Pattern 2: Missing Key

// BUG: List items don't update correctly
{items.map((item, index) => (
  <Item key={index} {...item} />  // index key = bugs!
))}

// FIX: Use stable unique ID
{items.map((item) => (
  <Item key={item.id} {...item} />  // stable ID
))}

Pattern 3: Infinite Loop

// BUG: Infinite re-renders
function Component() {
  const [data, setData] = useState([]);

  useEffect(() => {
    setData([...data, newItem]); // data in effect body
  }, [data]); // data in deps = infinite loop
}

// FIX: Use functional update
useEffect(() => {
  setData(current => [...current, newItem]);
}, [newItem]); // Only depend on newItem

Pattern 4: Race Condition

// BUG: Shows wrong user data
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetchUser(userId).then(setUser);
    // If userId changes fast, old request might resolve after new one
  }, [userId]);
}

// FIX: Cancel stale requests
useEffect(() => {
  let cancelled = false;

  fetchUser(userId).then(user => {
    if (!cancelled) setUser(user);
  });

  return () => { cancelled = true; };
}, [userId]);

Pattern 5: Event Handler in Render

// BUG: New function every render, breaks memo
function Parent() {
  return <Child onClick={() => doSomething()} />;
}

// FIX: Use useCallback
function Parent() {
  const handleClick = useCallback(() => doSomething(), []);
  return <Child onClick={handleClick} />;
}

Pattern 6: Controlled vs Uncontrolled

// BUG: Warning about switching from uncontrolled to controlled
function Input() {
  const [value, setValue] = useState(); // undefined initially!

  return <input value={value} onChange={e => setValue(e.target.value)} />;
}

// FIX: Initialize with empty string
function Input() {
  const [value, setValue] = useState(''); // controlled from start

  return <input value={value} onChange={e => setValue(e.target.value)} />;
}

Writing Reproducing Tests

Template

import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';

describe('BugFix: [bug description]', () => {
  it('should [expected behavior] when [condition]', async () => {
    // Given - setup that reproduces the bug
    const user = userEvent.setup();

    // When - the action that triggers the bug
    render(<Component />);
    await user.click(screen.getByRole('button'));

    // Then - the expected behavior (fails before fix)
    await waitFor(() => {
      expect(screen.getByText('Success')).toBeInTheDocument();
    });
  });
});

Example: Stale State Bug

describe('BugFix: Counter shows stale value', () => {
  it('should increment correctly when clicked rapidly', async () => {
    const user = userEvent.setup();
    render(<Counter />);

    // Click 5 times rapidly
    const button = screen.getByRole('button', { name: /increment/i });
    await user.click(button);
    await user.click(button);
    await user.click(button);
    await user.click(button);
    await user.click(button);

    // Should be 5, not 1 (stale closure would show 1)
    expect(screen.getByText('5')).toBeInTheDocument();
  });
});

DevTools Debugging

React DevTools

1. Components tab:
   - Check component tree
   - Inspect props
   - Inspect state
   - Check hooks values

2. Profiler tab:
   - Record renders
   - Find unnecessary re-renders
   - Check render times

3. Console filtering:
   - Filter by "React" for React-specific messages
   - Look for warnings about keys, effects, etc.

Browser DevTools

1. Elements tab:
   - Check if element exists in DOM
   - Check computed styles
   - Check event listeners

2. Console:
   - console.log for debugging
   - console.trace for call stack

3. Network tab:
   - Check API requests
   - Verify response data