pytest-neon 2.0.0__tar.gz → 2.1.0__tar.gz

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 2.0.0
+Version: 2.1.0
 Summary: Pytest plugin for Neon database branch isolation in tests
 Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
 Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
@@ -489,16 +489,26 @@ The `neon_branch_readwrite` fixture uses Neon's branch restore API to reset data
 
 This is similar to database transactions but at the branch level.
 
-## Limitations
+## Parallel Test Execution (pytest-xdist)
 
-### Parallel Test Execution
+This plugin supports parallel test execution with [pytest-xdist](https://pytest-xdist.readthedocs.io/). Each xdist worker automatically gets its own isolated branch.
 
-This plugin sets the `DATABASE_URL` environment variable, which is process-global. This means it is **not compatible with pytest-xdist** or other parallel test runners that run tests in the same process.
+```bash
+# Run tests in parallel with 4 workers
+pip install pytest-xdist
+pytest -n 4
+```
+
+**How it works:**
+- Each xdist worker (gw0, gw1, gw2, etc.) creates its own branch
+- Branches are named with the worker ID suffix (e.g., `-test-gw0`, `-test-gw1`)
+- Workers run tests in parallel without database state interference
+- All branches are cleaned up after the test session
 
-If you need parallel execution, you can:
-- Use `neon_branch.connection_string` directly instead of relying on `DATABASE_URL`
-- Run with `pytest-xdist --dist=loadfile` to keep modules in separate processes
-- Run tests serially (default pytest behavior)
+**Cost implications:**
+- Running with `-n 4` creates 4 branches (one per worker) plus the migration branch
+- Choose your parallelism level based on your Neon plan's branch limits
+- Each worker's branch is reset after each test using the fast reset operation (~0.5s)
 
 ## Troubleshooting
 

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/README.md

@@ -444,16 +444,26 @@ The `neon_branch_readwrite` fixture uses Neon's branch restore API to reset data
 
 This is similar to database transactions but at the branch level.
 
-## Limitations
+## Parallel Test Execution (pytest-xdist)
 
-### Parallel Test Execution
+This plugin supports parallel test execution with [pytest-xdist](https://pytest-xdist.readthedocs.io/). Each xdist worker automatically gets its own isolated branch.
 
-This plugin sets the `DATABASE_URL` environment variable, which is process-global. This means it is **not compatible with pytest-xdist** or other parallel test runners that run tests in the same process.
+```bash
+# Run tests in parallel with 4 workers
+pip install pytest-xdist
+pytest -n 4
+```
+
+**How it works:**
+- Each xdist worker (gw0, gw1, gw2, etc.) creates its own branch
+- Branches are named with the worker ID suffix (e.g., `-test-gw0`, `-test-gw1`)
+- Workers run tests in parallel without database state interference
+- All branches are cleaned up after the test session
 
-If you need parallel execution, you can:
-- Use `neon_branch.connection_string` directly instead of relying on `DATABASE_URL`
-- Run with `pytest-xdist --dist=loadfile` to keep modules in separate processes
-- Run tests serially (default pytest behavior)
+**Cost implications:**
+- Running with `-n 4` creates 4 branches (one per worker) plus the migration branch
+- Choose your parallelism level based on your Neon plan's branch limits
+- Each worker's branch is reset after each test using the fast reset operation (~0.5s)
 
 ## Troubleshooting
 

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytest-neon"
-version = "2.0.0"
+version = "2.1.0"
 description = "Pytest plugin for Neon database branch isolation in tests"
 readme = "README.md"
 license = "MIT"

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/src/pytest_neon/__init__.py

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

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/src/pytest_neon/plugin.py

@@ -56,6 +56,17 @@ DEFAULT_BRANCH_EXPIRY_SECONDS = 600
 _MIGRATIONS_NOT_DEFINED = object()
 
 
+def _get_xdist_worker_id() -> str:
+    """
+    Get the pytest-xdist worker ID, or "main" if not running under xdist.
+
+    When running tests in parallel with pytest-xdist, each worker process
+    gets a unique ID (gw0, gw1, gw2, etc.). This is used to create separate
+    branches per worker to avoid database state pollution between parallel tests.
+    """
+    return os.environ.get("PYTEST_XDIST_WORKER", "main")
+
+
 def _get_schema_fingerprint(connection_string: str) -> tuple[tuple[Any, ...], ...]:
     """
     Get a fingerprint of the database schema for change detection.
@@ -527,6 +538,12 @@ def _neon_branch_for_reset(
     session, avoiding issues with Python's module caching (e.g., SQLAlchemy
     engines created at import time would otherwise point to stale branches).
 
+    Parallel Test Support (pytest-xdist):
+        When running tests in parallel with pytest-xdist, each worker gets its
+        own branch. This prevents database state pollution between tests running
+        concurrently on different workers. The worker ID is included in the
+        branch name suffix (e.g., "-test-gw0", "-test-gw1").
+
     Smart Migration Detection:
         This fixture implements a cost-optimization strategy:
 
@@ -558,15 +575,21 @@ def _neon_branch_for_reset(
         # Assume migrations changed something to be safe
         schema_changed = True
 
+    # Get worker ID for parallel test support
+    # Each xdist worker gets its own branch to avoid state pollution
+    worker_id = _get_xdist_worker_id()
+    branch_suffix = f"-test-{worker_id}"
+
     # Only create a child branch if migrations actually modified the schema
-    if schema_changed:
+    # OR if we're running under xdist (each worker needs its own branch)
+    if schema_changed or worker_id != "main":
         yield from _create_neon_branch(
             request,
             parent_branch_id_override=_neon_migration_branch.branch_id,
-            branch_name_suffix="-test",
+            branch_name_suffix=branch_suffix,
         )
     else:
-        # No schema changes - reuse the migration branch directly
+        # No schema changes and not parallel - reuse the migration branch directly
         # This saves creating an unnecessary branch
         yield _neon_migration_branch
 

pytest_neon-2.1.0/tests/test_xdist_worker_support.py

@@ -0,0 +1,189 @@
+"""Tests for pytest-xdist parallel worker support."""
+
+
+class TestXdistBranchIsolation:
+    """Test that parallel workers get separate branches."""
+
+    def test_xdist_worker_creates_branch_even_without_migrations(
+        self, pytester, monkeypatch
+    ):
+        """Even without schema changes, xdist workers should get their own branch."""
+        monkeypatch.setenv("PYTEST_XDIST_WORKER", "gw0")
+
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from pytest_neon.plugin import (
+                NeonBranch,
+                _get_xdist_worker_id,
+                _MIGRATIONS_NOT_DEFINED,
+            )
+
+            branch_creation_calls = []
+
+            @pytest.fixture(scope="session")
+            def _neon_migration_branch(request):
+                # Store empty fingerprint to simulate no psycopg available
+                request.config._neon_pre_migration_fingerprint = ()
+
+                return NeonBranch(
+                    branch_id="br-migration-123",
+                    project_id="proj-mock",
+                    connection_string="postgresql://mock:mock@migration.neon.tech/mockdb",
+                    host="migration.neon.tech",
+                    parent_id="br-parent-000",
+                )
+
+            @pytest.fixture(scope="session")
+            def neon_apply_migrations(_neon_migration_branch):
+                # Return sentinel to simulate NO migrations defined
+                return _MIGRATIONS_NOT_DEFINED
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset(
+                request, _neon_migration_branch, neon_apply_migrations
+            ):
+                # Replicate the real logic
+                sentinel = _MIGRATIONS_NOT_DEFINED
+                migrations_defined = neon_apply_migrations is not sentinel
+                fingerprint_key = "_neon_pre_migration_fingerprint"
+                pre_fp = getattr(request.config, fingerprint_key, ())
+                schema_changed = False
+
+                if migrations_defined and pre_fp:
+                    schema_changed = False  # Simplified
+                elif migrations_defined and not pre_fp:
+                    schema_changed = True
+
+                worker_id = _get_xdist_worker_id()
+                suffix = f"-test-{worker_id}"
+
+                # Key: create branch even without schema changes when xdist
+                if schema_changed or worker_id != "main":
+                    branch_creation_calls.append(f"created-branch{suffix}")
+                    conn = f"postgresql://mock:mock@t{suffix}.neon.tech/db"
+                    branch_info = NeonBranch(
+                        branch_id=f"br-test{suffix}",
+                        project_id="proj-mock",
+                        connection_string=conn,
+                        host=f"t{suffix}.neon.tech",
+                        parent_id=_neon_migration_branch.branch_id,
+                    )
+                else:
+                    branch_creation_calls.append("reused-migration-branch")
+                    branch_info = _neon_migration_branch
+
+                os.environ["DATABASE_URL"] = branch_info.connection_string
+                try:
+                    yield branch_info
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="session", autouse=True)
+            def verify_branch_created():
+                yield
+                # Under xdist, should create a new branch
+                assert branch_creation_calls == ["created-branch-test-gw0"]
+            """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_xdist_creates_branch(_neon_branch_for_reset):
+                # Just trigger the fixture
+                assert _neon_branch_for_reset is not None
+            """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=1)
+
+    def test_non_xdist_reuses_migration_branch_without_migrations(
+        self, pytester, monkeypatch
+    ):
+        """Without xdist and without migrations, should reuse migration branch."""
+        monkeypatch.delenv("PYTEST_XDIST_WORKER", raising=False)
+
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from pytest_neon.plugin import (
+                NeonBranch,
+                _get_xdist_worker_id,
+                _MIGRATIONS_NOT_DEFINED,
+            )
+
+            branch_creation_calls = []
+
+            @pytest.fixture(scope="session")
+            def _neon_migration_branch(request):
+                request.config._neon_pre_migration_fingerprint = ()
+                return NeonBranch(
+                    branch_id="br-migration-123",
+                    project_id="proj-mock",
+                    connection_string="postgresql://mock:mock@migration.neon.tech/mockdb",
+                    host="migration.neon.tech",
+                    parent_id="br-parent-000",
+                )
+
+            @pytest.fixture(scope="session")
+            def neon_apply_migrations(_neon_migration_branch):
+                return _MIGRATIONS_NOT_DEFINED
+
+            @pytest.fixture(scope="session")
+            def _neon_branch_for_reset(
+                request, _neon_migration_branch, neon_apply_migrations
+            ):
+                sentinel = _MIGRATIONS_NOT_DEFINED
+                migrations_defined = neon_apply_migrations is not sentinel
+                fingerprint_key = "_neon_pre_migration_fingerprint"
+                pre_fp = getattr(request.config, fingerprint_key, ())
+                schema_changed = False
+
+                if migrations_defined and pre_fp:
+                    schema_changed = False
+                elif migrations_defined and not pre_fp:
+                    schema_changed = True
+
+                worker_id = _get_xdist_worker_id()
+                suffix = f"-test-{worker_id}"
+
+                if schema_changed or worker_id != "main":
+                    branch_creation_calls.append(f"created-branch{suffix}")
+                    conn = f"postgresql://mock:mock@t{suffix}.neon.tech/db"
+                    branch_info = NeonBranch(
+                        branch_id=f"br-test{suffix}",
+                        project_id="proj-mock",
+                        connection_string=conn,
+                        host=f"t{suffix}.neon.tech",
+                        parent_id=_neon_migration_branch.branch_id,
+                    )
+                else:
+                    branch_creation_calls.append("reused-migration-branch")
+                    branch_info = _neon_migration_branch
+
+                os.environ["DATABASE_URL"] = branch_info.connection_string
+                try:
+                    yield branch_info
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="session", autouse=True)
+            def verify_branch_reused():
+                yield
+                # Without xdist, should reuse migration branch
+                assert branch_creation_calls == ["reused-migration-branch"]
+            """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_no_xdist_reuses_branch(_neon_branch_for_reset):
+                assert _neon_branch_for_reset is not None
+            """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=1)

{pytest_neon-2.0.0 → pytest_neon-2.1.0}/uv.lock

@@ -1200,7 +1200,7 @@ wheels = [
 
 [[package]]
 name = "pytest-neon"
-version = "1.0.0"
+version = "2.0.0"
 source = { editable = "." }
 dependencies = [
     { name = "neon-api" },