pytest-alembic

0.12.1 · active · verified Sat Apr 11

pytest-alembic is a pytest plugin designed to verify Alembic database migrations. It provides fixtures and test functions to ensure that migrations can be applied and reverted correctly, that the database schema remains consistent, and that the migration history is valid. The library is actively maintained, with frequent minor releases addressing compatibility and bug fixes, typically on a monthly or bi-monthly basis.

Warnings

breaking Older versions of `pytest-alembic` (specifically prior to `0.11.0`) have fixture definition incompatibilities when used with `pytest` version `8.x.x` or higher.
Fix: Upgrade `pytest-alembic` to version `0.11.0` or newer to ensure compatibility with `pytest >= 8.0.0`.
gotcha When using `pyproject.toml` for Alembic configuration (instead of `alembic.ini`), versions of `pytest-alembic` prior to `0.12.1` may not correctly parse the configuration.
Fix: Upgrade `pytest-alembic` to version `0.12.1` or newer for proper handling of `pyproject.toml` based Alembic configurations.
gotcha Early versions of `pytest-alembic` might have compatibility issues with SQLAlchemy 2.0's new API. While general support exists, specific edge cases could arise.
Fix: Ensure you are using `pytest-alembic` version `0.10.7` or newer for robust SQLAlchemy 2.0 compatibility.
gotcha In versions prior to `0.12.0`, `pytest-alembic` might not correctly handle branched revisions, potentially leading to errors when upgrading a database with a complex, branched migration history.
Fix: Upgrade `pytest-alembic` to version `0.12.0` or newer to ensure proper handling and testing of branched revisions, where each branch head is upgraded individually.
deprecated The `--pytest-alembic-tests-folder` CLI option (or its programmatic equivalent) was removed/refactored in `v0.10.2`. Relying on it in older test setups may cause issues.
Fix: Review your `conftest.py` and pytest command-line arguments. The plugin now automatically discovers tests by default or uses the `pytest_alembic_test_paths` hook to configure test registration paths.

Install

pip install pytest-alembic Install stable version

Imports

Config
```
from alembic.config import Config
```
Required for configuring Alembic within pytest fixtures.
create_engine
```
from sqlalchemy import create_engine
```
Required for providing a SQLAlchemy engine to Alembic fixtures.
AlembicRunner
```
from pytest_alembic.runner import AlembicRunner
```
Used for type hinting the `alembic_runner` fixture, or for programmatic interaction with migration tests.
create_alembic_fixture
```
from pytest_alembic.util import create_alembic_fixture
```
While `test_single_up_down_migration` exists, `create_alembic_fixture` is the recommended way to generate parametrized tests for individual migrations.

Quickstart

To get started, define `alembic_config` and `alembic_engine` fixtures in your `conftest.py`. The `alembic_config` fixture should point to your Alembic configuration file and script location. The `alembic_engine` fixture should return a SQLAlchemy engine configured for a test database. Once these are set, you can write pytest functions that use the `alembic_runner` fixture to interact with and test your migrations. Run pytest with the plugin installed, and it will automatically discover tests.

import pytest
from alembic.config import Config
from sqlalchemy import create_engine
from pytest_alembic.runner import AlembicRunner

# conftest.py
# This file should be in your tests directory or root project directory

@pytest.fixture(scope="session")
def alembic_config():
    """Override this fixture to provide your alembic configuration."""
    # Adjust 'alembic.ini' and 'migrations' to your project's paths
    config = Config("alembic.ini")
    config.set_main_option("script_location", "migrations")
    return config

@pytest.fixture(scope="session")
def alembic_engine(alembic_config):
    """Override this fixture to provide your database engine."""
    # Use an in-memory SQLite database for quick tests or a separate test database
    # For real applications, consider a dedicated test database service.
    return create_engine("sqlite:///:memory/")

# test_migrations.py
# This file would be in your tests directory

def test_alembic_history_consistent(alembic_runner: AlembicRunner):
    """Verify that the migration history is linear and consistent."""
    alembic_runner.check_current_revision_is_linear()

def test_all_migrations_can_upgrade_and_downgrade(alembic_runner: AlembicRunner):
    """Verify that all migrations can be applied and reverted successfully."""
    alembic_runner.upgrade_downgrade()

view raw JSON →