fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/testing/pytest/__init__.py

@@ -0,0 +1,38 @@
+"""Pytest integration for confiture migration testing.
+
+This module provides both the pytest plugin and the migration_test decorator.
+
+Usage:
+    # Enable the plugin in conftest.py
+    pytest_plugins = ["confiture.testing.pytest"]
+
+    # Use the decorator for migration-specific tests
+    from confiture.testing.pytest import migration_test
+
+    @migration_test("003_move_catalog_tables")
+    class TestMigration003:
+        def test_up_preserves_data(self, confiture_sandbox, migration):
+            migration.up()
+            assert confiture_sandbox.validator.constraints_valid()
+"""
+
+# Re-export from the plugin module
+from confiture.testing.pytest_plugin import (
+    confiture_db_url,
+    confiture_migrations_dir,
+    confiture_sandbox,
+    confiture_snapshotter,
+    confiture_validator,
+    migration_test,
+)
+
+__all__ = [
+    # Decorator
+    "migration_test",
+    # Fixtures (for documentation, actual fixtures registered via plugin)
+    "confiture_db_url",
+    "confiture_migrations_dir",
+    "confiture_sandbox",
+    "confiture_validator",
+    "confiture_snapshotter",
+]

confiture/testing/pytest_plugin.py

@@ -0,0 +1,190 @@
+"""Pytest plugin for confiture migration testing.
+
+This module provides pytest fixtures for migration testing with automatic
+transaction rollback.
+
+Usage:
+    # In conftest.py
+    pytest_plugins = ["confiture.testing.pytest"]
+
+    # Or enable automatically when confiture is installed (via entry point)
+
+Available fixtures:
+    - confiture_db_url: Database URL (override to customize)
+    - confiture_migrations_dir: Migrations directory (override to customize)
+    - confiture_sandbox: MigrationSandbox with automatic rollback
+    - confiture_validator: DataValidator from sandbox
+    - confiture_snapshotter: SchemaSnapshotter from sandbox
+
+Example test file:
+    >>> def test_migration(confiture_sandbox):
+    ...     migration = confiture_sandbox.load("003_move_tables")
+    ...     migration.up()
+    ...     assert confiture_sandbox.validator.constraints_valid()
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Generator
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from confiture.testing.fixtures.data_validator import DataValidator
+    from confiture.testing.fixtures.schema_snapshotter import SchemaSnapshotter
+    from confiture.testing.sandbox import MigrationSandbox
+
+
+@pytest.fixture
+def confiture_db_url() -> str:
+    """Provide database URL for migration testing.
+
+    Override this fixture to use a different database:
+
+        @pytest.fixture
+        def confiture_db_url():
+            return "postgresql://localhost/my_test_db"
+
+    Environment variable CONFITURE_TEST_DB_URL takes precedence.
+
+    Returns:
+        Database connection URL
+    """
+    return os.getenv(
+        "CONFITURE_TEST_DB_URL",
+        "postgresql://localhost/confiture_test",
+    )
+
+
+@pytest.fixture
+def confiture_migrations_dir() -> Path:
+    """Provide migrations directory for testing.
+
+    Override this fixture to use a custom migrations directory:
+
+        @pytest.fixture
+        def confiture_migrations_dir():
+            return Path("custom/migrations")
+
+    Returns:
+        Path to migrations directory
+    """
+    return Path("db/migrations")
+
+
+@pytest.fixture
+def confiture_sandbox(
+    confiture_db_url: str,
+    confiture_migrations_dir: Path,
+) -> Generator[MigrationSandbox, None, None]:
+    """Provide a migration sandbox with automatic rollback.
+
+    Creates a MigrationSandbox that automatically rolls back all changes
+    at the end of the test.
+
+    Usage:
+        def test_migration(confiture_sandbox):
+            migration = confiture_sandbox.load("003_move_tables")
+            baseline = confiture_sandbox.capture_baseline()
+            migration.up()
+            confiture_sandbox.assert_no_data_loss(baseline)
+
+    Yields:
+        MigrationSandbox instance
+
+    Note:
+        This fixture requires a running PostgreSQL database.
+        Tests will be skipped if the database is not available.
+    """
+    from confiture.testing.sandbox import MigrationSandbox
+
+    try:
+        with MigrationSandbox(
+            db_url=confiture_db_url,
+            migrations_dir=confiture_migrations_dir,
+        ) as sandbox:
+            yield sandbox
+    except Exception as e:
+        pytest.skip(f"Database not available: {e}")
+
+
+@pytest.fixture
+def confiture_validator(confiture_sandbox: MigrationSandbox) -> DataValidator:
+    """Provide data validator from sandbox.
+
+    Convenience fixture that extracts the validator from the sandbox.
+
+    Usage:
+        def test_constraints(confiture_sandbox, confiture_validator):
+            confiture_sandbox.load("003").up()
+            assert confiture_validator.constraints_valid()
+
+    Returns:
+        DataValidator instance
+    """
+    return confiture_sandbox.validator
+
+
+@pytest.fixture
+def confiture_snapshotter(confiture_sandbox: MigrationSandbox) -> SchemaSnapshotter:
+    """Provide schema snapshotter from sandbox.
+
+    Convenience fixture that extracts the snapshotter from the sandbox.
+
+    Usage:
+        def test_schema_changes(confiture_sandbox, confiture_snapshotter):
+            before = confiture_snapshotter.capture()
+            confiture_sandbox.load("003").up()
+            after = confiture_snapshotter.capture()
+            changes = confiture_snapshotter.compare(before, after)
+            assert "products" in changes["tables_added"]
+
+    Returns:
+        SchemaSnapshotter instance
+    """
+    return confiture_sandbox.snapshotter
+
+
+def migration_test(migration_name: str):
+    """Decorator to inject migration fixture for specific migration.
+
+    Use this decorator on test classes to automatically inject a `migration`
+    fixture that loads the specified migration.
+
+    Usage:
+        from confiture.testing.pytest import migration_test
+
+        @migration_test("003_move_catalog_tables")
+        class TestMigration003:
+            def test_up_preserves_data(self, confiture_sandbox, migration):
+                baseline = confiture_sandbox.capture_baseline()
+                migration.up()
+                confiture_sandbox.assert_no_data_loss(baseline)
+
+            def test_down_reverses_changes(self, confiture_sandbox, migration):
+                migration.up()
+                migration.down()
+                # Assert schema is back to original state
+
+    Args:
+        migration_name: Name of the migration to load (e.g., "003_move_catalog_tables")
+
+    Returns:
+        Class decorator that adds migration fixture
+    """
+
+    def decorator(cls):
+        # Create a migration fixture for this specific test class
+        @pytest.fixture
+        def migration(self, confiture_sandbox: MigrationSandbox):  # noqa: ARG001
+            """Migration fixture injected by @migration_test decorator."""
+            return confiture_sandbox.load(migration_name)
+
+        # Add the fixture to the class
+        cls.migration = migration
+        return cls
+
+    return decorator

confiture/testing/sandbox.py

@@ -0,0 +1,304 @@
+"""Migration testing sandbox.
+
+Provides an isolated environment for testing migrations with automatic
+rollback and pre-loaded testing utilities.
+
+Example:
+    >>> from confiture.testing import MigrationSandbox
+    >>>
+    >>> with MigrationSandbox(db_url) as sandbox:
+    ...     migration = sandbox.load("003_move_tables")
+    ...     migration.up()
+    ...     assert sandbox.validator.constraints_valid()
+    ...
+    >>> # Auto-rollback at end of context
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import psycopg
+
+if TYPE_CHECKING:
+    from confiture.models.migration import Migration
+    from confiture.testing.fixtures.data_validator import DataBaseline, DataValidator
+    from confiture.testing.fixtures.schema_snapshotter import SchemaSnapshotter
+
+
+class MigrationSandbox:
+    """Test migrations in isolation with automatic rollback.
+
+    A context manager that provides a sandboxed environment for migration testing:
+    - Automatic transaction management (rollback on exit)
+    - Pre-loaded testing utilities (validator, snapshotter)
+    - Migration loading via load_migration()
+
+    The sandbox can work in two modes:
+    1. **URL mode**: Creates a new connection, uses transaction with rollback
+    2. **Connection mode**: Uses existing connection, creates a savepoint for rollback
+
+    Attributes:
+        connection: The database connection being used
+        validator: DataValidator for data integrity checks
+        snapshotter: SchemaSnapshotter for schema comparison
+        migrations_dir: Directory where migrations are located
+
+    Example with URL:
+        >>> with MigrationSandbox("postgresql://localhost/test_db") as sandbox:
+        ...     migration = sandbox.load("003_move_tables")
+        ...     baseline = sandbox.capture_baseline()
+        ...     migration.up()
+        ...     assert sandbox.validator.no_data_loss(baseline)
+
+    Example with existing connection:
+        >>> with MigrationSandbox(connection=existing_conn) as sandbox:
+        ...     # Uses savepoint instead of full transaction
+        ...     migration = sandbox.load("003")
+        ...     migration.up()
+
+    Example with custom migrations directory:
+        >>> with MigrationSandbox(db_url, migrations_dir=Path("/custom/migrations")) as sandbox:
+        ...     migration = sandbox.load("001_initial")
+    """
+
+    def __init__(
+        self,
+        db_url: str | None = None,
+        *,
+        connection: psycopg.Connection | None = None,
+        migrations_dir: Path | None = None,
+    ):
+        """Initialize the migration sandbox.
+
+        Args:
+            db_url: Database connection URL. Creates a new connection.
+            connection: Existing database connection. Uses savepoint for rollback.
+            migrations_dir: Custom migrations directory. Defaults to "db/migrations".
+
+        Raises:
+            ValueError: If neither db_url nor connection is provided,
+                       or if both are provided.
+
+        Note:
+            When using an existing connection, the sandbox creates a savepoint
+            that will be rolled back on exit. This preserves the connection's
+            transaction state.
+        """
+        if db_url is None and connection is None:
+            raise ValueError("Either 'db_url' or 'connection' must be provided")
+        if db_url is not None and connection is not None:
+            raise ValueError("Provide either 'db_url' or 'connection', not both")
+
+        self._db_url = db_url
+        self._external_connection = connection
+        self._owns_connection = db_url is not None
+        self._savepoint_name = "confiture_sandbox"
+        self._active = False
+
+        self.migrations_dir = migrations_dir or Path("db/migrations")
+        self.connection: psycopg.Connection = None  # type: ignore[assignment]
+        self._validator: DataValidator | None = None
+        self._snapshotter: SchemaSnapshotter | None = None
+
+    def __enter__(self) -> MigrationSandbox:
+        """Enter the sandbox context.
+
+        Creates connection (if URL provided) and starts transaction/savepoint.
+
+        Returns:
+            Self for use in with statement
+        """
+        if self._owns_connection:
+            # Create new connection with autocommit=False for transaction control
+            assert self._db_url is not None
+            self.connection = psycopg.connect(self._db_url, autocommit=False)
+        else:
+            # Use provided connection, create savepoint
+            assert self._external_connection is not None
+            self.connection = self._external_connection
+            with self.connection.cursor() as cursor:
+                cursor.execute(f"SAVEPOINT {self._savepoint_name}")
+
+        self._active = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit the sandbox context.
+
+        Rolls back all changes and closes connection (if we created it).
+
+        Args:
+            exc_type: Exception type if an error occurred
+            exc_val: Exception value
+            exc_tb: Exception traceback
+        """
+        if not self._active:
+            return
+
+        try:
+            if self._owns_connection:
+                # Rollback entire transaction
+                self.connection.rollback()
+                self.connection.close()
+            else:
+                # Rollback to savepoint
+                with self.connection.cursor() as cursor:
+                    cursor.execute(f"ROLLBACK TO SAVEPOINT {self._savepoint_name}")
+                    cursor.execute(f"RELEASE SAVEPOINT {self._savepoint_name}")
+        finally:
+            self._active = False
+
+    def load(self, name: str) -> Migration:
+        """Load and instantiate a migration.
+
+        Args:
+            name: Migration name without .py extension (e.g., "003_move_tables")
+                  or version prefix (e.g., "003")
+
+        Returns:
+            Instantiated Migration object ready to execute
+
+        Raises:
+            MigrationNotFoundError: If migration not found
+            MigrationLoadError: If migration cannot be loaded
+
+        Example:
+            >>> migration = sandbox.load("003_move_catalog_tables")
+            >>> migration.up()
+
+            >>> # Also works with version prefix
+            >>> migration = sandbox.load("003")
+        """
+        from confiture.testing.loader import load_migration
+
+        # Determine if name is a version prefix or full name
+        if "_" in name:
+            # Full name provided
+            migration_class = load_migration(name, migrations_dir=self.migrations_dir)
+        else:
+            # Version prefix provided
+            migration_class = load_migration(version=name, migrations_dir=self.migrations_dir)
+
+        return migration_class(connection=self.connection)
+
+    @property
+    def validator(self) -> DataValidator:
+        """Get data validator for this sandbox.
+
+        Returns:
+            DataValidator configured with the sandbox's connection
+
+        Example:
+            >>> assert sandbox.validator.constraints_valid()
+        """
+        if self._validator is None:
+            from confiture.testing.fixtures.data_validator import DataValidator
+
+            self._validator = DataValidator(self.connection)
+        return self._validator
+
+    @property
+    def snapshotter(self) -> SchemaSnapshotter:
+        """Get schema snapshotter for this sandbox.
+
+        Returns:
+            SchemaSnapshotter configured with the sandbox's connection
+
+        Example:
+            >>> before = sandbox.snapshotter.capture()
+            >>> migration.up()
+            >>> after = sandbox.snapshotter.capture()
+            >>> changes = sandbox.snapshotter.compare(before, after)
+        """
+        if self._snapshotter is None:
+            from confiture.testing.fixtures.schema_snapshotter import SchemaSnapshotter
+
+            self._snapshotter = SchemaSnapshotter(self.connection)
+        return self._snapshotter
+
+    def capture_baseline(self) -> DataBaseline:
+        """Capture data baseline before migration.
+
+        Convenience method that wraps validator.capture_baseline().
+
+        Returns:
+            DataBaseline snapshot for later comparison
+
+        Example:
+            >>> baseline = sandbox.capture_baseline()
+            >>> migration.up()
+            >>> sandbox.assert_no_data_loss(baseline)
+        """
+        return self.validator.capture_baseline()
+
+    def assert_no_data_loss(self, baseline: DataBaseline) -> None:
+        """Assert no data was lost since baseline.
+
+        Convenience method that wraps validator.no_data_loss() with assertion.
+
+        Args:
+            baseline: Baseline captured before migration
+
+        Raises:
+            AssertionError: If data loss is detected
+
+        Example:
+            >>> baseline = sandbox.capture_baseline()
+            >>> migration.up()
+            >>> sandbox.assert_no_data_loss(baseline)  # Raises if data lost
+        """
+        if not self.validator.no_data_loss(baseline):
+            raise AssertionError("Data loss detected after migration")
+
+    def assert_constraints_valid(self) -> None:
+        """Assert all database constraints are valid.
+
+        Convenience method that wraps validator.constraints_valid() with assertion.
+
+        Raises:
+            AssertionError: If constraint violations are detected
+
+        Example:
+            >>> migration.up()
+            >>> sandbox.assert_constraints_valid()  # Raises if violations found
+        """
+        if not self.validator.constraints_valid():
+            raise AssertionError("Constraint violations detected after migration")
+
+    def execute(self, sql: str) -> None:
+        """Execute raw SQL in the sandbox.
+
+        Useful for setting up test data or making assertions.
+
+        Args:
+            sql: SQL to execute
+
+        Example:
+            >>> sandbox.execute("INSERT INTO users (name) VALUES ('test')")
+        """
+        with self.connection.cursor() as cursor:
+            cursor.execute(sql)
+
+    def query(self, sql: str) -> list[tuple]:
+        """Execute a query and return results.
+
+        Args:
+            sql: SQL query to execute
+
+        Returns:
+            List of result rows as tuples
+
+        Example:
+            >>> rows = sandbox.query("SELECT COUNT(*) FROM users")
+            >>> assert rows[0][0] > 0
+        """
+        with self.connection.cursor() as cursor:
+            cursor.execute(sql)
+            return cursor.fetchall()