pytest-neon 0.2.0__tar.gz

pytest_neon-0.2.0/.env.example

@@ -0,0 +1,4 @@
+# Copy this file to .env and fill in your Neon API key
+# Get your API key from: https://console.neon.tech/app/settings/api-keys
+
+NEON_API_KEY=your-api-key-here

pytest_neon-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,76 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,psycopg]"
+
+      - name: Run unit tests
+        run: pytest tests/ --ignore=tests/test_integration.py -v
+
+  integration:
+    runs-on: ubuntu-latest
+    # Only run integration tests on main branch pushes to avoid using API quota on PRs
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,psycopg]"
+
+      - name: Run integration tests
+        env:
+          NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+          NEON_PROJECT_ID: ${{ secrets.NEON_PROJECT_ID }}
+        run: pytest tests/test_integration.py -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff check
+        run: ruff check .
+
+      - name: Run ruff format check
+        run: ruff format --check .

pytest_neon-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# mypy
+.mypy_cache/
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db

pytest_neon-0.2.0/.neon

@@ -0,0 +1,3 @@
+{
+  "projectId": "frosty-violet-45543831"
+}

pytest_neon-0.2.0/CLAUDE.md

@@ -0,0 +1,45 @@
+# Claude Code Instructions for pytest-neon
+
+## 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.
+
+## 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
+- **Convenience fixtures**: `neon_connection`, `neon_connection_psycopg`, `neon_engine` - Optional, require extras
+
+## Dependencies
+
+- Core: `pytest`, `neon-api` only
+- Optional extras: `psycopg2`, `psycopg`, `sqlalchemy` - for convenience fixtures
+
+## Important Patterns
+
+### Fixture Scopes
+- `neon_branch`: `scope="module"` - one branch per test file
+- 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.
+
+### 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.
+
+## Commit Messages
+- Do NOT add Claude attribution or Co-Authored-By lines
+- Keep commits clean and descriptive
+
+## Testing
+
+Tests in `tests/` use `pytester` for testing pytest plugins. The plugin itself can be tested without a real Neon connection by mocking `NeonAPI`.
+
+## Publishing
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+Package name on PyPI: `pytest-neon`

pytest_neon-0.2.0/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.

pytest_neon-0.2.0/PKG-INFO

@@ -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