ljwx-children/tests

Testing Guide

Comprehensive testing framework for Gold Template project.

Test Structure

tests/
├── unit/               # Fast, isolated unit tests
│   ├── test_models.py          # Database model tests
│   └── test_api_endpoints.py   # API endpoint tests
├── integration/        # Integration tests with dependencies
│   ├── test_database.py        # Database integration tests
│   └── test_api_integration.py # Full API workflow tests
├── e2e/               # End-to-end tests
│   ├── test_auth_flow.py       # Authentication flows
│   └── test_crud_operations.py # CRUD workflows
├── conftest.py        # Shared fixtures
├── factories.py       # Test data factories
└── README.md         # This file

Running Tests

All Tests

pytest

By Category

# Unit tests only (fast)
pytest tests/unit/ -v

# Integration tests
pytest tests/integration/ -v

# E2E tests (requires running app)
pytest tests/e2e/ -v -m e2e

By Marker

# Run only async tests
pytest -m asyncio

# Skip slow tests
pytest -m "not slow"

# Run integration tests
pytest -m integration

Coverage

Generate Coverage Report

# Terminal report
pytest --cov=backend --cov-report=term-missing

# HTML report (opens in browser)
pytest --cov=backend --cov-report=html
open htmlcov/index.html

# XML report (for CI)
pytest --cov=backend --cov-report=xml

Coverage Goals

• Overall: >80%
• Critical paths: >95%
• New code: 100%

Test Fixtures

Database Fixtures

• test_engine: In-memory SQLite database engine
• test_session: Async database session
• test_client: FastAPI test client with DB override

Data Fixtures

• sample_user_data: Single user data
• sample_item_data: Single item data
• multiple_users_data: List of users

Test Factories

Use factories to generate realistic test data:

from tests.factories import create_user, create_item

# Create single user with defaults
user = create_user()

# Create user with custom values
user = create_user(username="custom_user", email="[email protected]")

# Create multiple users
users = create_users(10)

E2E Tests

E2E tests require:

1. Running application instance
2. Playwright installation

Setup E2E Tests

# Install Playwright
pip install playwright
playwright install

# Start application
python -m uvicorn backend.main:app --reload

# Run E2E tests
pytest tests/e2e/ -v

CI Integration

Tests run automatically in CI on:

• Every push to main/develop
• Every pull request
• Manual workflow dispatch

CI Configuration

See .github/workflows/ci.yml for:

• Parallel test execution
• Coverage reporting
• Test result uploads

Best Practices

Writing Unit Tests

import pytest

class TestUserModel:
    @pytest.mark.asyncio
    async def test_create_user(self, test_session):
        # Arrange
        user_data = create_user()

        # Act
        user = User(**user_data)
        test_session.add(user)
        await test_session.commit()

        # Assert
        assert user.id is not None

Writing Integration Tests

@pytest.mark.asyncio
async def test_user_crud_workflow(test_client):
    # Create
    response = await test_client.post("/users/", json=user_data)
    assert response.status_code == 201

    # Read
    user_id = response.json()["id"]
    response = await test_client.get(f"/users/{user_id}")
    assert response.status_code == 200

Test Naming

• Use descriptive names: test_create_user_with_valid_data
• Follow pattern: test_<action>_<scenario>_<expected_result>
• Group related tests in classes

Test Organization

• One test file per module
• Group related tests in classes
• Use descriptive class names: TestUserAuthentication

Troubleshooting

Tests Fail Due to Database Lock

# Remove test database
rm test.db

# Run tests again
pytest

Async Tests Not Running

# Ensure pytest-asyncio is installed
pip install pytest-asyncio

# Check pytest.ini has asyncio_mode = auto

Coverage Not Showing

# Ensure pytest-cov is installed
pip install pytest-cov

# Check .coveragerc configuration

E2E Tests Failing

# Ensure application is running
lsof -i :8000

# Reinstall Playwright browsers
playwright install --force

Performance

Test Execution Time

• Unit tests: <10 seconds
• Integration tests: <30 seconds
• E2E tests: <2 minutes
• Full suite: <5 minutes

Optimization Tips

• Use pytest-xdist for parallel execution
• Mock external dependencies
• Use in-memory database for tests
• Cache expensive fixtures

Resources

• Pytest Documentation
• Pytest-Asyncio
• Playwright for Python
• Testing FastAPI