pytest-neon 2.3.2__tar.gz → 3.0.1__tar.gz

{pytest_neon-2.3.2 → pytest_neon-3.0.1}/.gitignore

@@ -37,3 +37,6 @@ htmlcov/
 # OS
 .DS_Store
 Thumbs.db
+
+# bv (beads viewer) local config and caches
+.bv/

pytest_neon-3.0.1/CLAUDE.md

@@ -0,0 +1,167 @@
+# Claude Code Instructions for pytest-neon
+
+## Understanding the Plugin
+
+Read `README.md` for complete documentation on how to use this plugin, including fixtures, configuration options, and migration support.
+
+## Project Overview
+
+This is a pytest plugin that provides Neon database branches for integration testing. All tests share a single branch per session.
+
+## Key Architecture
+
+- **Entry point**: `src/pytest_neon/plugin.py` - Contains all fixtures and pytest hooks
+- **Test branch fixture**: `_neon_test_branch` - Session-scoped, single branch for all tests
+- **User migration hook**: `neon_apply_migrations` - Session-scoped no-op, users override to run migrations
+- **Main fixture**: `neon_branch` - Session-scoped, shared branch for all tests
+- **Convenience fixtures**: `neon_connection`, `neon_connection_psycopg`, `neon_engine` - Optional, require extras
+
+## Branch Hierarchy
+
+```
+Parent Branch (configured or project default)
+    └── Test Branch (session-scoped, 10-min expiry)
+            ↑ migrations run here ONCE, all tests share this
+```
+
+## Dependencies
+
+- Core: `pytest`, `neon-api`, `requests`, `filelock`
+- Optional extras: `psycopg2`, `psycopg`, `sqlalchemy` - for convenience fixtures
+
+## Important Patterns
+
+### Modular Architecture
+
+The plugin uses a service-oriented architecture for testability:
+
+- **NeonConfig**: Dataclass for configuration extraction from pytest config
+- **NeonBranchManager**: Manages Neon API operations (branch create/delete)
+- **XdistCoordinator**: Handles worker synchronization with file locks and JSON caching
+- **EnvironmentManager**: Manages DATABASE_URL environment variable lifecycle
+
+### Fixture Scopes
+- `_neon_config`: `scope="session"` - Configuration extracted from pytest config
+- `_neon_branch_manager`: `scope="session"` - Branch lifecycle manager
+- `_neon_xdist_coordinator`: `scope="session"` - Worker synchronization
+- `_neon_test_branch`: `scope="session"` - Internal, creates branch, yields (branch, is_creator)
+- `neon_apply_migrations`: `scope="session"` - User overrides to run migrations
+- `neon_branch`: `scope="session"` - User-facing, shared branch for all tests
+- Connection fixtures: `scope="function"` - Fresh connection per test
+
+### Environment Variable Handling
+The `EnvironmentManager` class handles `DATABASE_URL` lifecycle:
+- Sets environment variable when fixture starts
+- Saves original value for restoration
+- Restores original value (or removes) when fixture ends
+
+### xdist Worker Synchronization
+The `XdistCoordinator` handles sharing resources across workers:
+- Uses file locks (`filelock`) for coordination
+- Stores shared resource data in JSON files
+- `coordinate_resource()` ensures only one worker creates shared resources
+- `wait_for_signal()` / `send_signal()` for migration synchronization
+- All workers share ONE branch (no per-worker branches)
+
+### 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.
+
+## Test Isolation
+
+Since all tests share the same branch, users should implement their own isolation:
+1. **Transaction rollback** - Recommended for most cases
+2. **Table truncation** - For cases where transactions aren't suitable
+3. **Unique identifiers** - Use UUIDs to avoid conflicts
+
+## Documentation
+
+Important help text should be documented in BOTH:
+1. **README.md** - Full user-facing documentation
+2. **Module/fixture docstrings** - So `help(pytest_neon)` shows useful info
+
+The module docstring in `plugin.py` should include key usage notes. Keep docstrings and README in sync.
+
+## Commit Messages
+- Do NOT add Claude attribution or Co-Authored-By lines
+- Keep commits clean and descriptive
+
+## Testing
+
+Run tests with:
+```bash
+uv run pytest tests/ -v
+```
+
+Tests in `tests/` use `pytester` for testing pytest plugins. The plugin itself can be tested without a real Neon connection by mocking `NeonAPI`.
+
+## Publishing
+
+**Always use the GitHub Actions release workflow** - do not manually bump versions:
+1. Go to Actions → Release → Run workflow
+2. Choose patch/minor/major
+3. Workflow bumps version, commits, tags, and publishes to PyPI
+
+Package name on PyPI: `pytest-neon`
+
+<!-- bv-agent-instructions-v1 -->
+
+---
+
+## Beads Workflow Integration
+
+This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
+
+### Essential Commands
+
+```bash
+# View issues (launches TUI - avoid in automated sessions)
+bv
+
+# CLI commands for agents (use these instead)
+bd ready              # Show issues ready to work (no blockers)
+bd list --status=open # All open issues
+bd show <id>          # Full issue details with dependencies
+bd create --title="..." --type=task --priority=2
+bd update <id> --status=in_progress
+bd close <id> --reason="Completed"
+bd close <id1> <id2>  # Close multiple issues at once
+bd sync               # Commit and push changes
+```
+
+### Workflow Pattern
+
+1. **Start**: Run `bd ready` to find actionable work
+2. **Claim**: Use `bd update <id> --status=in_progress`
+3. **Work**: Implement the task
+4. **Complete**: Use `bd close <id>`
+5. **Sync**: Always run `bd sync` at session end
+
+### Key Concepts
+
+- **Dependencies**: Issues can block other issues. `bd ready` shows only unblocked work.
+- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
+- **Types**: task, bug, feature, epic, question, docs
+- **Blocking**: `bd dep add <issue> <depends-on>` to add dependencies
+
+### Session Protocol
+
+**Before ending any session, run this checklist:**
+
+```bash
+git status              # Check what changed
+git add <files>         # Stage code changes
+bd sync                 # Commit beads changes
+git commit -m "..."     # Commit code
+bd sync                 # Commit any new beads changes
+git push                # Push to remote
+```
+
+### Best Practices
+
+- Check `bd ready` at session start to find available work
+- Update status as you work (in_progress → closed)
+- Create new issues with `bd create` when you discover tasks
+- Use descriptive titles and set appropriate priority/type
+- Always `bd sync` before ending session
+
+<!-- end-bv-agent-instructions -->

pytest_neon-3.0.1/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: pytest-neon
+Version: 3.0.1
+Summary: Pytest plugin for Neon database branch isolation in tests
+Project-URL: Homepage, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Repository, https://github.com/ZainRizvi/pytest-neon
+Project-URL: Issues, https://github.com/ZainRizvi/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: filelock>=3.0
+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: psycopg2-binary>=2.9; extra == 'dev'
+Requires-Dist: psycopg[binary]>=3.1; 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'
+Requires-Dist: sqlalchemy>=2.0; 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
+
+[![Tests](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml/badge.svg)](https://github.com/ZainRizvi/pytest-neon/actions/workflows/tests.yml)
+
+A pytest plugin that provides Neon database branches for integration testing.
+
+## Features
+
+- **Automatic branch management**: Creates a test branch at session start, deletes at end
+- **Branch expiry**: Auto-cleanup via 10-minute expiry (crash-safe)
+- **Migration support**: Run migrations once, all tests share the migrated schema
+- **pytest-xdist support**: All workers share a single branch
+- **Minimal API calls**: Single branch creation reduces rate limiting issues
+
+## Installation
+
+```bash
+pip install pytest-neon
+
+# With optional database drivers
+pip install pytest-neon[psycopg]     # psycopg v3 support
+pip install pytest-neon[psycopg2]    # psycopg2 support
+pip install pytest-neon[sqlalchemy]  # SQLAlchemy engine support
+```
+
+## Quick Start
+
+1. Set environment variables:
+```bash
+export NEON_API_KEY="your-api-key"
+export NEON_PROJECT_ID="your-project-id"
+```
+
+2. Use the `neon_branch` fixture in your tests:
+```python
+def test_query_users(neon_branch):
+    import psycopg
+    with psycopg.connect(neon_branch.connection_string) as conn:
+        result = conn.execute("SELECT * FROM users").fetchall()
+        assert len(result) >= 0
+```
+
+The `DATABASE_URL` environment variable is automatically set when the fixture is active.
+
+## Fixtures
+
+### `neon_branch` (session-scoped)
+
+The main fixture providing a shared Neon branch for all tests.
+
+```python
+def test_example(neon_branch):
+    # neon_branch.branch_id - Neon branch ID
+    # neon_branch.project_id - Neon project ID
+    # neon_branch.connection_string - PostgreSQL connection string
+    # neon_branch.host - Database host
+    pass
+```
+
+**Important**: All tests share the same branch. Data written by one test is visible to subsequent tests. See [Test Isolation](#test-isolation) for patterns to handle this.
+
+### `neon_apply_migrations` (session-scoped)
+
+Override this fixture to run migrations before tests:
+
+```python
+# conftest.py
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_test_branch):
+    """Run database migrations."""
+    import subprocess
+    subprocess.run(["alembic", "upgrade", "head"], check=True)
+```
+
+Or with Django:
+```python
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_test_branch):
+    from django.core.management import call_command
+    call_command("migrate", "--noinput")
+```
+
+Or with raw SQL:
+```python
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_test_branch):
+    import psycopg
+    branch, is_creator = _neon_test_branch
+    with psycopg.connect(branch.connection_string) as conn:
+        with open("schema.sql") as f:
+            conn.execute(f.read())
+        conn.commit()
+```
+
+### Connection Fixtures (Optional)
+
+These require extra dependencies:
+
+**`neon_connection`** - psycopg2 connection (requires `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_connection_psycopg`** - psycopg v3 connection (requires `pytest-neon[psycopg]`)
+```python
+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()
+```
+
+**`neon_engine`** - SQLAlchemy engine (requires `pytest-neon[sqlalchemy]`)
+```python
+def test_query(neon_engine):
+    from sqlalchemy import text
+    with neon_engine.connect() as conn:
+        result = conn.execute(text("SELECT 1"))
+```
+
+## Test Isolation
+
+Since all tests share a single branch, you may need to handle test isolation yourself. Here are recommended patterns:
+
+### Transaction Rollback (Recommended)
+
+```python
+@pytest.fixture
+def db_transaction(neon_branch):
+    """Provide a database transaction that rolls back after each test."""
+    import psycopg
+    conn = psycopg.connect(neon_branch.connection_string)
+    conn.execute("BEGIN")
+    yield conn
+    conn.execute("ROLLBACK")
+    conn.close()
+
+def test_insert(db_transaction):
+    db_transaction.execute("INSERT INTO users (name) VALUES ('test')")
+    # Automatically rolled back - next test won't see this
+```
+
+### Table Truncation
+
+```python
+@pytest.fixture(autouse=True)
+def clean_tables(neon_branch):
+    """Clean up test data after each test."""
+    yield
+    import psycopg
+    with psycopg.connect(neon_branch.connection_string) as conn:
+        conn.execute("TRUNCATE users, orders CASCADE")
+        conn.commit()
+```
+
+### Unique Identifiers
+
+```python
+import uuid
+
+def test_create_user(neon_branch):
+    unique_id = uuid.uuid4().hex[:8]
+    email = f"test_{unique_id}@example.com"
+    # Create user with unique email - no conflicts with other tests
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NEON_API_KEY` | Neon API key (required) |
+| `NEON_PROJECT_ID` | Neon project ID (required) |
+| `NEON_PARENT_BRANCH_ID` | Parent branch to create test branches from |
+| `NEON_DATABASE` | Database name (default: `neondb`) |
+| `NEON_ROLE` | Database role (default: `neondb_owner`) |
+
+### Command Line Options
+
+```bash
+pytest --neon-api-key=KEY --neon-project-id=ID
+pytest --neon-parent-branch=BRANCH_ID
+pytest --neon-database=mydb --neon-role=myrole
+pytest --neon-keep-branches  # Don't delete branches (for debugging)
+pytest --neon-branch-expiry=600  # Branch expiry in seconds (default: 600)
+pytest --neon-env-var=CUSTOM_URL  # Use custom env var instead of DATABASE_URL
+```
+
+### pytest.ini / pyproject.toml
+
+```ini
+[pytest]
+neon_api_key = your-api-key
+neon_project_id = your-project-id
+neon_parent_branch = br-parent-123
+neon_database = mydb
+neon_role = myrole
+neon_keep_branches = false
+neon_branch_expiry = 600
+neon_env_var = DATABASE_URL
+```
+
+## Architecture
+
+```
+Parent Branch (configured or project default)
+    └── Test Branch (session-scoped, 10-min expiry)
+            ↑ migrations run here ONCE, all tests share this
+```
+
+The plugin creates exactly **one branch per test session**:
+1. First test triggers branch creation with auto-expiry
+2. Migrations run once (if `neon_apply_migrations` is overridden)
+3. All tests share the same branch
+4. Branch deleted at session end (plus auto-expiry as safety net)
+
+### pytest-xdist Support
+
+When running with pytest-xdist, all workers share the same branch:
+- First worker creates the branch and runs migrations
+- Other workers wait for migrations to complete
+- All workers see the same database state
+
+```bash
+pytest -n 4  # 4 workers, all sharing one branch
+```
+
+## Branch Naming
+
+Branches are automatically named to help identify their source:
+
+```
+pytest-[git-branch]-[random]-test
+```
+
+**Examples:**
+- `pytest-main-a1b2-test` - Test branch from `main`
+- `pytest-feature-auth-c3d4-test` - Test branch from `feature/auth`
+- `pytest-a1b2-test` - When not in a git repo
+
+The git branch name is sanitized (only `a-z`, `0-9`, `-`, `_` allowed) and truncated to 15 characters.
+
+## Upgrading from v2.x
+
+Version 3.0 simplifies the plugin significantly. If you're upgrading from v2.x:
+
+### Removed Fixtures
+
+These fixtures have been removed:
+- `neon_branch_readonly` → use `neon_branch`
+- `neon_branch_readwrite` → use `neon_branch`
+- `neon_branch_isolated` → use `neon_branch` + transaction rollback
+- `neon_branch_dirty` → use `neon_branch`
+- `neon_branch_shared` → use `neon_branch`
+
+### Migration Hook Change
+
+The migration hook now uses `_neon_test_branch` instead of `_neon_migration_branch`:
+
+```python
+# Before (v2.x)
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_migration_branch):
+    ...
+
+# After (v3.x)
+@pytest.fixture(scope="session")
+def neon_apply_migrations(_neon_test_branch):
+    ...
+```
+
+### No Per-Test Reset
+
+The v2.x `neon_branch_isolated` fixture reset the branch after each test. In v3.x, there's no automatic reset. Use transaction rollback or cleanup fixtures for test isolation.
+
+## Troubleshooting
+
+### Rate Limiting
+
+The plugin includes automatic retry with exponential backoff for Neon API rate limits. If you're hitting rate limits:
+- The plugin creates only 1-2 API calls per session (create + delete)
+- Consider increasing `--neon-branch-expiry` to reduce cleanup calls
+
+### Stale Connections (SQLAlchemy)
+
+If using SQLAlchemy with connection pooling, use `pool_pre_ping=True`:
+```python
+engine = create_engine(DATABASE_URL, pool_pre_ping=True)
+```
+
+This is a best practice for any cloud database where connections can be terminated externally.
+
+### Branch Not Deleted
+
+If a test run crashes, the branch auto-expires after 10 minutes (configurable). You can also use `--neon-keep-branches` to prevent deletion for debugging.
+
+## License
+
+MIT