{"id":4210,"library":"pytest-alembic","title":"pytest-alembic","description":"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.","status":"active","version":"0.12.1","language":"en","source_language":"en","source_url":"https://github.com/schireson/pytest-alembic","tags":["pytest","alembic","database","migrations","testing","sqlalchemy"],"install":[{"cmd":"pip install pytest-alembic","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"It is a pytest plugin and integrates directly with pytest's test discovery and execution.","package":"pytest","optional":false},{"reason":"It tests Alembic database migrations and requires Alembic to be installed.","package":"alembic","optional":false},{"reason":"Alembic depends on SQLAlchemy for database interaction.","package":"sqlalchemy","optional":false}],"imports":[{"note":"Required for configuring Alembic within pytest fixtures.","symbol":"Config","correct":"from alembic.config import Config"},{"note":"Required for providing a SQLAlchemy engine to Alembic fixtures.","symbol":"create_engine","correct":"from sqlalchemy import create_engine"},{"note":"Used for type hinting the `alembic_runner` fixture, or for programmatic interaction with migration tests.","symbol":"AlembicRunner","correct":"from pytest_alembic.runner import AlembicRunner"},{"note":"While `test_single_up_down_migration` exists, `create_alembic_fixture` is the recommended way to generate parametrized tests for individual migrations.","wrong":"from pytest_alembic.tests import test_single_up_down_migration","symbol":"create_alembic_fixture","correct":"from pytest_alembic.util import create_alembic_fixture"}],"quickstart":{"code":"import pytest\nfrom alembic.config import Config\nfrom sqlalchemy import create_engine\nfrom pytest_alembic.runner import AlembicRunner\n\n# conftest.py\n# This file should be in your tests directory or root project directory\n\n@pytest.fixture(scope=\"session\")\ndef alembic_config():\n    \"\"\"Override this fixture to provide your alembic configuration.\"\"\"\n    # Adjust 'alembic.ini' and 'migrations' to your project's paths\n    config = Config(\"alembic.ini\")\n    config.set_main_option(\"script_location\", \"migrations\")\n    return config\n\n@pytest.fixture(scope=\"session\")\ndef alembic_engine(alembic_config):\n    \"\"\"Override this fixture to provide your database engine.\"\"\"\n    # Use an in-memory SQLite database for quick tests or a separate test database\n    # For real applications, consider a dedicated test database service.\n    return create_engine(\"sqlite:///:memory/\")\n\n# test_migrations.py\n# This file would be in your tests directory\n\ndef test_alembic_history_consistent(alembic_runner: AlembicRunner):\n    \"\"\"Verify that the migration history is linear and consistent.\"\"\"\n    alembic_runner.check_current_revision_is_linear()\n\ndef test_all_migrations_can_upgrade_and_downgrade(alembic_runner: AlembicRunner):\n    \"\"\"Verify that all migrations can be applied and reverted successfully.\"\"\"\n    alembic_runner.upgrade_downgrade()\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade `pytest-alembic` to version `0.11.0` or newer to ensure compatibility with `pytest >= 8.0.0`.","message":"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.","severity":"breaking","affected_versions":"<0.11.0"},{"fix":"Upgrade `pytest-alembic` to version `0.12.1` or newer for proper handling of `pyproject.toml` based Alembic configurations.","message":"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.","severity":"gotcha","affected_versions":"<0.12.1"},{"fix":"Ensure you are using `pytest-alembic` version `0.10.7` or newer for robust SQLAlchemy 2.0 compatibility.","message":"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.","severity":"gotcha","affected_versions":"<0.10.7"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.12.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<0.10.2"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}