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

{pytest_neon-0.2.1 → pytest_neon-0.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.2.1
+Version: 0.4.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
@@ -120,6 +120,7 @@ Returns a `NeonBranch` dataclass with:
 - `project_id`: The Neon project ID
 - `connection_string`: Full PostgreSQL connection URI
 - `host`: The database host
+- `parent_id`: The parent branch ID (used for resets)
 
 ```python
 import os
@@ -237,6 +238,30 @@ pytest --neon-branch-expiry=0
 pytest --neon-env-var=TEST_DATABASE_URL
 ```
 
+### pyproject.toml / pytest.ini
+
+You can also configure options in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+neon_database = "mydb"
+neon_role = "myrole"
+neon_keep_branches = true
+neon_branch_expiry = "300"
+```
+
+Or in `pytest.ini`:
+
+```ini
+[pytest]
+neon_database = mydb
+neon_role = myrole
+neon_keep_branches = true
+neon_branch_expiry = 300
+```
+
+**Priority order**: CLI options > environment variables > ini settings > defaults
+
 ## CI/CD Integration
 
 ### GitHub Actions
@@ -276,6 +301,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.4.0}/README.md

@@ -78,6 +78,7 @@ Returns a `NeonBranch` dataclass with:
 - `project_id`: The Neon project ID
 - `connection_string`: Full PostgreSQL connection URI
 - `host`: The database host
+- `parent_id`: The parent branch ID (used for resets)
 
 ```python
 import os
@@ -195,6 +196,30 @@ pytest --neon-branch-expiry=0
 pytest --neon-env-var=TEST_DATABASE_URL
 ```
 
+### pyproject.toml / pytest.ini
+
+You can also configure options in your `pyproject.toml`:
+
+```toml
+[tool.pytest.ini_options]
+neon_database = "mydb"
+neon_role = "myrole"
+neon_keep_branches = true
+neon_branch_expiry = "300"
+```
+
+Or in `pytest.ini`:
+
+```ini
+[pytest]
+neon_database = mydb
+neon_role = myrole
+neon_keep_branches = true
+neon_branch_expiry = 300
+```
+
+**Priority order**: CLI options > environment variables > ini settings > defaults
+
 ## CI/CD Integration
 
 ### GitHub Actions
@@ -234,6 +259,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.4.0}/pyproject.toml

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

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

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

{pytest_neon-0.2.1 → pytest_neon-0.4.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
@@ -32,9 +30,10 @@ class NeonBranch:
 
 
 def pytest_addoption(parser: pytest.Parser) -> None:
-    """Add Neon-specific command line options."""
+    """Add Neon-specific command line options and ini settings."""
     group = parser.getgroup("neon", "Neon database branching")
 
+    # CLI options
     group.addoption(
         "--neon-api-key",
         dest="neon_api_key",
@@ -53,13 +52,11 @@ def pytest_addoption(parser: pytest.Parser) -> None:
     group.addoption(
         "--neon-database",
         dest="neon_database",
-        default="neondb",
         help="Database name (default: neondb)",
     )
     group.addoption(
         "--neon-role",
         dest="neon_role",
-        default="neondb_owner",
         help="Database role (default: neondb_owner)",
     )
     group.addoption(
@@ -72,7 +69,6 @@ def pytest_addoption(parser: pytest.Parser) -> None:
         "--neon-branch-expiry",
         dest="neon_branch_expiry",
         type=int,
-        default=DEFAULT_BRANCH_EXPIRY_SECONDS,
         help=(
             f"Branch auto-expiry in seconds "
             f"(default: {DEFAULT_BRANCH_EXPIRY_SECONDS}). Set to 0 to disable."
@@ -81,19 +77,62 @@ def pytest_addoption(parser: pytest.Parser) -> None:
     group.addoption(
         "--neon-env-var",
         dest="neon_env_var",
-        default="DATABASE_URL",
         help="Environment variable to set with connection string (default: DATABASE_URL)",  # noqa: E501
     )
 
+    # INI file settings (pytest.ini, pyproject.toml, etc.)
+    parser.addini("neon_api_key", "Neon API key", default=None)
+    parser.addini("neon_project_id", "Neon project ID", default=None)
+    parser.addini("neon_parent_branch", "Parent branch ID", default=None)
+    parser.addini("neon_database", "Database name", default="neondb")
+    parser.addini("neon_role", "Database role", default="neondb_owner")
+    parser.addini(
+        "neon_keep_branches",
+        "Don't delete branches after tests",
+        type="bool",
+        default=False,
+    )
+    parser.addini(
+        "neon_branch_expiry",
+        "Branch auto-expiry in seconds",
+        default=str(DEFAULT_BRANCH_EXPIRY_SECONDS),
+    )
+    parser.addini(
+        "neon_env_var",
+        "Environment variable for connection string",
+        default="DATABASE_URL",
+    )
+
 
 def _get_config_value(
-    config: pytest.Config, option: str, env_var: str, default: str | None = None
+    config: pytest.Config,
+    option: str,
+    env_var: str,
+    ini_name: str | None = None,
+    default: str | None = None,
 ) -> str | None:
-    """Get config value from CLI option, env var, or default."""
+    """Get config value from CLI option, env var, ini setting, or default.
+
+    Priority order: CLI option > environment variable > ini setting > default
+    """
+    # 1. CLI option (highest priority)
     value = config.getoption(option, default=None)
     if value is not None:
         return value
-    return os.environ.get(env_var, default)
+
+    # 2. Environment variable
+    env_value = os.environ.get(env_var)
+    if env_value is not None:
+        return env_value
+
+    # 3. INI setting (pytest.ini, pyproject.toml, etc.)
+    if ini_name is not None:
+        ini_value = config.getini(ini_name)
+        if ini_value:
+            return ini_value
+
+    # 4. Default
+    return default
 
 
 def _create_neon_branch(
@@ -106,20 +145,32 @@ def _create_neon_branch(
     """
     config = request.config
 
-    api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY")
-    project_id = _get_config_value(config, "neon_project_id", "NEON_PROJECT_ID")
+    api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY", "neon_api_key")
+    project_id = _get_config_value(
+        config, "neon_project_id", "NEON_PROJECT_ID", "neon_project_id"
+    )
     parent_branch_id = _get_config_value(
-        config, "neon_parent_branch", "NEON_PARENT_BRANCH_ID"
+        config, "neon_parent_branch", "NEON_PARENT_BRANCH_ID", "neon_parent_branch"
     )
     database_name = _get_config_value(
-        config, "neon_database", "NEON_DATABASE", "neondb"
+        config, "neon_database", "NEON_DATABASE", "neon_database", "neondb"
+    )
+    role_name = _get_config_value(
+        config, "neon_role", "NEON_ROLE", "neon_role", "neondb_owner"
     )
-    role_name = _get_config_value(config, "neon_role", "NEON_ROLE", "neondb_owner")
-    keep_branches = config.getoption("neon_keep_branches", default=False)
-    branch_expiry = config.getoption(
-        "neon_branch_expiry", default=DEFAULT_BRANCH_EXPIRY_SECONDS
+
+    # For boolean/int options, check CLI first, then ini
+    keep_branches = config.getoption("neon_keep_branches", default=None)
+    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"))
+
+    env_var_name = _get_config_value(
+        config, "neon_env_var", "", "neon_env_var", "DATABASE_URL"
     )
-    env_var_name = config.getoption("neon_env_var", default="DATABASE_URL")
 
     if not api_key:
         pytest.skip(
@@ -168,9 +219,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 +232,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 +306,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()
 
@@ -302,7 +354,16 @@ def neon_branch(
             conn_string = neon_branch.connection_string
     """
     config = request.config
-    api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY")
+    api_key = _get_config_value(config, "neon_api_key", "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
 
@@ -311,11 +372,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.2.1 → pytest_neon-0.4.0}/tests/conftest.py

@@ -19,8 +19,13 @@ from pytest_neon.plugin import NeonBranch
 @pytest.fixture(scope="module")
 def neon_branch(request):
     """Mock neon_branch fixture for testing."""
-    keep_branches = request.config.getoption("neon_keep_branches", default=False)
-    env_var_name = request.config.getoption("neon_env_var", default="DATABASE_URL")
+    keep_branches = request.config.getoption("neon_keep_branches", default=None)
+    if keep_branches is None:
+        keep_branches = False
+
+    env_var_name = request.config.getoption("neon_env_var", default=None)
+    if env_var_name is None:
+        env_var_name = "DATABASE_URL"
 
     branch_info = NeonBranch(
         branch_id="br-mock-123",

pytest_neon-0.4.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()