pytest-neon 0.2.1__tar.gz → 0.3.0__tar.gz

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/CLAUDE.md

@@ -2,27 +2,30 @@
 
 ## Project Overview
 
-This is a pytest plugin that provides isolated Neon database branches for integration testing. Each test module gets its own branch, with automatic cleanup.
+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.
 
 ## Key Architecture
 
 - **Entry point**: `src/pytest_neon/plugin.py` - Contains all fixtures and pytest hooks
-- **Core fixture**: `neon_branch` - Creates branch, sets `DATABASE_URL`, yields `NeonBranch` dataclass
+- **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
 
 ## Dependencies
 
-- Core: `pytest`, `neon-api` only
+- Core: `pytest`, `neon-api`, `requests`
 - Optional extras: `psycopg2`, `psycopg`, `sqlalchemy` - for convenience fixtures
 
 ## Important Patterns
 
 ### Fixture Scopes
-- `neon_branch`: `scope="module"` - one branch per test file
+- `_neon_branch_for_reset`: `scope="module"` - internal, creates one branch per test file
+- `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
 
 ### Environment Variable Handling
-The `_temporary_env` context manager sets `DATABASE_URL` during test execution and restores the original value after. This is critical for not polluting other tests.
+The `_create_neon_branch` function sets `DATABASE_URL` (or configured env var) during the fixture lifecycle and restores the original value in the finally block. This is critical for not polluting other tests.
 
 ### Error Messages
 Convenience fixtures use `pytest.fail()` with detailed, formatted error messages when dependencies are missing. Keep this pattern - users need clear guidance on how to fix import errors.
@@ -37,9 +40,15 @@ Tests in `tests/` use `pytester` for testing pytest plugins. The plugin itself c
 
 ## Publishing
 
+Use the GitHub Actions release workflow:
+1. Go to Actions → Release → Run workflow
+2. Choose patch/minor/major
+3. Workflow bumps version, commits, tags, and publishes to PyPI
+
+Or manually:
 ```bash
-python -m build
-python -m twine upload dist/*
+uv build
+uv publish --token $PYPI_TOKEN
 ```
 
 Package name on PyPI: `pytest-neon`

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -276,6 +276,28 @@ jobs:
 
 Branches use copy-on-write storage, so you only pay for data that differs from the parent branch.
 
+### What Reset Does
+
+The `neon_branch` fixture uses Neon's branch restore API to reset database state after each test:
+
+- **Data changes are reverted**: All INSERT, UPDATE, DELETE operations are undone
+- **Schema changes are reverted**: CREATE TABLE, ALTER TABLE, DROP TABLE, etc. are undone
+- **Sequences are reset**: Auto-increment counters return to parent state
+- **Complete rollback**: The branch is restored to the exact state of the parent at the time the child branch was created
+
+This is similar to database transactions but at the branch level.
+
+## Limitations
+
+### Parallel Test Execution
+
+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.
+
+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)
+
 ## Troubleshooting
 
 ### "psycopg not installed" or "psycopg2 not installed"

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/README.md

@@ -234,6 +234,28 @@ jobs:
 
 Branches use copy-on-write storage, so you only pay for data that differs from the parent branch.
 
+### What Reset Does
+
+The `neon_branch` fixture uses Neon's branch restore API to reset database state after each test:
+
+- **Data changes are reverted**: All INSERT, UPDATE, DELETE operations are undone
+- **Schema changes are reverted**: CREATE TABLE, ALTER TABLE, DROP TABLE, etc. are undone
+- **Sequences are reset**: Auto-increment counters return to parent state
+- **Complete rollback**: The branch is restored to the exact state of the parent at the time the child branch was created
+
+This is similar to database transactions but at the branch level.
+
+## Limitations
+
+### Parallel Test Execution
+
+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.
+
+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)
+
 ## Troubleshooting
 
 ### "psycopg not installed" or "psycopg2 not installed"

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/pyproject.toml

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

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/src/pytest_neon/__init__.py

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

{pytest_neon-0.2.1 → pytest_neon-0.3.0}/src/pytest_neon/plugin.py

@@ -7,14 +7,12 @@ import time
 from collections.abc import Generator
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 import pytest
 import requests
 from neon_api import NeonAPI
-
-if TYPE_CHECKING:
-    pass
+from neon_api.schema import EndpointState
 
 # Default branch expiry in seconds (10 minutes)
 DEFAULT_BRANCH_EXPIRY_SECONDS = 600
@@ -168,9 +166,10 @@ def _create_neon_branch(
         raise RuntimeError(f"No endpoint created for branch {branch.id}")
 
     # Wait for endpoint to be ready (it starts in "init" state)
-    # Endpoints typically become active in 1-2 seconds
+    # Endpoints typically become active in 1-2 seconds, but we allow up to 60s
+    # to handle occasional Neon API slowness or high load scenarios
     max_wait_seconds = 60
-    poll_interval = 0.5
+    poll_interval = 0.5  # Poll every 500ms for responsive feedback
     waited = 0.0
 
     while True:
@@ -180,7 +179,7 @@ def _create_neon_branch(
         endpoint = endpoint_response.endpoint
         state = endpoint.current_state
 
-        if state == "active" or str(state) == "EndpointState.active":
+        if state == EndpointState.active:
             break
 
         if waited >= max_wait_seconds:
@@ -254,7 +253,7 @@ def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
         "Content-Type": "application/json",
     }
     response = requests.post(
-        url, headers=headers, json={"source_branch_id": branch.parent_id}
+        url, headers=headers, json={"source_branch_id": branch.parent_id}, timeout=30
     )
     response.raise_for_status()
 
@@ -304,6 +303,15 @@ def neon_branch(
     config = request.config
     api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY")
 
+    # Validate that branch has a parent for reset functionality
+    if not _neon_branch_for_reset.parent_id:
+        pytest.fail(
+            f"\n\nBranch {_neon_branch_for_reset.branch_id} has no parent. "
+            f"The neon_branch fixture requires a parent branch for reset.\n\n"
+            f"Use neon_branch_shared if you don't need reset, or specify "
+            f"a parent branch with --neon-parent-branch or NEON_PARENT_BRANCH_ID."
+        )
+
     yield _neon_branch_for_reset
 
     # Reset branch to parent state after each test
@@ -311,11 +319,11 @@ def neon_branch(
         try:
             _reset_branch_to_parent(branch=_neon_branch_for_reset, api_key=api_key)
         except Exception as e:
-            import warnings
-
-            warnings.warn(
-                f"Failed to reset branch {_neon_branch_for_reset.branch_id}: {e}",
-                stacklevel=2,
+            pytest.fail(
+                f"\n\nFailed to reset branch {_neon_branch_for_reset.branch_id} "
+                f"after test. Subsequent tests in this module may see dirty "
+                f"database state.\n\nError: {e}\n\n"
+                f"To keep the branch for debugging, use --neon-keep-branches"
             )
 
 

pytest_neon-0.3.0/tests/test_reset_behavior.py

@@ -0,0 +1,179 @@
+"""Tests for branch reset behavior."""
+
+
+class TestResetBehavior:
+    """Test that branch reset happens between tests."""
+
+    def test_reset_called_after_each_test(self, pytester):
+        """Verify reset is called after each test function."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            reset_count = [0]
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="module")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                yield _neon_branch_for_reset
+                # Simulate reset
+                reset_count[0] += 1
+
+            def pytest_sessionfinish(session, exitstatus):
+                # Verify resets happened
+                assert reset_count[0] == 2, f"Expected 2 resets, got {reset_count[0]}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_first(neon_branch):
+                assert neon_branch.branch_id == "br-test"
+
+            def test_second(neon_branch):
+                assert neon_branch.branch_id == "br-test"
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=2)
+
+    def test_same_branch_used_across_tests_in_module(self, pytester):
+        """Verify all tests in a module use the same branch instance."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            branch_ids_seen = []
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str
+
+            @pytest.fixture(scope="module")
+            def _neon_branch_for_reset():
+                import random
+                branch = FakeNeonBranch(
+                    branch_id=f"br-{random.randint(1000, 9999)}",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id="br-parent",
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                branch_ids_seen.append(_neon_branch_for_reset.branch_id)
+                yield _neon_branch_for_reset
+
+            def pytest_sessionfinish(session, exitstatus):
+                # All tests should see the same branch
+                unique = len(set(branch_ids_seen))
+                assert unique == 1, f"Expected 1 unique branch, got {unique}"
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_first(neon_branch):
+                pass
+
+            def test_second(neon_branch):
+                pass
+
+            def test_third(neon_branch):
+                pass
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(passed=3)
+
+
+class TestParentIdValidation:
+    """Test that missing parent_id is caught early."""
+
+    def test_fails_if_no_parent_id(self, pytester):
+        """Verify that neon_branch fails if branch has no parent."""
+        pytester.makeconftest(
+            """
+            import os
+            import pytest
+            from dataclasses import dataclass
+
+            @dataclass
+            class FakeNeonBranch:
+                branch_id: str
+                project_id: str
+                connection_string: str
+                host: str
+                parent_id: str = None  # No parent!
+
+            @pytest.fixture(scope="module")
+            def _neon_branch_for_reset():
+                branch = FakeNeonBranch(
+                    branch_id="br-test",
+                    project_id="proj-test",
+                    connection_string="postgresql://test",
+                    host="test.neon.tech",
+                    parent_id=None,  # No parent
+                )
+                os.environ["DATABASE_URL"] = branch.connection_string
+                try:
+                    yield branch
+                finally:
+                    os.environ.pop("DATABASE_URL", None)
+
+            @pytest.fixture(scope="function")
+            def neon_branch(_neon_branch_for_reset):
+                if not _neon_branch_for_reset.parent_id:
+                    pytest.fail("Branch has no parent - cannot reset")
+                yield _neon_branch_for_reset
+        """
+        )
+
+        pytester.makepyfile(
+            """
+            def test_should_fail(neon_branch):
+                pass
+        """
+        )
+
+        result = pytester.runpytest("-v")
+        result.assert_outcomes(errors=1)
+        assert "has no parent" in result.stdout.str()