Registry / testing / pytest-alembic

pytest-alembic

JSON →
library0.12.1pypypi✓ verified 25d ago

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.

pip install pytest-alembic
INSTALL
IMPORT
SIG · PYTEST-ALEMBIC
P
pytest-alembic
testingpythonv0.12.1
Install
4.8s avg
Import
1192ms
Disk
59MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.12.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.240s · 59.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.8s · import 1.144s · 58MB
59MB installed
● package 59MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
from pytest_alembic.tests import test_single_up_down_migration
While `test_single_up_down_migration` exists, `create_alembic_fixture` is the recommended way to generate parametrized tests for individual migrations.

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()
Debug
Known issues
breakingOlder 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`.
affects: <0.11.0
gotchaWhen 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.
affects: <0.12.1
gotchaEarly 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.
affects: <0.10.7
gotchaIn 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.
affects: <0.12.0
deprecatedThe `--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.
affects: <0.10.2
Upgrade
Version history
0.12.1latest on PyPI · released May 27, 2025
Audit
Dependencies
pytestrequiredIt is a pytest plugin and integrates directly with pytest's test discovery and execution.
alembicrequiredIt tests Alembic database migrations and requires Alembic to be installed.
sqlalchemyrequiredAlembic depends on SQLAlchemy for database interaction.
Agent activity
8 hits · last 30 days
node
6
Resources
pytest-alembic — pip install pytest-alembic · libregistry