Back to Blog
Testing

React Testing Library: Best Practices and Patterns

19 min read3708 words
#react#testing#react-testing-library#javascript#accessibility

After writing thousands of React tests across dozens of projects, I've learned that the difference between tests that give you confidence and tests that break with every refactor comes down to one principle: test your components the way your users use them.

In this guide, I'll share the testing patterns that helped my teams catch 90% of bugs before production, reduce test maintenance by 60%, and ship features with confidence even on tight deadlines.

The Mental Model Shift

When I first started with React Testing Library, I fought against it. Coming from Enzyme, I wanted to access component state, test method calls, and assert on implementation details. RTL felt restrictive.

That was the point.

React Testing Library forces you to think like a user, not like a developer. This shift in perspective leads to tests that:

  • Break less frequently when you refactor
  • Catch bugs users actually encounter
  • Guide you toward accessible component design
  • Give you real confidence in your application

Core Testing Patterns

Pattern 1: User-Centric Queries

Always prefer queries that users would use to find elements:

// ❌ Bad: Testing implementation details
const { container } = render(<LoginForm />);
const emailInput = container.querySelector('[data-testid="email-input"]');
 
// ✅ Good: Testing like a user would interact
render(<LoginForm />);
const emailInput = screen.getByLabelText(/email address/i);
// or
const emailInput = screen.getByRole('textbox', { name: /email address/i });

Here's my query priority order:

  1. getByRole - Best for interactive elements
  2. getByLabelText - Perfect for form inputs
  3. getByText - Great for content elements
  4. getByDisplayValue - For inputs with default values
  5. getByAltText - For images
  6. getByTestId - Last resort only

Pattern 2: Comprehensive Form Testing

Forms are the heart of most applications. Here's how I test them thoroughly:

// components/LoginForm.jsx
import React, { useState } from 'react';
 
const LoginForm = ({ onSubmit, isLoading }) => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
 
  const handleSubmit = async (e) => {
    e.preventDefault();
    setError('');
 
    if (!email || !password) {
      setError('Please fill in all fields');
      return;
    }
 
    try {
      await onSubmit({ email, password });
    } catch (err) {
      setError(err.message || 'Login failed');
    }
  };
 
  return (
    <form onSubmit={handleSubmit} aria-label="Login form">
      <div>
        <label htmlFor="email">Email Address</label>
        <input
          id="email"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          disabled={isLoading}
          aria-describedby={error ? 'error-message' : undefined}
        />
      </div>
 
      <div>
        <label htmlFor="password">Password</label>
        <input
          id="password"
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          disabled={isLoading}
          aria-describedby={error ? 'error-message' : undefined}
        />
      </div>
 
      {error && (
        <div id="error-message" role="alert" aria-live="polite">
          {error}
        </div>
      )}
 
      <button
        type="submit"
        disabled={isLoading || !email || !password}
        aria-describedby={isLoading ? 'loading-message' : undefined}
      >
        {isLoading ? 'Signing In...' : 'Sign In'}
      </button>
 
      {isLoading && (
        <div id="loading-message" aria-live="polite">
          Please wait while we sign you in
        </div>
      )}
    </form>
  );
};
 
export default LoginForm;
// __tests__/LoginForm.test.js
import React from 'react';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import LoginForm from '../LoginForm';
 
describe('LoginForm', () => {
  let mockOnSubmit;
  let user;
 
  beforeEach(() => {
    mockOnSubmit = jest.fn();
    user = userEvent.setup();
  });
 
  test('renders form with accessible labels and structure', () => {
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    // Check form structure
    expect(screen.getByRole('form', { name: /login form/i })).toBeInTheDocument();
    
    // Check input accessibility
    expect(screen.getByLabelText(/email address/i)).toBeInTheDocument();
    expect(screen.getByLabelText(/password/i)).toBeInTheDocument();
    
    // Check submit button
    expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
  });
 
  test('allows user to enter email and password', async () => {
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    const emailInput = screen.getByLabelText(/email address/i);
    const passwordInput = screen.getByLabelText(/password/i);
 
    await user.type(emailInput, 'user@example.com');
    await user.type(passwordInput, 'password123');
 
    expect(emailInput).toHaveValue('user@example.com');
    expect(passwordInput).toHaveValue('password123');
  });
 
  test('enables submit button only when both fields are filled', async () => {
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    const submitButton = screen.getByRole('button', { name: /sign in/i });
    const emailInput = screen.getByLabelText(/email address/i);
    const passwordInput = screen.getByLabelText(/password/i);
 
    // Initially disabled
    expect(submitButton).toBeDisabled();
 
    // Still disabled with only email
    await user.type(emailInput, 'user@example.com');
    expect(submitButton).toBeDisabled();
 
    // Enabled when both fields filled
    await user.type(passwordInput, 'password123');
    expect(submitButton).toBeEnabled();
 
    // Disabled again when password cleared
    await user.clear(passwordInput);
    expect(submitButton).toBeDisabled();
  });
 
  test('shows validation error for empty fields', async () => {
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    const submitButton = screen.getByRole('button', { name: /sign in/i });
    
    // Try to submit empty form (button will be disabled, so we simulate the scenario)
    fireEvent.click(submitButton);
 
    await waitFor(() => {
      expect(screen.getByRole('alert')).toHaveTextContent(/please fill in all fields/i);
    });
 
    expect(mockOnSubmit).not.toHaveBeenCalled();
  });
 
  test('calls onSubmit with form data when form is valid', async () => {
    mockOnSubmit.mockResolvedValue();
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    await user.type(screen.getByLabelText(/email address/i), 'user@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    
    await user.click(screen.getByRole('button', { name: /sign in/i }));
 
    await waitFor(() => {
      expect(mockOnSubmit).toHaveBeenCalledWith({
        email: 'user@example.com',
        password: 'password123'
      });
    });
  });
 
  test('shows loading state during submission', async () => {
    // Mock a delayed response
    mockOnSubmit.mockImplementation(() => 
      new Promise(resolve => setTimeout(resolve, 100))
    );
    
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    await user.type(screen.getByLabelText(/email address/i), 'user@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    
    const submitButton = screen.getByRole('button', { name: /sign in/i });
    await user.click(submitButton);
 
    // Check loading state
    expect(screen.getByRole('button', { name: /signing in/i })).toBeDisabled();
    expect(screen.getByText(/please wait while we sign you in/i)).toBeInTheDocument();
 
    // Wait for loading to complete
    await waitFor(() => {
      expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled();
    });
  });
 
  test('handles submission errors gracefully', async () => {
    const errorMessage = 'Invalid credentials';
    mockOnSubmit.mockRejectedValue(new Error(errorMessage));
    
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    await user.type(screen.getByLabelText(/email address/i), 'user@example.com');
    await user.type(screen.getByLabelText(/password/i), 'wrongpassword');
    
    await user.click(screen.getByRole('button', { name: /sign in/i }));
 
    await waitFor(() => {
      expect(screen.getByRole('alert')).toHaveTextContent(errorMessage);
    });
 
    // Form should still be usable after error
    expect(screen.getByRole('button', { name: /sign in/i })).toBeEnabled();
  });
 
  test('supports keyboard navigation', async () => {
    render(<LoginForm onSubmit={mockOnSubmit} />);
 
    // Tab through form elements
    await user.tab();
    expect(screen.getByLabelText(/email address/i)).toHaveFocus();
 
    await user.tab();
    expect(screen.getByLabelText(/password/i)).toHaveFocus();
 
    await user.tab();
    expect(screen.getByRole('button', { name: /sign in/i })).toHaveFocus();
  });
});

Pattern 3: Testing Async Operations

For components that fetch data or handle async operations:

// components/UserProfile.jsx
import React, { useEffect, useState } from 'react';
 
const UserProfile = ({ userId }) => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);
 
  useEffect(() => {
    const fetchUser = async () => {
      try {
        setLoading(true);
        setError(null);
        
        const response = await fetch(`/api/users/${userId}`);
        if (!response.ok) {
          throw new Error('Failed to fetch user');
        }
        
        const userData = await response.json();
        setUser(userData);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };
 
    if (userId) {
      fetchUser();
    }
  }, [userId]);
 
  if (loading) {
    return (
      <div role="status" aria-live="polite">
        Loading user profile...
      </div>
    );
  }
 
  if (error) {
    return (
      <div role="alert" aria-live="assertive">
        Error: {error}
      </div>
    );
  }
 
  if (!user) {
    return (
      <div>No user found</div>
    );
  }
 
  return (
    <div>
      <h2>{user.name}</h2>
      <p>Email: {user.email}</p>
      <p>Role: {user.role}</p>
    </div>
  );
};
 
export default UserProfile;
// __tests__/UserProfile.test.js
import React from 'react';
import { render, screen, waitFor } from '@testing-library/react';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import UserProfile from '../UserProfile';
 
// Mock server setup
const server = setupServer();
 
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
 
describe('UserProfile', () => {
  const mockUser = {
    id: 1,
    name: 'John Doe',
    email: 'john@example.com',
    role: 'admin'
  };
 
  test('shows loading state initially', () => {
    render(<UserProfile userId={1} />);
 
    expect(screen.getByRole('status')).toHaveTextContent(/loading user profile/i);
  });
 
  test('displays user information after successful fetch', async () => {
    server.use(
      rest.get('/api/users/1', (req, res, ctx) => {
        return res(ctx.json(mockUser));
      })
    );
 
    render(<UserProfile userId={1} />);
 
    // Wait for loading to finish and user data to appear
    await waitFor(() => {
      expect(screen.getByRole('heading', { level: 2 })).toHaveTextContent('John Doe');
    });
 
    expect(screen.getByText('Email: john@example.com')).toBeInTheDocument();
    expect(screen.getByText('Role: admin')).toBeInTheDocument();
 
    // Loading should be gone
    expect(screen.queryByRole('status')).not.toBeInTheDocument();
  });
 
  test('displays error message when fetch fails', async () => {
    server.use(
      rest.get('/api/users/1', (req, res, ctx) => {
        return res(ctx.status(500), ctx.json({ error: 'Server error' }));
      })
    );
 
    render(<UserProfile userId={1} />);
 
    await waitFor(() => {
      expect(screen.getByRole('alert')).toHaveTextContent(/failed to fetch user/i);
    });
 
    // Loading should be gone
    expect(screen.queryByRole('status')).not.toBeInTheDocument();
    // User data should not be shown
    expect(screen.queryByRole('heading', { level: 2 })).not.toBeInTheDocument();
  });
 
  test('handles network errors gracefully', async () => {
    server.use(
      rest.get('/api/users/1', (req, res) => {
        return res.networkError('Network error');
      })
    );
 
    render(<UserProfile userId={1} />);
 
    await waitFor(() => {
      expect(screen.getByRole('alert')).toBeInTheDocument();
    });
  });
 
  test('fetches new user data when userId changes', async () => {
    const secondUser = { ...mockUser, id: 2, name: 'Jane Doe' };
 
    server.use(
      rest.get('/api/users/1', (req, res, ctx) => res(ctx.json(mockUser))),
      rest.get('/api/users/2', (req, res, ctx) => res(ctx.json(secondUser)))
    );
 
    const { rerender } = render(<UserProfile userId={1} />);
 
    // Wait for first user
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
    });
 
    // Change user ID
    rerender(<UserProfile userId={2} />);
 
    // Should show loading again
    expect(screen.getByRole('status')).toBeInTheDocument();
 
    // Wait for second user
    await waitFor(() => {
      expect(screen.getByText('Jane Doe')).toBeInTheDocument();
    });
  });
 
  test('does not fetch when no userId provided', () => {
    render(<UserProfile userId={null} />);
 
    expect(screen.getByText('No user found')).toBeInTheDocument();
    expect(screen.queryByRole('status')).not.toBeInTheDocument();
  });
});

Pattern 4: Testing Custom Hooks

Here's how I test custom hooks by focusing on their observable effects:

// hooks/useLocalStorage.js
import { useState, useEffect } from 'react';
 
export const useLocalStorage = (key, defaultValue) => {
  const [value, setValue] = useState(() => {
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : defaultValue;
    } catch (error) {
      console.error(`Error reading localStorage key "${key}":`, error);
      return defaultValue;
    }
  });
 
  useEffect(() => {
    try {
      window.localStorage.setItem(key, JSON.stringify(value));
    } catch (error) {
      console.error(`Error setting localStorage key "${key}":`, error);
    }
  }, [key, value]);
 
  return [value, setValue];
};
// __tests__/useLocalStorage.test.js
import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react';
import { useLocalStorage } from '../useLocalStorage';
 
// Test component that uses the hook
const TestComponent = ({ storageKey, defaultValue }) => {
  const [value, setValue] = useLocalStorage(storageKey, defaultValue);
 
  return (
    <div>
      <span data-testid="current-value">{JSON.stringify(value)}</span>
      <button onClick={() => setValue('new value')}>
        Update Value
      </button>
      <button onClick={() => setValue({ nested: 'object' })}>
        Set Object
      </button>
      <button onClick={() => setValue(null)}>
        Clear Value
      </button>
    </div>
  );
};
 
describe('useLocalStorage', () => {
  beforeEach(() => {
    // Clear localStorage before each test
    localStorage.clear();
    // Clear console.error calls
    jest.clearAllMocks();
  });
 
  test('returns default value when localStorage is empty', () => {
    render(<TestComponent storageKey="test-key" defaultValue="default" />);
 
    expect(screen.getByTestId('current-value')).toHaveTextContent('"default"');
  });
 
  test('returns stored value from localStorage', () => {
    localStorage.setItem('test-key', JSON.stringify('stored value'));
    
    render(<TestComponent storageKey="test-key" defaultValue="default" />);
 
    expect(screen.getByTestId('current-value')).toHaveTextContent('"stored value"');
  });
 
  test('updates localStorage when value changes', () => {
    render(<TestComponent storageKey="test-key" defaultValue="default" />);
 
    fireEvent.click(screen.getByText('Update Value'));
 
    expect(screen.getByTestId('current-value')).toHaveTextContent('"new value"');
    expect(localStorage.getItem('test-key')).toBe('"new value"');
  });
 
  test('handles complex objects', () => {
    render(<TestComponent storageKey="test-key" defaultValue={{}} />);
 
    fireEvent.click(screen.getByText('Set Object'));
 
    expect(screen.getByTestId('current-value')).toHaveTextContent('{"nested":"object"}');
    expect(JSON.parse(localStorage.getItem('test-key'))).toEqual({ nested: 'object' });
  });
 
  test('handles null values', () => {
    render(<TestComponent storageKey="test-key" defaultValue="default" />);
 
    fireEvent.click(screen.getByText('Clear Value'));
 
    expect(screen.getByTestId('current-value')).toHaveTextContent('null');
    expect(localStorage.getItem('test-key')).toBe('null');
  });
 
  test('handles localStorage errors gracefully', () => {
    const consoleSpy = jest.spyOn(console, 'error').mockImplementation();
    
    // Mock localStorage to throw an error
    const originalSetItem = Storage.prototype.setItem;
    Storage.prototype.setItem = jest.fn(() => {
      throw new Error('localStorage is full');
    });
 
    render(<TestComponent storageKey="test-key" defaultValue="default" />);
 
    fireEvent.click(screen.getByText('Update Value'));
 
    // Should log error but not crash
    expect(consoleSpy).toHaveBeenCalledWith(
      'Error setting localStorage key "test-key":',
      expect.any(Error)
    );
 
    // Restore original method
    Storage.prototype.setItem = originalSetItem;
    consoleSpy.mockRestore();
  });
 
  test('handles invalid JSON in localStorage', () => {
    const consoleSpy = jest.spyOn(console, 'error').mockImplementation();
    
    localStorage.setItem('test-key', 'invalid json {');
    
    render(<TestComponent storageKey="test-key" defaultValue="fallback" />);
 
    // Should use default value when JSON is invalid
    expect(screen.getByTestId('current-value')).toHaveTextContent('"fallback"');
    expect(consoleSpy).toHaveBeenCalledWith(
      'Error reading localStorage key "test-key":',
      expect.any(Error)
    );
 
    consoleSpy.mockRestore();
  });
});

Pattern 5: Integration Testing

Test how multiple components work together:

// components/TodoApp.jsx
import React, { useState } from 'react';
import TodoList from './TodoList';
import TodoForm from './TodoForm';
 
const TodoApp = () => {
  const [todos, setTodos] = useState([]);
 
  const addTodo = (text) => {
    const newTodo = {
      id: Date.now(),
      text,
      completed: false,
    };
    setTodos(prev => [...prev, newTodo]);
  };
 
  const toggleTodo = (id) => {
    setTodos(prev =>
      prev.map(todo =>
        todo.id === id ? { ...todo, completed: !todo.completed } : todo
      )
    );
  };
 
  const deleteTodo = (id) => {
    setTodos(prev => prev.filter(todo => todo.id !== id));
  };
 
  return (
    <div>
      <h1>Todo App</h1>
      <TodoForm onAddTodo={addTodo} />
      <TodoList
        todos={todos}
        onToggleTodo={toggleTodo}
        onDeleteTodo={deleteTodo}
      />
    </div>
  );
};
 
export default TodoApp;
// __tests__/TodoApp.integration.test.js
import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import TodoApp from '../TodoApp';
 
describe('TodoApp Integration', () => {
  let user;
 
  beforeEach(() => {
    user = userEvent.setup();
  });
 
  test('complete todo workflow', async () => {
    render(<TodoApp />);
 
    // Add first todo
    const input = screen.getByLabelText(/add new todo/i);
    const addButton = screen.getByRole('button', { name: /add todo/i });
 
    await user.type(input, 'Buy groceries');
    await user.click(addButton);
 
    // Verify todo appears in list
    expect(screen.getByText('Buy groceries')).toBeInTheDocument();
    expect(screen.getByRole('checkbox', { name: /buy groceries/i })).not.toBeChecked();
 
    // Add second todo
    await user.type(input, 'Walk the dog');
    await user.click(addButton);
 
    // Both todos should be visible
    expect(screen.getByText('Buy groceries')).toBeInTheDocument();
    expect(screen.getByText('Walk the dog')).toBeInTheDocument();
 
    // Complete first todo
    await user.click(screen.getByRole('checkbox', { name: /buy groceries/i }));
    expect(screen.getByRole('checkbox', { name: /buy groceries/i })).toBeChecked();
 
    // Delete completed todo
    await user.click(screen.getByRole('button', { name: /delete buy groceries/i }));
    expect(screen.queryByText('Buy groceries')).not.toBeInTheDocument();
 
    // Second todo should still be there
    expect(screen.getByText('Walk the dog')).toBeInTheDocument();
  });
 
  test('prevents adding empty todos', async () => {
    render(<TodoApp />);
 
    const addButton = screen.getByRole('button', { name: /add todo/i });
 
    // Try to add empty todo
    await user.click(addButton);
 
    // No todos should appear
    expect(screen.queryByRole('list')).not.toBeInTheDocument();
  });
 
  test('handles rapid user interactions', async () => {
    render(<TodoApp />);
 
    const input = screen.getByLabelText(/add new todo/i);
    const addButton = screen.getByRole('button', { name: /add todo/i });
 
    // Add multiple todos quickly
    const todoTexts = ['Todo 1', 'Todo 2', 'Todo 3'];
    
    for (const text of todoTexts) {
      await user.type(input, text);
      await user.click(addButton);
    }
 
    // All todos should be present
    todoTexts.forEach(text => {
      expect(screen.getByText(text)).toBeInTheDocument();
    });
 
    // Complete all todos quickly
    const checkboxes = screen.getAllByRole('checkbox');
    for (const checkbox of checkboxes) {
      await user.click(checkbox);
    }
 
    // All should be checked
    checkboxes.forEach(checkbox => {
      expect(checkbox).toBeChecked();
    });
  });
});

Advanced Testing Patterns

Testing with Context

// contexts/AuthContext.js
import React, { createContext, useContext, useState } from 'react';
 
const AuthContext = createContext();
 
export const useAuth = () => {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
};
 
export const AuthProvider = ({ children }) => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(false);
 
  const login = async (credentials) => {
    setLoading(true);
    try {
      // Simulate API call
      const response = await fetch('/api/login', {
        method: 'POST',
        body: JSON.stringify(credentials),
      });
      
      if (!response.ok) throw new Error('Login failed');
      
      const userData = await response.json();
      setUser(userData);
      return userData;
    } finally {
      setLoading(false);
    }
  };
 
  const logout = () => {
    setUser(null);
  };
 
  return (
    <AuthContext.Provider value={{ user, login, logout, loading }}>
      {children}
    </AuthContext.Provider>
  );
};
// __tests__/AuthContext.test.js
import React from 'react';
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import { AuthProvider, useAuth } from '../AuthContext';
 
const server = setupServer();
 
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
 
// Test component that uses auth context
const AuthTestComponent = () => {
  const { user, login, logout, loading } = useAuth();
 
  return (
    <div>
      {loading && <div role="status">Loading...</div>}
      {user ? (
        <div>
          <p>Welcome, {user.name}!</p>
          <button onClick={logout}>Logout</button>
        </div>
      ) : (
        <div>
          <p>Please log in</p>
          <button
            onClick={() => login({ email: 'test@example.com', password: 'password' })}
          >
            Login
          </button>
        </div>
      )}
    </div>
  );
};
 
const renderWithAuth = (component) => {
  return render(
    <AuthProvider>
      {component}
    </AuthProvider>
  );
};
 
describe('AuthContext', () => {
  test('provides authentication state and methods', () => {
    renderWithAuth(<AuthTestComponent />);
 
    expect(screen.getByText('Please log in')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
  });
 
  test('handles successful login', async () => {
    server.use(
      rest.post('/api/login', (req, res, ctx) => {
        return res(ctx.json({ id: 1, name: 'John Doe', email: 'test@example.com' }));
      })
    );
 
    const user = userEvent.setup();
    renderWithAuth(<AuthTestComponent />);
 
    await user.click(screen.getByRole('button', { name: /login/i }));
 
    // Should show loading
    expect(screen.getByRole('status')).toBeInTheDocument();
 
    // Wait for login to complete
    await waitFor(() => {
      expect(screen.getByText('Welcome, John Doe!')).toBeInTheDocument();
    });
 
    expect(screen.getByRole('button', { name: /logout/i })).toBeInTheDocument();
    expect(screen.queryByRole('status')).not.toBeInTheDocument();
  });
 
  test('handles login errors', async () => {
    server.use(
      rest.post('/api/login', (req, res, ctx) => {
        return res(ctx.status(401), ctx.json({ error: 'Invalid credentials' }));
      })
    );
 
    const user = userEvent.setup();
    renderWithAuth(<AuthTestComponent />);
 
    await user.click(screen.getByRole('button', { name: /login/i }));
 
    // Should still show login after error
    await waitFor(() => {
      expect(screen.getByText('Please log in')).toBeInTheDocument();
    });
 
    expect(screen.queryByRole('status')).not.toBeInTheDocument();
  });
 
  test('handles logout', async () => {
    // Start with logged in state
    server.use(
      rest.post('/api/login', (req, res, ctx) => {
        return res(ctx.json({ id: 1, name: 'John Doe', email: 'test@example.com' }));
      })
    );
 
    const user = userEvent.setup();
    renderWithAuth(<AuthTestComponent />);
 
    // Login first
    await user.click(screen.getByRole('button', { name: /login/i }));
    await waitFor(() => {
      expect(screen.getByText('Welcome, John Doe!')).toBeInTheDocument();
    });
 
    // Then logout
    await user.click(screen.getByRole('button', { name: /logout/i }));
 
    expect(screen.getByText('Please log in')).toBeInTheDocument();
    expect(screen.queryByText('Welcome, John Doe!')).not.toBeInTheDocument();
  });
});

Testing Accessibility

RTL encourages accessibility by default, but here are specific patterns:

// components/Modal.jsx
import React, { useEffect } from 'react';
import { createPortal } from 'react-dom';
 
const Modal = ({ isOpen, onClose, title, children }) => {
  useEffect(() => {
    if (isOpen) {
      // Focus management
      const modal = document.getElementById('modal');
      if (modal) {
        modal.focus();
      }
 
      // Escape key handler
      const handleEscape = (e) => {
        if (e.key === 'Escape') {
          onClose();
        }
      };
 
      document.addEventListener('keydown', handleEscape);
      return () => document.removeEventListener('keydown', handleEscape);
    }
  }, [isOpen, onClose]);
 
  if (!isOpen) return null;
 
  return createPortal(
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
      id="modal"
      tabIndex={-1}
      style={{
        position: 'fixed',
        top: 0,
        left: 0,
        right: 0,
        bottom: 0,
        backgroundColor: 'rgba(0,0,0,0.5)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center',
      }}
      onClick={(e) => {
        if (e.target === e.currentTarget) {
          onClose();
        }
      }}
    >
      <div
        style={{
          backgroundColor: 'white',
          padding: '2rem',
          borderRadius: '8px',
          minWidth: '300px',
        }}
        onClick={(e) => e.stopPropagation()}
      >
        <h2 id="modal-title">{title}</h2>
        <div>{children}</div>
        <button
          onClick={onClose}
          aria-label={`Close ${title} dialog`}
          style={{ marginTop: '1rem' }}
        >
          Close
        </button>
      </div>
    </div>,
    document.body
  );
};
 
export default Modal;
// __tests__/Modal.a11y.test.js
import React from 'react';
import { render, screen, fireEvent } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { axe, toHaveNoViolations } from 'jest-axe';
import Modal from '../Modal';
 
expect.extend(toHaveNoViolations);
 
describe('Modal Accessibility', () => {
  let user;
 
  beforeEach(() => {
    user = userEvent.setup();
  });
 
  test('has proper ARIA attributes', () => {
    render(
      <Modal isOpen={true} onClose={jest.fn()} title="Test Modal">
        <p>Modal content</p>
      </Modal>
    );
 
    const modal = screen.getByRole('dialog');
    expect(modal).toHaveAttribute('aria-modal', 'true');
    expect(modal).toHaveAttribute('aria-labelledby', 'modal-title');
    
    expect(screen.getByRole('heading', { level: 2 })).toHaveAttribute('id', 'modal-title');
  });
 
  test('traps focus within modal', async () => {
    render(
      <Modal isOpen={true} onClose={jest.fn()} title="Test Modal">
        <button>Modal Button</button>
        <input placeholder="Modal Input" />
      </Modal>
    );
 
    // Modal should be focused initially
    expect(screen.getByRole('dialog')).toHaveFocus();
 
    // Tab should move to first interactive element
    await user.tab();
    expect(screen.getByText('Modal Button')).toHaveFocus();
 
    await user.tab();
    expect(screen.getByPlaceholderText('Modal Input')).toHaveFocus();
 
    await user.tab();
    expect(screen.getByRole('button', { name: /close test modal dialog/i })).toHaveFocus();
 
    // Tab should wrap back to modal content
    await user.tab();
    expect(screen.getByText('Modal Button')).toHaveFocus();
  });
 
  test('closes on escape key', async () => {
    const mockOnClose = jest.fn();
    render(
      <Modal isOpen={true} onClose={mockOnClose} title="Test Modal">
        <p>Modal content</p>
      </Modal>
    );
 
    await user.keyboard('{Escape}');
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
 
  test('closes when clicking backdrop', async () => {
    const mockOnClose = jest.fn();
    render(
      <Modal isOpen={true} onClose={mockOnClose} title="Test Modal">
        <p>Modal content</p>
      </Modal>
    );
 
    // Click on backdrop (dialog element)
    await user.click(screen.getByRole('dialog'));
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
 
  test('does not close when clicking modal content', async () => {
    const mockOnClose = jest.fn();
    render(
      <Modal isOpen={true} onClose={mockOnClose} title="Test Modal">
        <p>Modal content</p>
      </Modal>
    );
 
    // Click on modal content
    await user.click(screen.getByText('Modal content'));
    expect(mockOnClose).not.toHaveBeenCalled();
  });
 
  test('has no accessibility violations', async () => {
    const { container } = render(
      <Modal isOpen={true} onClose={jest.fn()} title="Test Modal">
        <p>Modal content</p>
        <button>Action Button</button>
      </Modal>
    );
 
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
 
  test('close button has descriptive label', () => {
    render(
      <Modal isOpen={true} onClose={jest.fn()} title="User Settings">
        <p>Modal content</p>
      </Modal>
    );
 
    expect(screen.getByRole('button', { name: /close user settings dialog/i })).toBeInTheDocument();
  });
});

Common Anti-Patterns to Avoid

Anti-Pattern 1: Testing Implementation Details

// ❌ Bad: Testing internal state
test('component state updates correctly', () => {
  const wrapper = shallow(<Counter />);
  expect(wrapper.state('count')).toBe(0);
  wrapper.instance().increment();
  expect(wrapper.state('count')).toBe(1);
});
 
// ✅ Good: Testing user-observable behavior
test('displays updated count when increment button is clicked', async () => {
  const user = userEvent.setup();
  render(<Counter />);
  
  expect(screen.getByText('Count: 0')).toBeInTheDocument();
  
  await user.click(screen.getByRole('button', { name: /increment/i }));
  
  expect(screen.getByText('Count: 1')).toBeInTheDocument();
});

Anti-Pattern 2: Over-Mocking

// ❌ Bad: Mocking everything
jest.mock('../components/UserList', () => {
  return function MockUserList() {
    return <div>Mocked User List</div>;
  };
});
 
// ✅ Good: Only mock external dependencies
jest.mock('../api/userService', () => ({
  fetchUsers: jest.fn(),
}));

Anti-Pattern 3: Testing Library Internals

// ❌ Bad: Testing React internals
test('component rerenders when props change', () => {
  const spy = jest.spyOn(React, 'createElement');
  const { rerender } = render(<MyComponent prop="initial" />);
  
  rerender(<MyComponent prop="changed" />);
  
  expect(spy).toHaveBeenCalledTimes(2);
});
 
// ✅ Good: Testing user-visible changes
test('displays updated content when props change', () => {
  const { rerender } = render(<MyComponent message="Hello" />);
  expect(screen.getByText('Hello')).toBeInTheDocument();
  
  rerender(<MyComponent message="Goodbye" />);
  expect(screen.getByText('Goodbye')).toBeInTheDocument();
});

Test Organization and Maintainability

Custom Render Utilities

Create reusable test utilities:

// test-utils/render.js
import React from 'react';
import { render, queries } from '@testing-library/react';
import { BrowserRouter } from 'react-router-dom';
import { AuthProvider } from '../contexts/AuthContext';
import { ThemeProvider } from '../contexts/ThemeContext';
import * as customQueries from './custom-queries';
 
const allQueries = {
  ...queries,
  ...customQueries,
};
 
const AllTheProviders = ({ children }) => {
  return (
    <BrowserRouter>
      <AuthProvider>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </AuthProvider>
    </BrowserRouter>
  );
};
 
const customRender = (ui, options) =>
  render(ui, { 
    wrapper: AllTheProviders, 
    queries: allQueries,
    ...options 
  });
 
// Re-export everything
export * from '@testing-library/react';
export { customRender as render };

Test Data Factories

Create maintainable test data:

// test-utils/factories.js
export const createUser = (overrides = {}) => ({
  id: 1,
  name: 'John Doe',
  email: 'john@example.com',
  role: 'user',
  createdAt: new Date().toISOString(),
  ...overrides,
});
 
export const createPost = (overrides = {}) => ({
  id: 1,
  title: 'Test Post',
  content: 'This is a test post',
  author: createUser(),
  publishedAt: new Date().toISOString(),
  tags: ['test', 'example'],
  ...overrides,
});
 
// Usage in tests
test('displays post information', () => {
  const post = createPost({
    title: 'My Custom Post',
    author: createUser({ name: 'Jane Smith' })
  });
  
  render(<PostCard post={post} />);
  
  expect(screen.getByText('My Custom Post')).toBeInTheDocument();
  expect(screen.getByText('By Jane Smith')).toBeInTheDocument();
});

Performance Testing

Monitor test performance and optimize:

// test-utils/performance.js
export const measureRenderTime = (componentFn) => {
  const start = performance.now();
  const result = componentFn();
  const end = performance.now();
  
  return {
    ...result,
    renderTime: end - start,
  };
};
 
// Usage
test('component renders within performance budget', () => {
  const { renderTime } = measureRenderTime(() => 
    render(<ComplexComponent data={largeDataset} />)
  );
  
  // Should render within 100ms
  expect(renderTime).toBeLessThan(100);
});

The Testing Philosophy That Changed Everything

The biggest shift in my testing approach came when I stopped asking "How do I test this component?" and started asking "How would a user interact with this feature?"

This change led to:

  • Tests that survive refactoring because they focus on behavior, not implementation
  • Better component design because accessible components are easier to test
  • Higher confidence because tests mirror real usage patterns
  • Faster debugging because test failures indicate actual user problems

React Testing Library isn't just a testing tool—it's a design philosophy that makes you build better, more accessible applications. The constraints it imposes guide you toward code that's not just testable, but genuinely better for your users.

Start with one component. Test it the way a user would interact with it. I guarantee you'll catch bugs you never knew existed and discover accessibility issues you never considered. That's the power of user-centric testing.