docs/testing/unit-testing.md - tooling-gofannon - Git at Google

 # Unit Testing Guide

 Unit tests verify individual functions, classes, and components in isolation from external dependencies.

 ## Overview

 - **Framework (Frontend)**: Vitest + React Testing Library
 - **Framework (Backend)**: pytest + pytest-mock
 - **Location**: `tests/unit/` directory
 - **Mocking**: Mock all external dependencies (DB, APIs, file system)
 - **Coverage**: Must maintain ≥95% coverage

 ## Writing Backend Unit Tests (Python)

 ### Basic Structure

 ```python
 import pytest
 from unittest.mock import Mock, AsyncMock
 from services.user_service import UserService

 pytestmark = pytest.mark.unit  # Mark as unit test


 class TestUserService:
     """Test suite for UserService class."""

     @pytest.fixture
     def mock_db(self):
         """Create a mock database service."""
         db = Mock()
         db.get = Mock(return_value={"id": "test-123"})
         db.save = Mock(return_value={"rev": "test-rev"})
         return db

     @pytest.fixture
     def user_service(self, mock_db):
         """Create a UserService instance with mock database."""
         return UserService(mock_db)

     def test_get_user_existing(self, user_service, mock_db):
         """Test getting an existing user."""
         user = user_service.get_user("test-123")

         mock_db.get.assert_called_once_with("users", "test-123")
         assert user.id == "test-123"

     def test_get_user_not_found(self, user_service, mock_db):
         """Test handling of user not found."""
         from fastapi import HTTPException
         mock_db.get.side_effect = HTTPException(status_code=404)

         user = user_service.get_user("new-user")

         assert user.id == "new-user"
         mock_db.save.assert_called_once()  # Creates new user
 ```

 ### Using Test Factories

 ```python
 from tests.factories.user_factory import UserFactory

 def test_user_creation():
     """Test user creation with factory data."""
     user_data = UserFactory.build()

     assert "uid" in user_data
     assert "email" in user_data
     assert user_data["email_verified"] == True

 def test_multiple_users():
     """Create multiple test users."""
     users = UserFactory.build_batch(5)

     assert len(users) == 5
     assert all(u["email"] for u in users)
 ```

 ### Testing Async Functions

 ```python
 import pytest

 pytestmark = pytest.mark.asyncio  # Enable async support


 async def test_async_function():
     """Test an async function."""
     result = await my_async_function()
     assert result == expected_value


 async def test_with_async_mock(mocker):
     """Test with async mocked dependency."""
     mock_service = mocker.AsyncMock()
     mock_service.fetch_data.return_value = {"data": "test"}

     result = await function_using_service(mock_service)

     mock_service.fetch_data.assert_called_once()
     assert result["data"] == "test"
 ```

 ### Testing Models (Pydantic)

 ```python
 import pytest
 from pydantic import ValidationError
 from models.user import User, BasicInfo

 def test_user_creation_minimal():
     """Test creating a User with minimal required fields."""
     user = User(_id="test-123")

     assert user.id == "test-123"
     assert user.rev is None

 def test_user_validation_fails_without_id():
     """Test that User requires an ID."""
     with pytest.raises(ValidationError):
         User()

 def test_user_from_dict():
     """Test creating User from dictionary."""
     data = {
         "_id": "test-123",
         "basicInfo": {"displayName": "Test User"}
     }
     user = User(**data)

     assert user.id == "test-123"
     assert user.basic_info.display_name == "Test User"
 ```

 ## Writing Frontend Unit Tests (JavaScript/React)

 ### Basic Component Test

 ```jsx
 import { describe, it, expect, vi } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import ActionCard from './ActionCard';
 import { Settings as SettingsIcon } from '@mui/icons-material';

 describe('ActionCard', () => {
   const defaultProps = {
     icon: <SettingsIcon />,
     title: 'Test Action',
     description: 'Test description',
     buttonText: 'Click Me',
     onClick: vi.fn(),
   };

   it('renders with required props', () => {
     render(<ActionCard {...defaultProps} />);

     expect(screen.getByText('Test Action')).toBeInTheDocument();
     expect(screen.getByText('Test description')).toBeInTheDocument();
   });

   it('calls onClick when button is clicked', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();

     render(<ActionCard {...defaultProps} onClick={onClick} />);

     await user.click(screen.getByRole('button', { name: 'Click Me' }));

     expect(onClick).toHaveBeenCalledTimes(1);
   });
 });
 ```

 ### Testing with Context

 ```jsx
 import { render } from '@testing-library/react';
 import { AuthContext } from '../contexts/AuthContext';

 const renderWithAuth = (component, authValue) => {
   return render(
     <AuthContext.Provider value={authValue}>
       {component}
     </AuthContext.Provider>
   );
 };

 it('shows logout button when authenticated', () => {
   renderWithAuth(<MyComponent />, { user: { id: '123' } });

   expect(screen.getByText('Logout')).toBeInTheDocument();
 });
 ```

 ### Testing Hooks

 ```jsx
 import { renderHook, act } from '@testing-library/react';
 import { useCounter } from './useCounter';

 it('increments counter', () => {
   const { result } = renderHook(() => useCounter());

   act(() => {
     result.current.increment();
   });

   expect(result.current.count).toBe(1);
 });
 ```

 ### Mocking API Calls

 ```jsx
 import { vi } from 'vitest';

 it('fetches user data', async () => {
   global.fetch = vi.fn().mockResolvedValue({
     ok: true,
     json: async () => ({ id: '123', name: 'Test User' }),
   });

   render(<UserProfile userId="123" />);

   await screen.findByText('Test User');
   expect(global.fetch).toHaveBeenCalledWith(
     '/api/users/123',
     expect.any(Object),
   );
 });
 ```

 ## Running Unit Tests

 ### Frontend Tests

 ```bash
 cd webapp/packages/webui

 # Run tests
 pnpm test

 # Run tests in watch mode
 pnpm test -- --watch

 # Run tests with coverage
 pnpm test:coverage

 # Run tests with UI
 pnpm test:ui

 # Run specific test file
 pnpm test ActionCard.test.jsx
 ```

 ### Backend Tests

 ```bash
 cd webapp/packages/api/user-service

 # Run all unit tests
 python -m pytest tests/unit -v

 # Run specific test file
 python -m pytest tests/unit/test_user_service.py -v

 # Run specific test
 python -m pytest tests/unit/test_user_service.py::TestUserService::test_get_user -v

 # Run with coverage
 python -m pytest tests/unit --cov=. --cov-report=html

 # Run in watch mode (requires pytest-watch)
 ptw tests/unit
 ```

 ## Best Practices

 ### 1. Test One Thing Per Test

 ```python
 # Good
 def test_user_creation_sets_email():
     user = create_user(email="test@example.com")
     assert user.email == "test@example.com"

 def test_user_creation_sets_timestamp():
     user = create_user()
     assert user.created_at is not None

 # Bad
 def test_user_creation():
     user = create_user(email="test@example.com")
     assert user.email == "test@example.com"
     assert user.created_at is not None
     assert user.id is not None
 ```

 ### 2. Use Descriptive Names

 ```python
 # Good
 def test_get_user_raises_exception_when_database_unavailable():
     pass

 # Bad
 def test_get_user():
     pass
 ```

 ### 3. Follow AAA Pattern (Arrange, Act, Assert)

 ```python
 def test_add_usage_deducts_from_remaining():
     # Arrange
     user = User(_id="test-123")
     user.usage_info.spend_remaining = 100.0
     mock_db.get.return_value = user.model_dump()

     # Act
     updated_user = user_service.add_usage("test-123", 25.0)

     # Assert
     assert updated_user.usage_info.spend_remaining == 75.0
 ```

 ### 4. Mock External Dependencies

 ```python
 # Good - mocked database
 def test_save_user(user_service, mock_db):
     user = User(_id="test-123")
     user_service.save_user(user)

     mock_db.save.assert_called_once()

 # Bad - real database (integration test)
 def test_save_user():
     user = User(_id="test-123")
     db = CouchDB(url="http://localhost:5984")  # Real connection!
     user_service = UserService(db)
     user_service.save_user(user)
 ```

 ### 5. Test Edge Cases

 ```python
 def test_divide_by_zero():
     with pytest.raises(ZeroDivisionError):
         divide(10, 0)

 def test_empty_list():
     result = process_items([])
     assert result == []

 def test_null_input():
     result = process_user(None)
     assert result is None
 ```

 ### 6. Use Parametrize for Similar Tests

 ```python
 @pytest.mark.parametrize("input,expected", [
     ("hello", "Hello"),
     ("WORLD", "World"),
     ("", ""),
     ("123", "123"),
 ])
 def test_capitalize(input, expected):
     assert capitalize(input) == expected
 ```

 ## Common Patterns

 ### Testing Exceptions

 ```python
 def test_invalid_input_raises_value_error():
     with pytest.raises(ValueError, match="Invalid input"):
         process_data("invalid")
 ```

 ### Testing HTTP Errors

 ```python
 def test_not_found_returns_404():
     from fastapi import HTTPException

     with pytest.raises(HTTPException) as exc_info:
         get_user("nonexistent")

     assert exc_info.value.status_code == 404
 ```

 ### Testing Private Methods

 ```python
 def test_private_method():
     service = MyService()
     # Access private method for testing
     result = service._private_method("test")
     assert result == expected
 ```

 ## Troubleshooting

 ### Tests Hanging
 - Check for missing `await` on async functions
 - Verify mocks are properly configured
 - Look for infinite loops or blocking calls

 ### Import Errors
 - Verify `PYTHONPATH` includes project root
 - Check for circular imports
 - Ensure `__init__.py` files exist

 ### Flaky Tests
 - Remove time-based assertions
 - Ensure test isolation (no shared state)
 - Check for race conditions in async code

 ### Coverage Not Increasing
 - Verify test markers are correct
 - Check `.coveragerc` exclusions
 - Run coverage report to see uncovered lines

 ## Next Steps

 - Read [Integration Testing Guide](./integration-testing.md)
 - Review [Frontend Testing Guide](./frontend-testing.md)
 - Check [Contributing Tests](./contributing.md)
	# Unit Testing Guide

	Unit tests verify individual functions, classes, and components in isolation from external dependencies.

	## Overview

	- Framework (Frontend): Vitest + React Testing Library
	- Framework (Backend): pytest + pytest-mock
	- Location: `tests/unit/` directory
	- Mocking: Mock all external dependencies (DB, APIs, file system)
	- Coverage: Must maintain ≥95% coverage

	## Writing Backend Unit Tests (Python)

	### Basic Structure

	```python
	import pytest
	from unittest.mock import Mock, AsyncMock
	from services.user_service import UserService

	pytestmark = pytest.mark.unit # Mark as unit test


	class TestUserService:
	"""Test suite for UserService class."""

	@pytest.fixture
	def mock_db(self):
	"""Create a mock database service."""
	db = Mock()
	db.get = Mock(return_value={"id": "test-123"})
	db.save = Mock(return_value={"rev": "test-rev"})
	return db

	@pytest.fixture
	def user_service(self, mock_db):
	"""Create a UserService instance with mock database."""
	return UserService(mock_db)

	def test_get_user_existing(self, user_service, mock_db):
	"""Test getting an existing user."""
	user = user_service.get_user("test-123")

	mock_db.get.assert_called_once_with("users", "test-123")
	assert user.id == "test-123"

	def test_get_user_not_found(self, user_service, mock_db):
	"""Test handling of user not found."""
	from fastapi import HTTPException
	mock_db.get.side_effect = HTTPException(status_code=404)

	user = user_service.get_user("new-user")

	assert user.id == "new-user"
	mock_db.save.assert_called_once() # Creates new user
	```

	### Using Test Factories

	```python
	from tests.factories.user_factory import UserFactory

	def test_user_creation():
	"""Test user creation with factory data."""
	user_data = UserFactory.build()

	assert "uid" in user_data
	assert "email" in user_data
	assert user_data["email_verified"] == True

	def test_multiple_users():
	"""Create multiple test users."""
	users = UserFactory.build_batch(5)

	assert len(users) == 5
	assert all(u["email"] for u in users)
	```

	### Testing Async Functions

	```python
	import pytest

	pytestmark = pytest.mark.asyncio # Enable async support


	async def test_async_function():
	"""Test an async function."""
	result = await my_async_function()
	assert result == expected_value


	async def test_with_async_mock(mocker):
	"""Test with async mocked dependency."""
	mock_service = mocker.AsyncMock()
	mock_service.fetch_data.return_value = {"data": "test"}

	result = await function_using_service(mock_service)

	mock_service.fetch_data.assert_called_once()
	assert result["data"] == "test"
	```

	### Testing Models (Pydantic)

	```python
	import pytest
	from pydantic import ValidationError
	from models.user import User, BasicInfo

	def test_user_creation_minimal():
	"""Test creating a User with minimal required fields."""
	user = User(_id="test-123")

	assert user.id == "test-123"
	assert user.rev is None

	def test_user_validation_fails_without_id():
	"""Test that User requires an ID."""
	with pytest.raises(ValidationError):
	User()

	def test_user_from_dict():
	"""Test creating User from dictionary."""
	data = {
	"_id": "test-123",
	"basicInfo": {"displayName": "Test User"}
	}
	user = User(**data)

	assert user.id == "test-123"
	assert user.basic_info.display_name == "Test User"
	```

	## Writing Frontend Unit Tests (JavaScript/React)

	### Basic Component Test

	```jsx
	import { describe, it, expect, vi } from 'vitest';
	import { render, screen } from '@testing-library/react';
	import userEvent from '@testing-library/user-event';
	import ActionCard from './ActionCard';
	import { Settings as SettingsIcon } from '@mui/icons-material';

	describe('ActionCard', () => {
	const defaultProps = {
	icon: <SettingsIcon />,
	title: 'Test Action',
	description: 'Test description',
	buttonText: 'Click Me',
	onClick: vi.fn(),
	};

	it('renders with required props', () => {
	render(<ActionCard {...defaultProps} />);

	expect(screen.getByText('Test Action')).toBeInTheDocument();
	expect(screen.getByText('Test description')).toBeInTheDocument();
	});

	it('calls onClick when button is clicked', async () => {
	const user = userEvent.setup();
	const onClick = vi.fn();

	render(<ActionCard {...defaultProps} onClick={onClick} />);

	await user.click(screen.getByRole('button', { name: 'Click Me' }));

	expect(onClick).toHaveBeenCalledTimes(1);
	});
	});
	```

	### Testing with Context

	```jsx
	import { render } from '@testing-library/react';
	import { AuthContext } from '../contexts/AuthContext';

	const renderWithAuth = (component, authValue) => {
	return render(
	<AuthContext.Provider value={authValue}>
	{component}
	</AuthContext.Provider>
	);
	};

	it('shows logout button when authenticated', () => {
	renderWithAuth(<MyComponent />, { user: { id: '123' } });

	expect(screen.getByText('Logout')).toBeInTheDocument();
	});
	```

	### Testing Hooks

	```jsx
	import { renderHook, act } from '@testing-library/react';
	import { useCounter } from './useCounter';

	it('increments counter', () => {
	const { result } = renderHook(() => useCounter());

	act(() => {
	result.current.increment();
	});

	expect(result.current.count).toBe(1);
	});
	```

	### Mocking API Calls

	```jsx
	import { vi } from 'vitest';

	it('fetches user data', async () => {
	global.fetch = vi.fn().mockResolvedValue({
	ok: true,
	json: async () => ({ id: '123', name: 'Test User' }),
	});

	render(<UserProfile userId="123" />);

	await screen.findByText('Test User');
	expect(global.fetch).toHaveBeenCalledWith(
	'/api/users/123',
	expect.any(Object),
	);
	});
	```

	## Running Unit Tests

	### Frontend Tests

	```bash
	cd webapp/packages/webui

	# Run tests
	pnpm test

	# Run tests in watch mode
	pnpm test -- --watch

	# Run tests with coverage
	pnpm test:coverage

	# Run tests with UI
	pnpm test:ui

	# Run specific test file
	pnpm test ActionCard.test.jsx
	```

	### Backend Tests

	```bash
	cd webapp/packages/api/user-service

	# Run all unit tests
	python -m pytest tests/unit -v

	# Run specific test file
	python -m pytest tests/unit/test_user_service.py -v

	# Run specific test
	python -m pytest tests/unit/test_user_service.py::TestUserService::test_get_user -v

	# Run with coverage
	python -m pytest tests/unit --cov=. --cov-report=html

	# Run in watch mode (requires pytest-watch)
	ptw tests/unit
	```

	## Best Practices

	### 1. Test One Thing Per Test

	```python
	# Good
	def test_user_creation_sets_email():
	user = create_user(email="test@example.com")
	assert user.email == "test@example.com"

	def test_user_creation_sets_timestamp():
	user = create_user()
	assert user.created_at is not None

	# Bad
	def test_user_creation():
	user = create_user(email="test@example.com")
	assert user.email == "test@example.com"
	assert user.created_at is not None
	assert user.id is not None
	```

	### 2. Use Descriptive Names

	```python
	# Good
	def test_get_user_raises_exception_when_database_unavailable():
	pass

	# Bad
	def test_get_user():
	pass
	```

	### 3. Follow AAA Pattern (Arrange, Act, Assert)

	```python
	def test_add_usage_deducts_from_remaining():
	# Arrange
	user = User(_id="test-123")
	user.usage_info.spend_remaining = 100.0
	mock_db.get.return_value = user.model_dump()

	# Act
	updated_user = user_service.add_usage("test-123", 25.0)

	# Assert
	assert updated_user.usage_info.spend_remaining == 75.0
	```

	### 4. Mock External Dependencies

	```python
	# Good - mocked database
	def test_save_user(user_service, mock_db):
	user = User(_id="test-123")
	user_service.save_user(user)

	mock_db.save.assert_called_once()

	# Bad - real database (integration test)
	def test_save_user():
	user = User(_id="test-123")
	db = CouchDB(url="http://localhost:5984") # Real connection!
	user_service = UserService(db)
	user_service.save_user(user)
	```

	### 5. Test Edge Cases

	```python
	def test_divide_by_zero():
	with pytest.raises(ZeroDivisionError):
	divide(10, 0)

	def test_empty_list():
	result = process_items([])
	assert result == []

	def test_null_input():
	result = process_user(None)
	assert result is None
	```

	### 6. Use Parametrize for Similar Tests

	```python
	@pytest.mark.parametrize("input,expected", [
	("hello", "Hello"),
	("WORLD", "World"),
	("", ""),
	("123", "123"),
	])
	def test_capitalize(input, expected):
	assert capitalize(input) == expected
	```

	## Common Patterns

	### Testing Exceptions

	```python
	def test_invalid_input_raises_value_error():
	with pytest.raises(ValueError, match="Invalid input"):
	process_data("invalid")
	```

	### Testing HTTP Errors

	```python
	def test_not_found_returns_404():
	from fastapi import HTTPException

	with pytest.raises(HTTPException) as exc_info:
	get_user("nonexistent")

	assert exc_info.value.status_code == 404
	```

	### Testing Private Methods

	```python
	def test_private_method():
	service = MyService()
	# Access private method for testing
	result = service._private_method("test")
	assert result == expected
	```

	## Troubleshooting

	### Tests Hanging
	- Check for missing `await` on async functions
	- Verify mocks are properly configured
	- Look for infinite loops or blocking calls

	### Import Errors
	- Verify `PYTHONPATH` includes project root
	- Check for circular imports
	- Ensure `__init__.py` files exist

	### Flaky Tests
	- Remove time-based assertions
	- Ensure test isolation (no shared state)
	- Check for race conditions in async code

	### Coverage Not Increasing
	- Verify test markers are correct
	- Check `.coveragerc` exclusions
	- Run coverage report to see uncovered lines

	## Next Steps

	- Read [Integration Testing Guide](./integration-testing.md)
	- Review [Frontend Testing Guide](./frontend-testing.md)
	- Check [Contributing Tests](./contributing.md)