react-verification

React Verification Protocol

This is the PRIMARY FEEDBACK LOOP. You run these commands yourself via Bash, read the full output, diagnose using the patterns below, fix, and repeat.

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	npm run build passes	REQUIRED

⛔ BLOCKING: Any gate failure blocks completion. No exceptions.

The Verification Cycle

┌─────────────────────────────────────────────────────────────┐
│  1. TYPE CHECK                                               │
│     Run: npx tsc --noEmit                                    │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 type errors required                          │
│     If errors → go to Error→Fix table → fix → restart       │
│                                                              │
│  2. TEST                                                     │
│     Run: npm test -- --run                                   │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 failures required                             │
│     If failures → go to Error→Fix table → fix → restart     │
│                                                              │
│  3. COVERAGE ⚠️ MANDATORY                                    │
│     Run: npm test -- --coverage --run                        │
│     Check: coverage/lcov-report/index.html                   │
│     Parse: coverage/coverage-summary.json for exact %        │
│     ⛔ GATE: ≥ 80% line coverage required                    │
│     If < 80% → Add more tests → Re-run → Repeat              │
│     ⛔ Do NOT proceed if coverage < 80%                      │
│                                                              │
│  4. LINT                                                     │
│     Run: npm run lint                                        │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 errors required (warnings allowed)            │
│     If errors → fix lint issues → restart                   │
│                                                              │
│  5. BUILD                                                    │
│     Run: npm run build                                       │
│     Catches hydration errors, bundling issues                │
│     ⛔ GATE: Must pass                                       │
│                                                              │
│  ✓ ALL GATES PASS → VERIFICATION PASSED → May proceed       │
│  ✗ ANY GATE FAILS → VERIFICATION FAILED → Must fix first    │
└─────────────────────────────────────────────────────────────┘

Error→Fix Pattern Table

TypeScript Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic
Type 'X' is not assignable to type 'Y'	Type mismatch	Check interface definitions, verify prop types	Read component props interface
Property 'X' does not exist on type 'Y'	Missing property or typo	Check object shape, verify property name	Read type definition
Cannot find name 'X'	Missing import	Add import statement	Check file exports
Object is possibly 'undefined'	Null safety	Add null check or optional chaining	Verify data flow
Argument of type 'X' is not assignable to parameter of type 'Y'	Function parameter mismatch	Check function signature	Read function definition
Type 'X' has no properties in common with type 'Y'	Completely wrong type	Review type, likely wrong object	Compare structures
'X' is declared but never used	Unused variable	Remove or use the variable	Review if needed
Module '"X"' has no exported member 'Y'	Wrong import	Check available exports	Read module exports

Test Failures

Error Pattern	Root Cause	Fix Strategy	Diagnostic
Unable to find role="X"	Element not rendered or wrong role	Check component renders, verify semantic HTML	Inspect component output
Unable to find text: /X/	Text not rendered	Check conditional rendering, verify content	Log component state
expected element not to be in document	Element shouldn't exist but does	Check conditional logic	Inspect render conditions
not wrapped in act(...)	State update after test ends	Use waitFor() or act()	Wrap async operations
TypeError: Cannot read property 'X' of undefined	Missing mock or data	Setup proper mocks/test data	Check test setup
Expected mock function to have been called	Function not invoked	Verify event handlers, check conditions	Debug interaction flow
Timed out waiting for...	Async operation didn't complete	Increase timeout, check async logic	Add console logs

React-Specific Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic
Invalid hook call	Hook used outside component or conditionally	Move hook to component body, remove conditions	Check hook rules
Too many re-renders	Infinite loop in state update	Check useEffect deps, useState calls in render	Add console logs
Each child should have a unique "key" prop	Missing or duplicate keys	Add unique key to list items	Check list rendering
Cannot update a component while rendering	State update during render	Move to useEffect or event handler	Check render logic
Objects are not valid as React child	Rendering object instead of string	Access specific property or stringify	Check what's being rendered
Maximum update depth exceeded	Infinite useEffect loop	Fix dependency array	Check effect dependencies

Build Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic
Module not found: Can't resolve 'X'	Missing dependency or wrong path	Install package or fix import path	Check node_modules
SyntaxError: Unexpected token	Invalid JavaScript/JSX	Fix syntax, check for typos	Look at error location
ReferenceError: window is not defined	SSR issue (accessing browser APIs)	Use dynamic import or check typeof window	Wrap in useEffect
Hydration failed	Server/client mismatch	Ensure consistent rendering	Check conditional rendering

Lint Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic
react-hooks/exhaustive-deps	Missing hook dependencies	Add missing deps or disable with comment	Review if truly needed
react/prop-types	Missing prop types (if enabled)	Add TypeScript types	Define interface
no-unused-vars	Unused import/variable	Remove or use it	Check if needed
prefer-const	Using let for constant	Change to const	Review reassignments
@typescript-eslint/no-explicit-any	Using any type	Add proper type	Define interface

Diagnostic Commands

# TypeScript only - quick check
npx tsc --noEmit

# Single test file
npm test -- TodoItem.test.tsx

# Single test case
npm test -- -t "should render todo title"

# Watch mode for development
npm test -- --watch

# Coverage report
npm test -- --coverage

# Lint with fix
npm run lint -- --fix

# Build with verbose output
npm run build -- --verbose

# Check bundle size
npx vite-bundle-visualizer

Common Fixes

Fix: Type Mismatch

// Error: Type 'string | undefined' is not assignable to type 'string'
// Before
const name: string = user?.name;

// After - with fallback
const name: string = user?.name ?? '';

// After - with type guard
if (user?.name) {
  const name: string = user.name;
}

Fix: Missing Null Check

// Error: Object is possibly 'undefined'
// Before
const value = data.items[0].name;

// After
const value = data?.items?.[0]?.name ?? 'default';

Fix: Hook Dependencies

// Error: React Hook useEffect has missing dependencies
// Before
useEffect(() => {
  fetchUser(userId);
}, []); // missing userId

// After
useEffect(() => {
  fetchUser(userId);
}, [userId]);

Fix: Act Warning

// Error: not wrapped in act(...)
// Before
it('should update on click', () => {
  render(<Counter />);
  fireEvent.click(screen.getByRole('button'));
  expect(screen.getByText('1')).toBeInTheDocument();
});

// After
it('should update on click', async () => {
  render(<Counter />);
  await userEvent.click(screen.getByRole('button'));
  await waitFor(() => {
    expect(screen.getByText('1')).toBeInTheDocument();
  });
});

Fix: Key Prop

// Error: Each child should have a unique "key" prop
// Before
{items.map((item) => <Item {...item} />)}

// After
{items.map((item) => <Item key={item.id} {...item} />)}

Max Retry Rule

After 3 attempts at fixing the SAME error:

1. Summarize what you've tried
2. Show the error output
3. Ask the developer for guidance

Do NOT:

• Keep trying the same fix
• Silently skip the failing test
• Use any type to suppress errors
• Disable ESLint rules without justification
• Declare "done" with failures