python-skills 1.0.0__py3-none-any.whl

skills/testing/fixtures_mocks.md

@@ -0,0 +1,203 @@
+# Testing: Fixtures and Mocks
+
+**Purpose**: Effective test fixtures and mocking strategies.
+
+**When to use**: Writing tests that need setup, dependencies, or isolation.
+
+---
+
+## Core Rules
+
+### Fixture Principles
+- **Scope appropriately**: `function` (default), `class`, `module`, `session`
+- **Single responsibility**: Each fixture does one thing
+- **Explicit dependencies**: Fixtures request what they need
+- **Cleanup**: Use `yield` for teardown
+
+### Fixture Patterns
+
+```python
+# conftest.py
+
+# Session-scoped expensive resource
+@pytest.fixture(scope="session")
+def database():
+    db = create_test_database()
+    yield db
+    db.drop()
+
+# Function-scoped clean state
+@pytest.fixture
+def clean_db(database):
+    database.truncate_all()
+    yield database
+    database.truncate_all()
+
+# Factory fixture
+@pytest.fixture
+def user_factory(clean_db):
+    def _create(email: str = "test@test.com", **kwargs):
+        return UserService(clean_db).create(email, **kwargs)
+    return _create
+
+# Parametrized fixture
+@pytest.fixture(params=["sqlite", "postgresql"])
+def db_engine(request):
+    if request.param == "sqlite":
+        return create_sqlite_engine()
+    return create_pg_engine()
+```
+
+### Mocking Guidelines
+
+```python
+# Mock at the boundary (where your code calls external code)
+# NOT deep in the call stack
+
+# GOOD — mock the client your code uses
+@patch("mypackage.services.payment.StripeClient")
+def test_charge(mock_stripe, payment_service):
+    mock_stripe.return_value.charge.return_value = ChargeResult(success=True)
+    result = payment_service.charge(100, "token")
+    assert result.success
+
+# BAD — mock internal implementation
+@patch("mypackage.services.payment.calculate_fee")
+def test_charge_bad(mock_fee, payment_service):
+    ...
+```
+
+### Mock Types
+```python
+from unittest.mock import Mock, MagicMock, AsyncMock, PropertyMock
+
+# Sync mock
+mock = Mock()
+mock.method.return_value = "value"
+mock.method.side_effect = Exception("error")
+mock.property = PropertyMock(return_value="value")
+
+# Async mock
+async_mock = AsyncMock()
+async_mock.async_method.return_value = "value"
+async_mock.async_method.side_effect = [val1, val2, Exception("error")]
+
+# Spec (prevents typos)
+mock = Mock(spec=RealClass)
+mock.real_method()  # OK
+mock.typo_method()  # AttributeError!
+
+# Autospec (signature checking)
+mock = Mock(autospec=RealClass)
+mock.real_method(1, 2)  # OK
+mock.real_method()      # TypeError: missing args
+```
+
+### Test Data Builders
+```python
+# For complex test objects
+class UserBuilder:
+    def __init__(self):
+        self._email = "test@test.com"
+        self._name = "Test User"
+        self._active = True
+        self._roles = []
+    
+    def with_email(self, email: str) -> "UserBuilder":
+        self._email = email
+        return self
+    
+    def with_name(self, name: str) -> "UserBuilder":
+        self._name = name
+        return self
+    
+    def inactive(self) -> "UserBuilder":
+        self._active = False
+        return self
+    
+    def with_roles(self, *roles) -> "UserBuilder":
+        self._roles = list(roles)
+        return self
+    
+    def build(self) -> User:
+        return User(
+            email=self._email,
+            name=self._name,
+            active=self._active,
+            roles=self._roles,
+        )
+
+# Usage
+def test_admin_user(user_factory):
+    admin = UserBuilder().with_roles("admin").build()
+    assert admin.has_permission("admin")
+```
+
+---
+
+## Decision Rules
+
+| Need | Fixture/Mock Pattern |
+|------|---------------------|
+| Shared expensive resource | `scope="session"` fixture |
+| Clean state per test | Function fixture with cleanup |
+| Test data variations | Factory fixture or builder |
+| External service | Mock at boundary |
+| Time-dependent | `freezegun` / mock `time.time` |
+| Random-dependent | Mock `random` / `secrets` |
+| Multiple implementations | Parametrized fixture |
+
+---
+
+## Preferred Patterns
+
+```python
+# Conftest organization
+# tests/conftest.py — project-wide
+# tests/unit/conftest.py — unit-specific
+# tests/integration/conftest.py — integration-specific
+
+# Fixture naming
+@pytest.fixture
+def user_service() -> UserService:  # Return type hint
+    ...
+
+# Async fixtures
+@pytest.fixture
+async def async_client() -> AsyncClient:
+    client = AsyncClient()
+    yield client
+    await client.aclose()
+
+# Mock fixture
+@pytest.fixture
+def mock_email_service() -> Mock:
+    return Mock(spec=EmailService)
+```
+
+---
+
+## Avoid
+
+- Fixtures with side effects (no cleanup)
+- Over-mocking (mock everything, test nothing)
+- Mocking standard library (mock `requests`, not `json`)
+- Fixtures that depend on test order
+- Complex fixture chains (>3 levels)
+
+---
+
+## Validation Considerations
+
+- Fixture setup/teardown time (profile with `--durations=10`)
+- Mock call verification (`assert_called_once_with`)
+- No real network calls in unit tests (use `pytest-mock` + `requests-mock`)
+
+---
+
+## Related Skills
+
+- `testing/organization.md`
+- `testing/parameterized.md`
+- `testing/async_tests.md`
+- `generation/error_handling.md`

skills/testing/organization.md

@@ -0,0 +1,205 @@
+# Testing: Organization
+
+**Purpose**: Structuring test suites for maintainability and speed.
+
+**When to use**: Setting up or reorganizing test structure.
+
+---
+
+## Core Rules
+
+### Directory Structure
+```
+tests/
+├── conftest.py                 # Root fixtures
+├── pytest.ini                  # Config (or pyproject.toml)
+├── unit/                       # Fast, isolated
+│   ├── conftest.py
+│   ├── test_models.py
+│   ├── test_services.py
+│   └── test_utils.py
+├── integration/                # Real dependencies
+│   ├── conftest.py
+│   ├── test_database.py
+│   ├── test_api.py
+│   └── test_external.py
+├── e2e/                        # Full stack (optional)
+│   ├── conftest.py
+│   └── test_flows.py
+├── performance/                # Benchmarks (optional)
+│   └── test_benchmarks.py
+├── fixtures/                   # Shared test data
+│   ├── sample_users.json
+│   └── sample_orders.json
+└── helpers/                    # Test utilities
+    ├── __init__.py
+    ├── builders.py
+    └── matchers.py
+```
+
+### Naming Conventions
+```
+test_<module>.py                # Module tests
+test_<class>.py                 # Class tests
+test_<function>_<scenario>.py   # Specific scenario
+Test<ClassName>                 # Test class
+test_<function>_<condition>     # Test function
+```
+
+### Test Class Organization
+```python
+class TestUserService:
+    """Tests for UserService."""
+    
+    class TestCreateUser:
+        """Tests for create_user method."""
+        
+        def test_creates_user_with_valid_data(self):
+            ...
+        
+        def test_raises_on_duplicate_email(self):
+            ...
+        
+        def test_hashes_password(self):
+            ...
+    
+    class TestGetUser:
+        """Tests for get_user method."""
+        
+        def test_returns_user_when_exists(self):
+            ...
+        
+        def test_returns_none_when_not_found(self):
+            ...
+```
+
+### Marks for Categorization
+```python
+# pytest.ini
+[tool.pytest.ini_options]
+markers = [
+    "unit: Fast, isolated tests",
+    "integration: Tests with real dependencies",
+    "e2e: Full system tests",
+    "slow: Takes >1s",
+    "requires_db: Needs database",
+    "requires_network: Needs external API",
+    "regression: Bug fix verification",
+    "security: Security-related tests",
+]
+
+# Usage
+@pytest.mark.unit
+def test_unit():
+    ...
+
+@pytest.mark.integration
+@pytest.mark.requires_db
+def test_with_db():
+    ...
+
+# Run subsets
+# pytest -m unit
+# pytest -m "integration and not slow"
+# pytest -m "not e2e"
+```
+
+### Configuration
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers --strict-config --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*", "*/__main__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+```
+
+---
+
+## Decision Rules
+
+| Test Type | Location | Markers | Speed Target |
+|-----------|----------|---------|--------------|
+| Unit | `tests/unit/` | `unit` | <100ms |
+| Integration | `tests/integration/` | `integration`, `requires_db` | <1s |
+| E2E | `tests/e2e/` | `e2e` | <30s |
+| Regression | `tests/regression/` | `regression` | Varies |
+
+---
+
+## Preferred Patterns
+
+```python
+# Shared test utilities
+# tests/helpers/builders.py
+class UserBuilder:
+    def __init__(self):
+        self.data = {"email": "test@test.com", "name": "Test"}
+    
+    def with_email(self, email):
+        self.data["email"] = email
+        return self
+    
+    def build(self):
+        return User(**self.data)
+
+# tests/helpers/matchers.py
+def assert_user_equal(actual: User, expected: User):
+    assert actual.id == expected.id
+    assert actual.email == expected.email
+    assert actual.name == expected.name
+    # Don't compare timestamps (flaky)
+
+# Custom assertions
+def assert_validation_error(exc_info, field: str, message_contains: str):
+    assert exc_info.type is ValidationError
+    assert exc_info.value.field == field
+    assert message_contains in str(exc_info.value)
+```
+
+---
+
+## Avoid
+
+- All tests in one directory
+- No markers (can't run subsets)
+- Mixed unit/integration in same file
+- Slow tests in unit suite
+- Test order dependencies
+- Duplicate fixtures across directories
+
+---
+
+## Validation Considerations
+
+- `pytest --collect-only | head -20` shows structure
+- `pytest --durations=10` shows slowest tests
+- Coverage targets per test type
+- CI runs unit on every PR, integration nightly
+
+---
+
+## Related Skills
+
+- `testing/fixtures_mocks.md`
+- `testing/parameterized.md`
+- `engineering/virtual_environments.md`

skills/testing/parameterized.md

@@ -0,0 +1,174 @@
+# Testing: Parameterized Tests
+
+**Purpose**: Run same test logic with multiple inputs.
+
+**When to use**: Testing multiple cases, edge cases, boundary values.
+
+---
+
+## Core Rules
+
+### Basic Parametrization
+```python
+import pytest
+
+@pytest.mark.parametrize("input,expected", [
+    (1, 2),
+    (2, 4),
+    (3, 6),
+    (0, 0),
+    (-1, -2),
+])
+def test_double(input: int, expected: int):
+    assert double(input) == expected
+```
+
+### Multiple Parameters
+```python
+@pytest.mark.parametrize("a,b,expected", [
+    (1, 2, 3),
+    (0, 0, 0),
+    (-1, 1, 0),
+    (100, 200, 300),
+])
+def test_add(a: int, b: int, expected: int):
+    assert add(a, b) == expected
+```
+
+### Parametrized Fixtures
+```python
+@pytest.fixture(params=[1, 2, 3, 10, 100])
+def number(request):
+    return request.param
+
+def test_positive(number: int):
+    assert number > 0
+
+# Combined with test parametrization
+@pytest.mark.parametrize("multiplier", [2, 3, 10])
+def test_multiply(number: int, multiplier: int):
+    assert number * multiplier > 0
+```
+
+### Parametrizing with IDs
+```python
+@pytest.mark.parametrize("email,valid", [
+    pytest.param("test@example.com", True, id="valid-standard"),
+    pytest.param("user+tag@domain.org", True, id="valid-plus-tag"),
+    pytest.param("invalid", False, id="invalid-no-at"),
+    pytest.param("@domain.com", False, id="invalid-no-local"),
+    pytest.param("user@", False, id="invalid-no-domain"),
+], ids=lambda x: x[1] and "valid" or "invalid")
+def test_email_validation(email: str, valid: bool):
+    assert is_valid_email(email) == valid
+```
+
+### Parametrizing Classes
+```python
+@pytest.mark.parametrize("storage_cls", [InMemoryStorage, RedisStorage, FileStorage])
+class TestStorage:
+    def test_save_and_load(self, storage_cls):
+        storage = storage_cls()
+        storage.save("key", "value")
+        assert storage.load("key") == "value"
+    
+    def test_delete(self, storage_cls):
+        storage = storage_cls()
+        storage.save("key", "value")
+        storage.delete("key")
+        assert storage.load("key") is None
+```
+
+### Dynamic Parametrization
+```python
+def pytest_generate_tests(metafunc):
+    """Hook for dynamic parametrization."""
+    if "test_file" in metafunc.fixturenames:
+        test_files = list(Path("test_data").glob("*.json"))
+        metafunc.parametrize("test_file", test_files, ids=lambda p: p.stem)
+
+def test_with_file(test_file: Path):
+    data = json.loads(test_file.read_text())
+    assert process(data) == data["expected"]
+```
+
+### Cartesian Product (Multiple Decorators)
+```python
+@pytest.mark.parametrize("os", ["linux", "windows", "macos"])
+@pytest.mark.parametrize("python", ["3.10", "3.11", "3.12"])
+def test_compatibility(os: str, python: str):
+    # Runs 9 combinations
+    assert is_compatible(os, python)
+```
+
+---
+
+## Decision Rules
+
+| Situation | Pattern |
+|-----------|---------|
+| Few cases (<10) | Inline parametrize |
+| Many cases / data-driven | External data + `pytest_generate_tests` |
+| Cross-product | Multiple `@parametrize` |
+| Fixture variation | Parametrized fixture |
+| Different implementations | Parametrize class |
+
+---
+
+## Preferred Patterns
+
+```python
+# Boundary value testing
+@pytest.mark.parametrize("value", [
+    0,           # Minimum
+    1,           # Just above min
+    100,         # Typical
+    999,         # Just below max
+    1000,        # Maximum
+    1001,        # Just above max (invalid)
+])
+def test_range_validation(value: int):
+    if 0 <= value <= 1000:
+        assert validate_range(value) == value
+    else:
+        with pytest.raises(ValidationError):
+            validate_range(value)
+
+# Error case parametrization
+ERROR_CASES = [
+    (ValidationError, "empty", {}),
+    (ValidationError, "missing_field", {"name": "test"}),
+    (ConflictError, "duplicate", {"name": "test", "email": "a@b.c"}),
+]
+
+@pytest.mark.parametrize("error_type,case_name,input_data", ERROR_CASES)
+def test_create_user_errors(error_type, case_name, input_data):
+    with pytest.raises(error_type):
+        create_user(**input_data)
+```
+
+---
+
+## Avoid
+
+- Too many combinations (exponential explosion)
+- Parametrizing unrelated tests together
+- Complex logic in parametrization (use fixtures instead)
+- Missing `ids` for readability in output
+
+---
+
+## Validation Considerations
+
+- `pytest --collect-only` shows all generated tests
+- `pytest -v` shows parametrized test names
+- `pytest -k "valid"` filters by id/name
+- Duration tracking for large parametrized suites
+
+---
+
+## Related Skills
+
+- `testing/organization.md`
+- `testing/fixtures_mocks.md`
+- `testing/edge_cases.md`