@martinffx/atelier 2.0.0 → 3.0.0

package/skills/python-testing/references/pytest.md

@@ -1,524 +0,0 @@
-# pytest Configuration and Patterns
-
-## Configuration (pyproject.toml)
-
-### Basic Setup
-
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-python_files = ["test_*.py", "*_test.py"]
-python_classes = ["Test*"]
-python_functions = ["test_*"]
-addopts = [
-    "-ra",                # Show summary of all test outcomes
-    "--strict-markers",   # Fail on unknown markers
-    "--strict-config",    # Fail on invalid config
-    "-v",                 # Verbose output
-]
-```
-
-### With Coverage
-
-```toml
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-addopts = [
-    "-ra",
-    "--strict-markers",
-    "--cov=src",
-    "--cov-report=term-missing",
-    "--cov-report=html",
-    "--cov-fail-under=80",
-]
-```
-
-### Markers
-
-```toml
-[tool.pytest.ini_options]
-markers = [
-    "unit: unit tests (no I/O)",
-    "integration: integration tests (with I/O)",
-    "slow: slow tests (takes >1s)",
-    "db: database tests",
-]
-```
-
-## Fixtures
-
-### Database Session
-
-```python
-import pytest
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-
-@pytest.fixture
-def test_db():
-    """In-memory test database"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-
-    SessionLocal = sessionmaker(bind=engine)
-    db = SessionLocal()
-
-    try:
-        yield db
-    finally:
-        db.close()
-```
-
-### Application Client
-
-```python
-import pytest
-from fastapi.testclient import TestClient
-
-@pytest.fixture
-def test_client():
-    """FastAPI test client"""
-    return TestClient(app)
-```
-
-### Auto-Use Fixtures for Setup/Teardown
-
-```python
-@pytest.fixture(autouse=True)
-def reset_db(test_db):
-    """Reset database before each test"""
-    Base.metadata.drop_all(bind=test_db.bind)
-    Base.metadata.create_all(bind=test_db.bind)
-```
-
-### Fixture Scope
-
-```python
-@pytest.fixture(scope="function")  # Default: per test
-def data():
-    ...
-
-@pytest.fixture(scope="module")    # Per test file
-def client():
-    ...
-
-@pytest.fixture(scope="session")   # For entire test run
-def config():
-    ...
-```
-
-### Parametrized Fixtures
-
-```python
-@pytest.fixture(params=[
-    {"name": "Alice", "age": 25},
-    {"name": "Bob", "age": 30},
-    {"name": "Charlie", "age": 35},
-])
-def user_data(request):
-    """Fixture provides multiple inputs"""
-    return request.param
-
-def test_user_creation(user_data):
-    """Runs 3 times with different data"""
-    user = User(**user_data)
-    assert user.name is not None
-```
-
-### Fixture Dependencies
-
-```python
-@pytest.fixture
-def test_db():
-    """Database fixture"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    SessionLocal = sessionmaker(bind=engine)
-    return SessionLocal()
-
-@pytest.fixture
-def user_repository(test_db):
-    """Repository depends on database"""
-    return UserRepository(test_db)
-
-def test_repository_save(user_repository):
-    """Test uses repository (which uses database)"""
-    user = User(id=1, name="Alice")
-    user_repository.save(user)
-    assert user_repository.get(1) is not None
-```
-
-## Running Tests
-
-### Basic Commands
-
-```bash
-# Run all tests
-pytest
-
-# Run specific file
-pytest tests/test_entities.py
-
-# Run specific test
-pytest tests/test_entities.py::test_user_creation
-
-# Run with pattern
-pytest tests/test_*.py
-
-# Verbose output
-pytest -v
-
-# Very verbose (shows parameters)
-pytest -vv
-```
-
-### Filtering Tests
-
-```bash
-# Stop on first failure
-pytest -x
-
-# Stop after N failures
-pytest --maxfail=3
-
-# Show print statements
-pytest -s
-
-# Show local variables on failure
-pytest -l
-
-# Show durations of slowest tests
-pytest --durations=10
-```
-
-### Markers
-
-```bash
-# Run only unit tests
-pytest -m unit
-
-# Skip slow tests
-pytest -m "not slow"
-
-# Run integration tests
-pytest -m integration
-
-# Run tests matching pattern
-pytest -m "unit or integration"
-```
-
-### Coverage
-
-```bash
-# Generate coverage report
-pytest --cov=src
-
-# Show missing lines
-pytest --cov=src --cov-report=term-missing
-
-# Generate HTML report
-pytest --cov=src --cov-report=html
-# Open htmlcov/index.html in browser
-
-# Fail if below threshold
-pytest --cov=src --cov-fail-under=80
-```
-
-## Parametrize
-
-### Multiple Inputs
-
-```python
-@pytest.mark.parametrize("input,expected", [
-    (1, 2),
-    (2, 4),
-    (3, 6),
-    (4, 8),
-])
-def test_double(input, expected):
-    assert double(input) == expected
-```
-
-### Multiple Parameters
-
-```python
-@pytest.mark.parametrize("x,y,expected", [
-    (1, 2, 3),
-    (2, 3, 5),
-    (5, 5, 10),
-])
-def test_add(x, y, expected):
-    assert add(x, y) == expected
-```
-
-### Parametrize Multiple Test Values
-
-```python
-@pytest.mark.parametrize("value", [
-    "alice@example.com",
-    "bob@example.com",
-    "charlie@example.com",
-])
-def test_valid_email(value):
-    assert is_valid_email(value)
-```
-
-### Combining Parametrize
-
-```python
-@pytest.mark.parametrize("user_type", ["admin", "user", "guest"])
-@pytest.mark.parametrize("resource", ["posts", "comments", "users"])
-def test_permissions(user_type, resource):
-    """Tests all combinations (3×3 = 9 tests)"""
-    has_access = check_access(user_type, resource)
-    assert has_access is not None
-```
-
-## Markers
-
-### Built-in Markers
-
-```python
-@pytest.mark.skip
-def test_not_ready():
-    """Skip this test"""
-    ...
-
-@pytest.mark.skip(reason="Not implemented yet")
-def test_future():
-    """Skip with reason"""
-    ...
-
-@pytest.mark.skipif(sys.version_info < (3, 10), reason="Requires 3.10+")
-def test_new_syntax():
-    """Skip conditionally"""
-    ...
-
-@pytest.mark.xfail
-def test_known_bug():
-    """Mark as expected to fail"""
-    ...
-```
-
-### Custom Markers
-
-```python
-@pytest.mark.unit
-def test_entity():
-    ...
-
-@pytest.mark.integration
-def test_with_database():
-    ...
-
-@pytest.mark.slow
-def test_expensive_computation():
-    ...
-
-@pytest.mark.db
-def test_with_db():
-    ...
-```
-
-## Test Organization
-
-### Structure by Layer
-
-```
-tests/
-├── unit/
-│   ├── test_entities.py         # Entity tests
-│   ├── test_services.py         # Service tests (mocked)
-│   └── test_value_objects.py    # Value object tests
-├── integration/
-│   ├── test_repositories.py     # Repository tests (with DB)
-│   └── test_endpoints.py        # Router tests (with client)
-└── fixtures.py                  # Shared fixtures
-```
-
-### conftest.py for Shared Fixtures
-
-```python
-# tests/conftest.py
-import pytest
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-from fastapi.testclient import TestClient
-
-@pytest.fixture
-def test_db():
-    """Shared database fixture"""
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    SessionLocal = sessionmaker(bind=engine)
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-
-@pytest.fixture
-def test_client():
-    """Shared test client"""
-    return TestClient(app)
-
-# tests/test_entities.py
-def test_product_creation(test_db):
-    """Uses fixture from conftest.py"""
-    ...
-```
-
-### Naming Conventions
-
-```python
-# File names
-test_entities.py       # Tests for entities module
-test_create_product.py # Tests for specific feature
-
-# Test class (optional grouping)
-class TestProduct:
-    def test_creation(self):
-        ...
-
-    def test_validation(self):
-        ...
-
-# Test function names
-def test_product_creation():        # What is tested
-def test_product_with_discount():   # Behavior variant
-def test_product_raises_on_invalid_price():  # Error case
-```
-
-## Assertions and Context
-
-### assert with Message
-
-```python
-def test_with_message():
-    result = calculate()
-    assert result == 42, f"Expected 42 but got {result}"
-```
-
-### pytest.raises
-
-```python
-def test_raises_error():
-    with pytest.raises(ValueError):
-        invalid_operation()
-
-def test_raises_with_match():
-    with pytest.raises(ValueError, match="Invalid price"):
-        Product(price=-10)
-
-def test_raises_with_check():
-    with pytest.raises(ValueError) as exc_info:
-        invalid_operation()
-    assert "specific message" in str(exc_info.value)
-```
-
-### pytest.approx for Floats
-
-```python
-def test_float_calculation():
-    result = expensive_calculation()
-    # Avoid exact equality with floats
-    assert result == pytest.approx(3.14159, abs=0.0001)
-```
-
-### Comparing Collections
-
-```python
-def test_lists():
-    result = get_items()
-    assert result == [1, 2, 3]
-    assert 2 in result
-    assert len(result) == 3
-
-def test_dicts():
-    result = get_data()
-    assert result == {"name": "Alice", "age": 25}
-    assert result["name"] == "Alice"
-    assert "email" not in result
-```
-
-## Debugging Failed Tests
-
-### Print Debugging
-
-```bash
-# Show print statements
-pytest -s
-
-# Show print + traceback
-pytest -s -vv
-
-# Show local variables
-pytest -l
-
-# Full diff for collections
-pytest -vv --tb=short
-```
-
-### Using pdb
-
-```python
-def test_with_debugger():
-    result = complex_operation()
-    # Drop into debugger on failure
-    import pdb; pdb.set_trace()
-    assert result == expected
-```
-
-### Test Reports
-
-```bash
-# Generate JUnit XML (for CI)
-pytest --junit-xml=report.xml
-
-# Generate JSON report
-pytest --json-report --json-report-file=report.json
-
-# Generate HTML report
-pytest --html=report.html
-```
-
-## Performance Optimization
-
-### Profile Test Execution
-
-```bash
-# Show slowest tests
-pytest --durations=10
-
-# Show all tests sorted by duration
-pytest --durations=0
-```
-
-### Parallelize Tests
-
-```bash
-# Install pytest-xdist
-pip install pytest-xdist
-
-# Run tests in parallel (use N workers)
-pytest -n auto
-pytest -n 4
-```
-
-### Fixture Optimization
-
-```python
-# SLOW: Creates database for every test
-@pytest.fixture(scope="function")
-def test_db():
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    ...
-
-# FAST: Creates once per session (if tests don't modify schema)
-@pytest.fixture(scope="session")
-def test_db():
-    engine = create_engine("sqlite:///:memory:")
-    Base.metadata.create_all(engine)
-    ...
-```