pytest-neon 0.2.0__py3-none-any.whl

pytest_neon/__init__.py

@@ -0,0 +1,20 @@
+"""Pytest plugin for Neon database branch isolation in tests."""
+
+from pytest_neon.plugin import (
+    NeonBranch,
+    neon_branch,
+    neon_branch_shared,
+    neon_connection,
+    neon_connection_psycopg,
+    neon_engine,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "NeonBranch",
+    "neon_branch",
+    "neon_branch_shared",
+    "neon_connection",
+    "neon_connection_psycopg",
+    "neon_engine",
+]

pytest_neon/plugin.py

@@ -0,0 +1,477 @@
+"""Pytest plugin providing Neon database branch fixtures."""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Generator
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any
+
+import pytest
+import requests
+from neon_api import NeonAPI
+
+if TYPE_CHECKING:
+    pass
+
+# Default branch expiry in seconds (10 minutes)
+DEFAULT_BRANCH_EXPIRY_SECONDS = 600
+
+
+@dataclass
+class NeonBranch:
+    """Information about a Neon test branch."""
+
+    branch_id: str
+    project_id: str
+    connection_string: str
+    host: str
+    parent_id: str | None = None
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add Neon-specific command line options."""
+    group = parser.getgroup("neon", "Neon database branching")
+
+    group.addoption(
+        "--neon-api-key",
+        dest="neon_api_key",
+        help="Neon API key (default: NEON_API_KEY env var)",
+    )
+    group.addoption(
+        "--neon-project-id",
+        dest="neon_project_id",
+        help="Neon project ID (default: NEON_PROJECT_ID env var)",
+    )
+    group.addoption(
+        "--neon-parent-branch",
+        dest="neon_parent_branch",
+        help="Parent branch ID to create test branches from (default: project default)",
+    )
+    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(
+        "--neon-keep-branches",
+        action="store_true",
+        dest="neon_keep_branches",
+        help="Don't delete branches after tests (useful for debugging)",
+    )
+    group.addoption(
+        "--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."
+        ),
+    )
+    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
+    )
+
+
+def _get_config_value(
+    config: pytest.Config, option: str, env_var: str, default: str | None = None
+) -> str | None:
+    """Get config value from CLI option, env var, or default."""
+    value = config.getoption(option, default=None)
+    if value is not None:
+        return value
+    return os.environ.get(env_var, default)
+
+
+def _create_neon_branch(
+    request: pytest.FixtureRequest,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Internal helper that creates and manages a Neon branch lifecycle.
+
+    This is the core implementation used by branch fixtures.
+    """
+    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")
+    parent_branch_id = _get_config_value(
+        config, "neon_parent_branch", "NEON_PARENT_BRANCH_ID"
+    )
+    database_name = _get_config_value(
+        config, "neon_database", "NEON_DATABASE", "neondb"
+    )
+    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
+    )
+    env_var_name = config.getoption("neon_env_var", default="DATABASE_URL")
+
+    if not api_key:
+        pytest.skip(
+            "Neon API key not configured (set NEON_API_KEY or use --neon-api-key)"
+        )
+    if not project_id:
+        pytest.skip(
+            "Neon project ID not configured "
+            "(set NEON_PROJECT_ID or use --neon-project-id)"
+        )
+
+    neon = NeonAPI(api_key=api_key)
+
+    # Generate unique branch name
+    branch_name = f"pytest-{os.urandom(4).hex()}"
+
+    # Build branch creation payload
+    branch_config: dict[str, Any] = {"name": branch_name}
+    if parent_branch_id:
+        branch_config["parent_id"] = parent_branch_id
+
+    # Set branch expiration (auto-delete) as a safety net for interrupted test runs
+    # This uses the branch expires_at field, not endpoint suspend_timeout
+    if branch_expiry and branch_expiry > 0:
+        expires_at = datetime.now(timezone.utc) + timedelta(seconds=branch_expiry)
+        branch_config["expires_at"] = expires_at.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    # Create branch with compute endpoint
+    result = neon.branch_create(
+        project_id=project_id,
+        branch=branch_config,
+        endpoints=[{"type": "read_write"}],
+    )
+
+    branch = result.branch
+
+    # Get endpoint_id from operations
+    # (branch_create returns operations, not endpoints directly)
+    endpoint_id = None
+    for op in result.operations:
+        if op.endpoint_id:
+            endpoint_id = op.endpoint_id
+            break
+
+    if not endpoint_id:
+        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
+    max_wait_seconds = 60
+    poll_interval = 0.5
+    waited = 0.0
+
+    while True:
+        endpoint_response = neon.endpoint(
+            project_id=project_id, endpoint_id=endpoint_id
+        )
+        endpoint = endpoint_response.endpoint
+        state = endpoint.current_state
+
+        if state == "active" or str(state) == "EndpointState.active":
+            break
+
+        if waited >= max_wait_seconds:
+            raise RuntimeError(
+                f"Timeout waiting for endpoint {endpoint_id} to become active "
+                f"(current state: {state})"
+            )
+
+        time.sleep(poll_interval)
+        waited += poll_interval
+
+    host = endpoint.host
+
+    # Reset password to get the password value
+    # (newly created branches don't expose password)
+    password_response = neon.role_password_reset(
+        project_id=project_id,
+        branch_id=branch.id,
+        role_name=role_name,
+    )
+    password = password_response.role.password
+
+    # Build connection string
+    connection_string = (
+        f"postgresql://{role_name}:{password}@{host}/{database_name}?sslmode=require"
+    )
+
+    neon_branch_info = NeonBranch(
+        branch_id=branch.id,
+        project_id=project_id,
+        connection_string=connection_string,
+        host=host,
+        parent_id=branch.parent_id,
+    )
+
+    # Set DATABASE_URL (or configured env var) for the duration of the fixture scope
+    original_env_value = os.environ.get(env_var_name)
+    os.environ[env_var_name] = connection_string
+
+    try:
+        yield neon_branch_info
+    finally:
+        # Restore original env var
+        if original_env_value is None:
+            os.environ.pop(env_var_name, None)
+        else:
+            os.environ[env_var_name] = original_env_value
+
+        # Cleanup: delete branch unless --neon-keep-branches was specified
+        if not keep_branches:
+            try:
+                neon.branch_delete(project_id=project_id, branch_id=branch.id)
+            except Exception as e:
+                # Log but don't fail tests due to cleanup issues
+                import warnings
+
+                warnings.warn(
+                    f"Failed to delete Neon branch {branch.id}: {e}",
+                    stacklevel=2,
+                )
+
+
+def _reset_branch_to_parent(branch: NeonBranch, api_key: str) -> None:
+    """Reset a branch to its parent's state using the Neon API."""
+    if not branch.parent_id:
+        raise RuntimeError(f"Branch {branch.branch_id} has no parent - cannot reset")
+
+    url = f"https://console.neon.tech/api/v2/projects/{branch.project_id}/branches/{branch.branch_id}/restore"
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+    response = requests.post(
+        url, headers=headers, json={"source_branch_id": branch.parent_id}
+    )
+    response.raise_for_status()
+
+
+@pytest.fixture(scope="module")
+def _neon_branch_for_reset(
+    request: pytest.FixtureRequest,
+) -> Generator[NeonBranch, None, None]:
+    """Internal fixture that creates a branch for reset-based isolation."""
+    yield from _create_neon_branch(request)
+
+
+@pytest.fixture(scope="function")
+def neon_branch(
+    request: pytest.FixtureRequest,
+    _neon_branch_for_reset: NeonBranch,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Provide an isolated Neon database branch for each test.
+
+    This is the primary fixture for database testing. It creates one branch per
+    test module, then resets it to the parent branch's state after each test.
+    This provides test isolation with ~0.5s overhead per test.
+
+    The branch is automatically deleted after all tests in the module complete,
+    unless --neon-keep-branches is specified. Branches also auto-expire after
+    10 minutes by default (configurable via --neon-branch-expiry) as a safety net
+    for interrupted test runs.
+
+    The connection string is automatically set in the DATABASE_URL environment
+    variable (configurable via --neon-env-var).
+
+    Requires either:
+    - NEON_API_KEY and NEON_PROJECT_ID environment variables, or
+    - --neon-api-key and --neon-project-id command line options
+
+    Yields:
+        NeonBranch: Object with branch_id, project_id, connection_string, and host.
+
+    Example:
+        def test_database_operation(neon_branch):
+            # DATABASE_URL is automatically set
+            conn_string = os.environ["DATABASE_URL"]
+            # or use directly
+            conn_string = neon_branch.connection_string
+    """
+    config = request.config
+    api_key = _get_config_value(config, "neon_api_key", "NEON_API_KEY")
+
+    yield _neon_branch_for_reset
+
+    # Reset branch to parent state after each test
+    if api_key:
+        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.fixture(scope="module")
+def neon_branch_shared(
+    request: pytest.FixtureRequest,
+) -> Generator[NeonBranch, None, None]:
+    """
+    Provide a shared Neon database branch for all tests in a module.
+
+    This fixture creates one branch per test module and shares it across all
+    tests without resetting. This is the fastest option but tests can see
+    each other's data modifications.
+
+    Use this when:
+    - Tests are read-only or don't interfere with each other
+    - You manually clean up test data within each test
+    - Maximum speed is more important than isolation
+
+    Warning: Tests in the same module will share database state. Data created
+    by one test will be visible to subsequent tests. Use `neon_branch` instead
+    if you need isolation between tests.
+
+    Yields:
+        NeonBranch: Object with branch_id, project_id, connection_string, and host.
+
+    Example:
+        def test_read_only_query(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)
+
+
+@pytest.fixture
+def neon_connection(neon_branch: NeonBranch):
+    """
+    Provide a psycopg2 connection to the test branch.
+
+    Requires the psycopg2 optional dependency:
+        pip install pytest-neon[psycopg2]
+
+    The connection is rolled back and closed after each test.
+
+    Yields:
+        psycopg2 connection object
+
+    Example:
+        def test_insert(neon_connection):
+            cur = neon_connection.cursor()
+            cur.execute("INSERT INTO users (name) VALUES ('test')")
+            neon_connection.commit()
+    """
+    try:
+        import psycopg2
+    except ImportError:
+        pytest.fail(
+            "\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+            "  MISSING DEPENDENCY: psycopg2\n"
+            "═══════════════════════════════════════════════════════════════════\n\n"
+            "  The 'neon_connection' fixture requires psycopg2.\n\n"
+            "  To fix this, install the psycopg2 extra:\n\n"
+            "      pip install pytest-neon[psycopg2]\n\n"
+            "  Or use the 'neon_branch' fixture with your own database driver:\n\n"
+            "      def test_example(neon_branch):\n"
+            "          import your_driver\n"
+            "          conn = your_driver.connect(neon_branch.connection_string)\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+        )
+
+    conn = psycopg2.connect(neon_branch.connection_string)
+    yield conn
+    conn.rollback()
+    conn.close()
+
+
+@pytest.fixture
+def neon_connection_psycopg(neon_branch: NeonBranch):
+    """
+    Provide a psycopg (v3) connection to the test branch.
+
+    Requires the psycopg optional dependency:
+        pip install pytest-neon[psycopg]
+
+    The connection is rolled back and closed after each test.
+
+    Yields:
+        psycopg connection object
+
+    Example:
+        def test_insert(neon_connection_psycopg):
+            with neon_connection_psycopg.cursor() as cur:
+                cur.execute("INSERT INTO users (name) VALUES ('test')")
+            neon_connection_psycopg.commit()
+    """
+    try:
+        import psycopg
+    except ImportError:
+        pytest.fail(
+            "\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+            "  MISSING DEPENDENCY: psycopg (v3)\n"
+            "═══════════════════════════════════════════════════════════════════\n\n"
+            "  The 'neon_connection_psycopg' fixture requires psycopg v3.\n\n"
+            "  To fix this, install the psycopg extra:\n\n"
+            "      pip install pytest-neon[psycopg]\n\n"
+            "  Or use the 'neon_branch' fixture with your own database driver:\n\n"
+            "      def test_example(neon_branch):\n"
+            "          import your_driver\n"
+            "          conn = your_driver.connect(neon_branch.connection_string)\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+        )
+
+    conn = psycopg.connect(neon_branch.connection_string)
+    yield conn
+    conn.rollback()
+    conn.close()
+
+
+@pytest.fixture
+def neon_engine(neon_branch: NeonBranch):
+    """
+    Provide a SQLAlchemy engine connected to the test branch.
+
+    Requires the sqlalchemy optional dependency:
+        pip install pytest-neon[sqlalchemy]
+
+    The engine is disposed after each test.
+
+    Yields:
+        SQLAlchemy Engine object
+
+    Example:
+        def test_query(neon_engine):
+            with neon_engine.connect() as conn:
+                result = conn.execute(text("SELECT 1"))
+    """
+    try:
+        from sqlalchemy import create_engine
+    except ImportError:
+        pytest.fail(
+            "\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+            "  MISSING DEPENDENCY: SQLAlchemy\n"
+            "═══════════════════════════════════════════════════════════════════\n\n"
+            "  The 'neon_engine' fixture requires SQLAlchemy.\n\n"
+            "  To fix this, install the sqlalchemy extra:\n\n"
+            "      pip install pytest-neon[sqlalchemy]\n\n"
+            "  Or use the 'neon_branch' fixture with your own database driver:\n\n"
+            "      def test_example(neon_branch):\n"
+            "          from sqlalchemy import create_engine\n"
+            "          engine = create_engine(neon_branch.connection_string)\n\n"
+            "═══════════════════════════════════════════════════════════════════\n"
+        )
+
+    engine = create_engine(neon_branch.connection_string)
+    yield engine
+    engine.dispose()

pytest_neon-0.2.0.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: pytest-neon
+Version: 0.2.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
+Project-URL: Issues, https://github.com/zain/pytest-neon/issues
+Author: Zain Rizvi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: branching,database,neon,postgres,pytest,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: neon-api>=0.1.0
+Requires-Dist: pytest>=7.0
+Requires-Dist: requests>=2.20
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: psycopg
+Requires-Dist: psycopg[binary]>=3.1; extra == 'psycopg'
+Provides-Extra: psycopg2
+Requires-Dist: psycopg2-binary>=2.9; extra == 'psycopg2'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# pytest-neon
+
+Pytest plugin for [Neon](https://neon.tech) database branch isolation in tests.
+
+Each test gets its own isolated database state via Neon's instant branching and reset features. Branches are automatically cleaned up after tests complete.
+
+## Features
+
+- **Isolated test environments**: Each test runs against a clean database state
+- **Fast resets**: ~0.5s per test to reset the branch (not create a new one)
+- **Automatic cleanup**: Branches are deleted after tests, with auto-expiry fallback
+- **Zero infrastructure**: No Docker, no local Postgres, no manual setup
+- **Real database testing**: Test against actual Postgres with your production schema
+- **Automatic `DATABASE_URL`**: Connection string is set in environment automatically
+- **Driver agnostic**: Bring your own driver, or use the optional convenience fixtures
+
+## Installation
+
+Core package (bring your own database driver):
+
+```bash
+pip install pytest-neon
+```
+
+With optional convenience fixtures:
+
+```bash
+# For psycopg v3 (recommended)
+pip install pytest-neon[psycopg]
+
+# For psycopg2 (legacy)
+pip install pytest-neon[psycopg2]
+
+# For SQLAlchemy
+pip install pytest-neon[sqlalchemy]
+
+# Multiple extras
+pip install pytest-neon[psycopg,sqlalchemy]
+```
+
+## Quick Start
+
+1. Set environment variables:
+
+```bash
+export NEON_API_KEY="your-api-key"
+export NEON_PROJECT_ID="your-project-id"
+```
+
+2. Write tests:
+
+```python
+def test_user_creation(neon_branch):
+    # DATABASE_URL is automatically set to the test branch
+    import psycopg  # Your own install
+
+    with psycopg.connect() as conn:  # Uses DATABASE_URL by default
+        with conn.cursor() as cur:
+            cur.execute("INSERT INTO users (email) VALUES ('test@example.com')")
+        conn.commit()
+```
+
+3. Run tests:
+
+```bash
+pytest
+```
+
+## Fixtures
+
+### `neon_branch` (default, recommended)
+
+The primary fixture for database testing. Creates one branch per test module, then resets it to the parent branch's state after each test. This provides test isolation with ~0.5s overhead per test.
+
+Returns a `NeonBranch` dataclass with:
+
+- `branch_id`: The Neon branch ID
+- `project_id`: The Neon project ID
+- `connection_string`: Full PostgreSQL connection URI
+- `host`: The database host
+
+```python
+import os
+
+def test_branch_info(neon_branch):
+    # DATABASE_URL is set automatically
+    assert os.environ["DATABASE_URL"] == neon_branch.connection_string
+
+    # Use with any driver
+    import psycopg
+    conn = psycopg.connect(neon_branch.connection_string)
+```
+
+**Performance**: ~1.5s initial setup per module + ~0.5s reset per test. For a module with 10 tests, expect ~6.5s total overhead.
+
+### `neon_branch_shared` (fastest, no isolation)
+
+Creates one branch per test module and shares it across all tests without resetting. This is the fastest option but tests can see each other's data modifications.
+
+```python
+def test_read_only_query(neon_branch_shared):
+    # Fast: no reset between tests
+    # Warning: data from other tests in this module may be visible
+    conn = psycopg.connect(neon_branch_shared.connection_string)
+```
+
+**Use this when**:
+- Tests are read-only
+- Tests don't interfere with each other
+- You manually clean up test data
+- Maximum speed is more important than isolation
+
+**Performance**: ~1.5s initial setup per module, no per-test overhead.
+
+### `neon_connection_psycopg` (psycopg v3)
+
+Convenience fixture providing a [psycopg v3](https://www.psycopg.org/psycopg3/) connection with automatic rollback and cleanup.
+
+**Requires:** `pip install pytest-neon[psycopg]`
+
+```python
+def test_insert(neon_connection_psycopg):
+    with neon_connection_psycopg.cursor() as cur:
+        cur.execute("INSERT INTO users (name) VALUES (%s)", ("test",))
+    neon_connection_psycopg.commit()
+
+    with neon_connection_psycopg.cursor() as cur:
+        cur.execute("SELECT name FROM users")
+        assert cur.fetchone()[0] == "test"
+```
+
+### `neon_connection` (psycopg2)
+
+Convenience fixture providing a [psycopg2](https://www.psycopg.org/docs/) connection with automatic rollback and cleanup.
+
+**Requires:** `pip install pytest-neon[psycopg2]`
+
+```python
+def test_insert(neon_connection):
+    cur = neon_connection.cursor()
+    cur.execute("INSERT INTO users (name) VALUES (%s)", ("test",))
+    neon_connection.commit()
+```
+
+### `neon_engine` (SQLAlchemy)
+
+Convenience fixture providing a [SQLAlchemy](https://www.sqlalchemy.org/) engine with automatic disposal.
+
+**Requires:** `pip install pytest-neon[sqlalchemy]`
+
+```python
+from sqlalchemy import text
+
+def test_query(neon_engine):
+    with neon_engine.connect() as conn:
+        result = conn.execute(text("SELECT 1"))
+        assert result.scalar() == 1
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `NEON_API_KEY` | Your Neon API key | Yes |
+| `NEON_PROJECT_ID` | Your Neon project ID | Yes |
+| `NEON_PARENT_BRANCH_ID` | Parent branch to create test branches from | No |
+| `NEON_DATABASE` | Database name (default: `neondb`) | No |
+| `NEON_ROLE` | Database role (default: `neondb_owner`) | No |
+
+### Command Line Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--neon-api-key` | Neon API key | `NEON_API_KEY` env |
+| `--neon-project-id` | Neon project ID | `NEON_PROJECT_ID` env |
+| `--neon-parent-branch` | Parent branch ID | Project default |
+| `--neon-database` | Database name | `neondb` |
+| `--neon-role` | Database role | `neondb_owner` |
+| `--neon-keep-branches` | Don't delete branches after tests | `false` |
+| `--neon-branch-expiry` | Branch auto-expiry in seconds | `600` (10 min) |
+| `--neon-env-var` | Environment variable for connection string | `DATABASE_URL` |
+
+Examples:
+
+```bash
+# Keep branches for debugging
+pytest --neon-keep-branches
+
+# Disable auto-expiry
+pytest --neon-branch-expiry=0
+
+# Use a different env var
+pytest --neon-env-var=TEST_DATABASE_URL
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install -e .[psycopg,dev]
+
+      - name: Run tests
+        env:
+          NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+          NEON_PROJECT_ID: ${{ secrets.NEON_PROJECT_ID }}
+        run: pytest
+```
+
+## How It Works
+
+1. Before each test module, the plugin creates a new Neon branch from your parent branch
+2. `DATABASE_URL` is set to point to the new branch
+3. Tests run against this isolated branch with full access to your schema and data
+4. After each test, the branch is reset to its parent state (~0.5s)
+5. After all tests in the module complete, the branch is deleted
+6. As a safety net, branches auto-expire after 10 minutes even if cleanup fails
+
+Branches use copy-on-write storage, so you only pay for data that differs from the parent branch.
+
+## Troubleshooting
+
+### "psycopg not installed" or "psycopg2 not installed"
+
+The convenience fixtures require their respective drivers. Install the appropriate extra:
+
+```bash
+# For neon_connection_psycopg fixture
+pip install pytest-neon[psycopg]
+
+# For neon_connection fixture
+pip install pytest-neon[psycopg2]
+
+# For neon_engine fixture
+pip install pytest-neon[sqlalchemy]
+```
+
+Or use the core `neon_branch` fixture with your own driver:
+
+```python
+def test_example(neon_branch):
+    import my_preferred_driver
+    conn = my_preferred_driver.connect(neon_branch.connection_string)
+```
+
+### "Neon API key not configured"
+
+Set the `NEON_API_KEY` environment variable or use the `--neon-api-key` CLI option.
+
+### "Neon project ID not configured"
+
+Set the `NEON_PROJECT_ID` environment variable or use the `--neon-project-id` CLI option.
+
+## License
+
+MIT

pytest_neon-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_neon/__init__.py,sha256=3dk41NZmdfWWpfqyf8I1T7UsMbt3hjlRMPrfC1k_W5Y,398
+pytest_neon/plugin.py,sha256=-7NHdQ-nqfR-ZQXFmLBu_vV445LTLJ44UXnkQPtCgOQ,17217
+pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_neon-0.2.0.dist-info/METADATA,sha256=xremaYd4xWifbUUMB88IdltsK5d_wsQmZq_zDpOrxkw,9496
+pytest_neon-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pytest_neon-0.2.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
+pytest_neon-0.2.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
+pytest_neon-0.2.0.dist-info/RECORD,,

pytest_neon-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_neon-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+neon = pytest_neon.plugin

pytest_neon-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zain Rizvi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.