pytest-neon 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

pytest_neon/__init__.py

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

pytest_neon/plugin.py

@@ -30,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",
@@ -51,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(
@@ -70,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."
@@ -79,45 +77,114 @@ 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(
     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
 
-    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"
+    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"
+    )
+    # 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(
-        config, "neon_database", "NEON_DATABASE", "neondb"
+        config, "neon_database", "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
+    role_name = _get_config_value(
+        config, "neon_role", "NEON_ROLE", "neon_role", "neondb_owner"
+    )
+
+    # 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")
+
+    # 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"
     )
-    env_var_name = config.getoption("neon_env_var", default="DATABASE_URL")
 
     if not api_key:
         pytest.skip(
@@ -132,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}
@@ -258,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")
@@ -301,7 +442,7 @@ 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:
@@ -330,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.
@@ -338,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
@@ -355,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.3.0.dist-info → pytest_neon-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-neon
-Version: 0.3.0
+Version: 0.5.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
@@ -199,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
@@ -237,6 +322,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

pytest_neon-0.5.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_neon/__init__.py,sha256=GmCMNwXFausX8ZucJLRZmywVEc2IamMolGhQ3JIvqpk,398
+pytest_neon/plugin.py,sha256=1TukuxsBQ88NlgQS6qosUarIrCc94apMrwvVrYt9IOg,23241
+pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_neon-0.5.0.dist-info/METADATA,sha256=UsUvPOuacr1cs2sAjWDhsQJfoGnKFswo3Td3m5unuNw,13532
+pytest_neon-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pytest_neon-0.5.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
+pytest_neon-0.5.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
+pytest_neon-0.5.0.dist-info/RECORD,,

pytest_neon-0.3.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pytest_neon/__init__.py,sha256=RftEKwHM37DDwxA_oVN00DMXTh_3tlpaz6LbbN_IOYA,398
-pytest_neon/plugin.py,sha256=A4eTJIV6XKQv4AIBizhg5qRDrvB_Hfx4ysTerjROHUg,17938
-pytest_neon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pytest_neon-0.3.0.dist-info/METADATA,sha256=JmC3wuJSupLxVqeDlgzpUyYYpawRArzGj96N2CtcTE0,10555
-pytest_neon-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-pytest_neon-0.3.0.dist-info/entry_points.txt,sha256=5U88Idj_G8-PSDb9VF3OwYFbGLHnGOo_GxgYvi0dtXw,37
-pytest_neon-0.3.0.dist-info/licenses/LICENSE,sha256=aKKp_Ex4WBHTByY4BhXJ181dzB_qYhi2pCUmZ7Spn_0,1067
-pytest_neon-0.3.0.dist-info/RECORD,,