pytest-neon 0.4.0__tar.gz → 0.5.1__tar.gz

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/.github/workflows/release.yml

@@ -80,6 +80,13 @@ jobs:
           git tag "v$VERSION"
           git push origin main --tags
 
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.bump.outputs.version }}
+        run: |
+          gh release create "v$VERSION" --generate-notes
+
       - name: Build and publish
         env:
           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/CLAUDE.md

@@ -1,5 +1,9 @@
 # Claude Code Instructions for pytest-neon
 
+## Understanding the Plugin
+
+Read `README.md` for complete documentation on how to use this plugin, including fixtures, configuration options, and migration support.
+
 ## Project Overview
 
 This is a pytest plugin that provides isolated Neon database branches for integration testing. Each test gets isolated database state via branch reset after each test.
@@ -7,6 +11,8 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 ## Key Architecture
 
 - **Entry point**: `src/pytest_neon/plugin.py` - Contains all fixtures and pytest hooks
+- **Migration fixture**: `_neon_migration_branch` - Session-scoped, parent for all test branches
+- **User migration hook**: `neon_apply_migrations` - Session-scoped no-op, users override to run migrations
 - **Core fixture**: `neon_branch` - Creates branch (module-scoped), resets after each test (function-scoped wrapper), sets `DATABASE_URL`, yields `NeonBranch` dataclass
 - **Shared fixture**: `neon_branch_shared` - Module-scoped, no reset between tests
 - **Convenience fixtures**: `neon_connection`, `neon_connection_psycopg`, `neon_engine` - Optional, require extras
@@ -19,7 +25,9 @@ This is a pytest plugin that provides isolated Neon database branches for integr
 ## Important Patterns
 
 ### Fixture Scopes
-- `_neon_branch_for_reset`: `scope="module"` - internal, creates one branch per test file
+- `_neon_migration_branch`: `scope="session"` - internal, parent for all test branches, migrations run here
+- `neon_apply_migrations`: `scope="session"` - user overrides to run migrations
+- `_neon_branch_for_reset`: `scope="module"` - internal, creates one branch per test file from migration branch
 - `neon_branch`: `scope="function"` - wraps the above, resets branch after each test
 - `neon_branch_shared`: `scope="module"` - one branch per test file, no reset
 - Connection fixtures: `scope="function"` (default) - fresh connection per test

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.4.0
+Version: 0.5.1
 Summary: Pytest plugin for Neon database branch isolation in tests
-Project-URL: Homepage, https://github.com/zain/pytest-neon
-Project-URL: Repository, https://github.com/zain/pytest-neon
-Project-URL: Issues, https://github.com/zain/pytest-neon/issues
+Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Issues, https://github.com/ZainRizvi/pytest-neon/issues
 Author: Zain Rizvi
 License-Expression: MIT
 License-File: LICENSE
@@ -200,6 +200,90 @@ def test_query(neon_engine):
         assert result.scalar() == 1
 ```
 
+## Migrations
+
+pytest-neon supports running migrations once before tests, with all test resets preserving the migrated state.
+
+### How It Works
+
+When you override the `neon_apply_migrations` fixture, the plugin uses a two-branch architecture:
+
+```
+Parent Branch (your configured parent)
+    └── Migration Branch (session-scoped)
+            │   ↑ migrations run here ONCE
+            └── Test Branch (module-scoped)
+                    ↑ resets to migration branch after each test
+```
+
+This means:
+- Migrations run **once per test session** (not per test or per module)
+- Each test reset restores to the **post-migration state**
+- Tests always see your migrated schema
+
+### Setup
+
+Override the `neon_apply_migrations` fixture in your `conftest.py`:
+
+**Alembic:**
+```python
+# conftest.py
+import subprocess
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run Alembic migrations before tests."""
+    # DATABASE_URL is already set to the migration branch
+    subprocess.run(["alembic", "upgrade", "head"], check=True)
+```
+
+**Django:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run Django migrations before tests."""
+    from django.core.management import call_command
+    call_command("migrate", "--noinput")
+```
+
+**Raw SQL:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Apply schema from SQL file."""
+    import psycopg
+    with psycopg.connect(_neon_migration_branch.connection_string) as conn:
+        with open("schema.sql") as f:
+            conn.execute(f.read())
+        conn.commit()
+```
+
+**Custom migration tool:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run custom migrations."""
+    from myapp.migrations import run_migrations
+    run_migrations(_neon_migration_branch.connection_string)
+```
+
+### Important Notes
+
+- The `_neon_migration_branch` parameter gives you access to the `NeonBranch` object with `connection_string`, `branch_id`, etc.
+- `DATABASE_URL` (or your configured env var) is automatically set when the fixture runs
+- If you don't override `neon_apply_migrations`, no migrations run (the fixture is a no-op by default)
+- Migrations run before any test branches are created, so all tests see the same migrated schema
+
 ## Configuration
 
 ### Environment Variables

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/README.md

@@ -158,6 +158,90 @@ def test_query(neon_engine):
         assert result.scalar() == 1
 ```
 
+## Migrations
+
+pytest-neon supports running migrations once before tests, with all test resets preserving the migrated state.
+
+### How It Works
+
+When you override the `neon_apply_migrations` fixture, the plugin uses a two-branch architecture:
+
+```
+Parent Branch (your configured parent)
+    └── Migration Branch (session-scoped)
+            │   ↑ migrations run here ONCE
+            └── Test Branch (module-scoped)
+                    ↑ resets to migration branch after each test
+```
+
+This means:
+- Migrations run **once per test session** (not per test or per module)
+- Each test reset restores to the **post-migration state**
+- Tests always see your migrated schema
+
+### Setup
+
+Override the `neon_apply_migrations` fixture in your `conftest.py`:
+
+**Alembic:**
+```python
+# conftest.py
+import subprocess
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run Alembic migrations before tests."""
+    # DATABASE_URL is already set to the migration branch
+    subprocess.run(["alembic", "upgrade", "head"], check=True)
+```
+
+**Django:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run Django migrations before tests."""
+    from django.core.management import call_command
+    call_command("migrate", "--noinput")
+```
+
+**Raw SQL:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Apply schema from SQL file."""
+    import psycopg
+    with psycopg.connect(_neon_migration_branch.connection_string) as conn:
+        with open("schema.sql") as f:
+            conn.execute(f.read())
+        conn.commit()
+```
+
+**Custom migration tool:**
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    """Run custom migrations."""
+    from myapp.migrations import run_migrations
+    run_migrations(_neon_migration_branch.connection_string)
+```
+
+### Important Notes
+
+- The `_neon_migration_branch` parameter gives you access to the `NeonBranch` object with `connection_string`, `branch_id`, etc.
+- `DATABASE_URL` (or your configured env var) is automatically set when the fixture runs
+- If you don't override `neon_apply_migrations`, no migrations run (the fixture is a no-op by default)
+- Migrations run before any test branches are created, so all tests see the same migrated schema
+
 ## Configuration
 
 ### Environment Variables

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-neon"
-version = "0.4.0"
+version = "0.5.1"
 description = "Pytest plugin for Neon database branch isolation in tests"
 readme = "README.md"
 license = "MIT"
@@ -45,9 +45,9 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/zain/pytest-neon"
-Repository = "https://github.com/zain/pytest-neon"
-Issues = "https://github.com/zain/pytest-neon/issues"
+Homepage = "https://github.com/ZainRizvi/pytest-neon"
+Repository = "https://github.com/ZainRizvi/pytest-neon"
+Issues = "https://github.com/ZainRizvi/pytest-neon/issues"
 
 [project.entry-points.pytest11]
 neon = "pytest_neon.plugin"

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/src/pytest_neon/__init__.py

@@ -9,7 +9,7 @@ from pytest_neon.plugin import (
     neon_engine,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 __all__ = [
     "NeonBranch",
     "neon_branch",

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/src/pytest_neon/plugin.py

@@ -137,11 +137,20 @@ def _get_config_value(
 
 def _create_neon_branch(
     request: pytest.FixtureRequest,
+    parent_branch_id_override: str | None = None,
+    branch_expiry_override: int | None = None,
+    branch_name_suffix: str = "",
 ) -> Generator[NeonBranch, None, None]:
     """
     Internal helper that creates and manages a Neon branch lifecycle.
 
     This is the core implementation used by branch fixtures.
+
+    Args:
+        request: Pytest fixture request
+        parent_branch_id_override: If provided, use this as parent instead of config
+        branch_expiry_override: If provided, use this expiry instead of config
+        branch_name_suffix: Optional suffix for branch name (e.g., "-migrated", "-test")
     """
     config = request.config
 
@@ -149,7 +158,8 @@ def _create_neon_branch(
     project_id = _get_config_value(
         config, "neon_project_id", "NEON_PROJECT_ID", "neon_project_id"
     )
-    parent_branch_id = _get_config_value(
+    # Use override if provided, otherwise read from config
+    parent_branch_id = parent_branch_id_override or _get_config_value(
         config, "neon_parent_branch", "NEON_PARENT_BRANCH_ID", "neon_parent_branch"
     )
     database_name = _get_config_value(
@@ -164,9 +174,13 @@ def _create_neon_branch(
     if keep_branches is None:
         keep_branches = config.getini("neon_keep_branches")
 
-    branch_expiry = config.getoption("neon_branch_expiry", default=None)
-    if branch_expiry is None:
-        branch_expiry = int(config.getini("neon_branch_expiry"))
+    # Use override if provided, otherwise read from config
+    if branch_expiry_override is not None:
+        branch_expiry = branch_expiry_override
+    else:
+        branch_expiry = config.getoption("neon_branch_expiry", default=None)
+        if branch_expiry is None:
+            branch_expiry = int(config.getini("neon_branch_expiry"))
 
     env_var_name = _get_config_value(
         config, "neon_env_var", "", "neon_env_var", "DATABASE_URL"
@@ -185,7 +199,7 @@ def _create_neon_branch(
     neon = NeonAPI(api_key=api_key)
 
     # Generate unique branch name
-    branch_name = f"pytest-{os.urandom(4).hex()}"
+    branch_name = f"pytest-{os.urandom(4).hex()}{branch_name_suffix}"
 
     # Build branch creation payload
     branch_config: dict[str, Any] = {"name": branch_name}
@@ -311,12 +325,86 @@ def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
     response.raise_for_status()
 
 
+@pytest.fixture(scope="session")
+def _neon_migration_branch(
+    request: pytest.FixtureRequest,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Session-scoped branch where migrations are applied.
+
+    This branch is created from the configured parent and serves as
+    the parent for all test branches. Migrations run once per session
+    on this branch.
+
+    Note: The migration branch cannot have an expiry because Neon doesn't
+    allow creating child branches from branches with expiration dates.
+    Cleanup relies on the fixture teardown at session end.
+    """
+    # No expiry - Neon doesn't allow children from branches with expiry
+    yield from _create_neon_branch(
+        request,
+        branch_expiry_override=0,
+        branch_name_suffix="-migrated",
+    )
+
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch: NeonBranch) -> None:
+    """
+    Override this fixture to run migrations on the test database.
+
+    The migration branch is already created and DATABASE_URL is set.
+    Migrations run once per test session, before any tests execute.
+
+    Example in conftest.py:
+
+        @pytest.fixture(scope="session")
+        def neon_apply_migrations(_neon_migration_branch):
+            import subprocess
+            subprocess.run(["alembic", "upgrade", "head"], check=True)
+
+    Or with Django:
+
+        @pytest.fixture(scope="session")
+        def neon_apply_migrations(_neon_migration_branch):
+            from django.core.management import call_command
+            call_command("migrate", "--noinput")
+
+    Or with raw SQL:
+
+        @pytest.fixture(scope="session")
+        def neon_apply_migrations(_neon_migration_branch):
+            import psycopg
+            with psycopg.connect(_neon_migration_branch.connection_string) as conn:
+                with open("schema.sql") as f:
+                    conn.execute(f.read())
+                conn.commit()
+
+    Args:
+        _neon_migration_branch: The migration branch with connection details.
+            Use _neon_migration_branch.connection_string to connect directly,
+            or rely on DATABASE_URL which is already set.
+    """
+    pass  # No-op by default - users override this fixture to run migrations
+
+
 @pytest.fixture(scope="module")
 def _neon_branch_for_reset(
     request: pytest.FixtureRequest,
+    _neon_migration_branch: NeonBranch,
+    neon_apply_migrations: None,  # Ensures migrations run first
 ) -> Generator[NeonBranch, None, None]:
-    """Internal fixture that creates a branch for reset-based isolation."""
-    yield from _create_neon_branch(request)
+    """
+    Internal fixture that creates a test branch from the migration branch.
+
+    The test branch is created as a child of the migration branch, so resets
+    restore to post-migration state rather than the original parent state.
+    """
+    yield from _create_neon_branch(
+        request,
+        parent_branch_id_override=_neon_migration_branch.branch_id,
+        branch_name_suffix="-test",
+    )
 
 
 @pytest.fixture(scope="function")
@@ -383,6 +471,8 @@ def neon_branch(
 @pytest.fixture(scope="module")
 def neon_branch_shared(
     request: pytest.FixtureRequest,
+    _neon_migration_branch: NeonBranch,
+    neon_apply_migrations: None,  # Ensures migrations run first
 ) -> Generator[NeonBranch, None, None]:
     """
     Provide a shared Neon database branch for all tests in a module.
@@ -391,6 +481,9 @@ def neon_branch_shared(
     tests without resetting. This is the fastest option but tests can see
     each other's data modifications.
 
+    If you override the `neon_apply_migrations` fixture, migrations will run
+    once before the first test, and this branch will include the migrated schema.
+
     Use this when:
     - Tests are read-only or don't interfere with each other
     - You manually clean up test data within each test
@@ -408,7 +501,11 @@ def neon_branch_shared(
             # Fast: no reset between tests, but be careful about data leakage
             conn_string = neon_branch_shared.connection_string
     """
-    yield from _create_neon_branch(request)
+    yield from _create_neon_branch(
+        request,
+        parent_branch_id_override=_neon_migration_branch.branch_id,
+        branch_name_suffix="-shared",
+    )
 
 
 @pytest.fixture

{pytest_neon-0.4.0 → pytest_neon-0.5.1}/tests/test_integration.py

@@ -81,6 +81,81 @@ class TestRealBranchCreation:
         assert os.environ.get("DATABASE_URL") == neon_branch.connection_string
 
 
+class TestMigrations:
+    """Test migration support with real Neon branches."""
+
+    def test_migrations_persist_across_resets(self, pytester, tmp_path):
+        """Test that migrations run once and persist across test resets."""
+        # Write a conftest that tracks migration and verifies table exists
+        conftest = """
+import os
+import pytest
+
+# Track if migrations ran
+migrations_ran = [False]
+
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    \"\"\"Create a test table via migration.\"\"\"
+    try:
+        import psycopg
+    except ImportError:
+        pytest.skip("psycopg not installed")
+
+    with psycopg.connect(_neon_migration_branch.connection_string) as conn:
+        with conn.cursor() as cur:
+            cur.execute(\"\"\"
+                CREATE TABLE IF NOT EXISTS migration_test (
+                    id SERIAL PRIMARY KEY,
+                    value TEXT NOT NULL
+                )
+            \"\"\")
+        conn.commit()
+    migrations_ran[0] = True
+
+def pytest_sessionfinish(session, exitstatus):
+    assert migrations_ran[0], "Migrations should have run"
+"""
+        pytester.makeconftest(conftest)
+
+        # Write tests that verify the migrated table exists and data resets
+        pytester.makepyfile(
+            """
+import psycopg
+
+def test_first_insert(neon_branch):
+    \"\"\"Insert data - table should exist from migration.\"\"\"
+    with psycopg.connect(neon_branch.connection_string) as conn:
+        with conn.cursor() as cur:
+            cur.execute("INSERT INTO migration_test (value) VALUES ('first')")
+        conn.commit()
+
+        with conn.cursor() as cur:
+            cur.execute("SELECT COUNT(*) FROM migration_test")
+            count = cur.fetchone()[0]
+            assert count == 1
+
+def test_second_insert_after_reset(neon_branch):
+    \"\"\"After reset, table exists but previous data is gone.\"\"\"
+    with psycopg.connect(neon_branch.connection_string) as conn:
+        # Table should still exist (from migration)
+        with conn.cursor() as cur:
+            cur.execute("SELECT COUNT(*) FROM migration_test")
+            count = cur.fetchone()[0]
+            # Data from first test should be gone after reset
+            assert count == 0
+
+        # Insert new data
+        with conn.cursor() as cur:
+            cur.execute("INSERT INTO migration_test (value) VALUES ('second')")
+        conn.commit()
+"""
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=2)
+
+
 class TestRealDatabaseConnectivity:
     """Test actual database connectivity."""
 

pytest_neon-0.5.1/tests/test_migrations.py

@@ -0,0 +1,77 @@
+"""Tests for migration support."""
+
+
+class TestMigrationFixtureOrder:
+    """Test that migrations run before test branches are created."""
+
+    def test_migrations_run_before_test_branch_created(self, pytester):
+        """Verify neon_apply_migrations is called before test branch exists."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            execution_order = []
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="session")
+            def _neon_migration_branch():
+                execution_order.append("migration_branch_created")
+                branch = FakeNeonBranch(
+                    branch_id="br-migration",
+                    project_id="proj-test",
+                    connection_string="postgresql://migration",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                yield branch
+
+            @pytest.fixture(scope="session")
+            def neon_apply_migrations(_neon_migration_branch):
+                execution_order.append("migrations_applied")
+                # User would run migrations here
+
+            @pytest.fixture(scope="module")
+            def _neon_branch_for_reset(_neon_migration_branch, neon_apply_migrations):
+                execution_order.append("test_branch_created")
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id=_neon_migration_branch.branch_id,
+                )
+                yield branch
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Verify order: migration branch -> migrations -> test branch
+                assert execution_order == [
+                    "migration_branch_created",
+                    "migrations_applied",
+                    "test_branch_created",
+                ], f"Wrong order: {execution_order}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_uses_branch(neon_branch):
+                assert neon_branch.parent_id == "br-migration"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=1)