[](https://codecov.io/gh/schireson/pytest-alembic)
[](https://pytest-alembic.readthedocs.io/en/latest/?badge=latest)
See the full documentation [here](https://pytest-alembic.readthedocs.io/en/latest/).
## Introduction
A pytest plugin to test alembic migrations (with default tests) and
which enables you to write tests specific to your migrations.
```bash
$ pip install pytest-alembic
$ pytest --test-alembic
...
::pytest_alembic/tests/model_definitions_match_ddl <- . PASSED [ 25%]
::pytest_alembic/tests/single_head_revision <- . PASSED [ 50%]
::pytest_alembic/tests/up_down_consistency <- . PASSED [ 75%]
::pytest_alembic/tests/upgrade <- . PASSED [100%]
============================== 4 passed in 2.32s ===============================
```
## The pitch
Have you ever merged a change to your models and you forgot to generate
a migration?
Have you ever written a migration only to realize that it fails when
there’s data in the table?
Have you ever written a **perfect** migration only to merge it and later
find out that someone else merged also merged a migration and your CD is
now broken!?
`pytest-alembic` is meant to (with a little help) solve all these
problems and more. Note, due to a few different factors, there **may**
be some [minimal required
setup](http://pytest-alembic.readthedocs.io/en/latest/setup.html);
however most of it is boilerplate akin to the setup required for alembic
itself.
### Built-in Tests
- **test_single_head_revision**
Assert that there only exists one head revision.
We’re not sure what realistic scenario involves a diverging history to
be desirable. We have only seen it be the result of uncaught merge
conflicts resulting in a diverged history, which lazily breaks during
deployment.
- **test_upgrade**
Assert that the revision history can be run through from base to head.
- **test_model_definitions_match_ddl**
Assert that the state of the migrations matches the state of the
models describing the DDL.
In general, the set of migrations in the history should coalesce into
DDL which is described by the current set of models. Therefore, a call
to `revision --autogenerate` should always generate an empty migration
(e.g. find no difference between your database (i.e. migrations
history) and your models).
- **test_up_down_consistency**
Assert that all downgrades succeed.
While downgrading may not be lossless operation data-wise, there’s a
theory of database migrations that says that the revisions in
existence for a database should be able to go from an entirely blank
schema to the finished product, and back again.
- [Experimental
tests](http://pytest-alembic.readthedocs.io/en/latest/experimental_tests.html)
- all_models_register_on_metadata
Assert that all defined models are imported statically.
Prevents scenarios in which the minimal import of your models in your `env.py`
does not import all extant models, leading alembic to not autogenerate all
your models, or (worse!) suggest the deletion of tables which should still exist.
- downgrade_leaves_no_trace
Assert that there is no difference between the state of the database pre/post downgrade.
In essence this is a much more strict version of `test_up_down_consistency`,
where the state of a MetaData before and after a downgrade are identical as
far as alembic (autogenerate) is concerned.
These tests will need to be enabled manually because their semantics or API are
not yet guaranteed to stay the same. See the linked docs for more details!
Let us know if you have any ideas for more built-in tests which would be
generally useful for most alembic histories!
### Custom Tests
For more information, see the docs for [custom
tests](http://pytest-alembic.readthedocs.io/en/latest/custom_tests.html)
(example below) or [custom static
data](http://pytest-alembic.readthedocs.io/en/latest/custom_data.html)
(to be inserted automatically before a given revision).
Sometimes when writing a particularly gnarly data migration, it helps to
be able to practice a little timely TDD, since there’s always the
potential you’ll trash your actual production data.
With `pytest-alembic`, you can write tests directly, in the same way
that you would normally, through the use of the `alembic_runner`
fixture.
```python
def test_gnarly_migration_xyz123(alembic_engine, alembic_runner):
# Migrate up to, but not including this new migration
alembic_runner.migrate_up_before('xyz123')
# Perform some very specific data setup, because this migration is sooooo complex.
# ...
alembic_engine.execute(table.insert(id=1, name='foo'))
alembic_runner.migrate_up_one()
```
`alembic_runner` has a number of methods designed to make it convenient
to change the state of your database up, down, and all around.
## Installing
```bash
pip install "pytest-alembic"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/schireson/pytest-alembic",
"name": "pytest-alembic",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "pytest, sqlalchemy, alembic, migration, revision",
"author": "Dan Cardin",
"author_email": "ddcardin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7e/7b/cd3c7a07dcdf01d66ed14aa8cea89f5877c3d0a8e657be196f87ac38dfd1/pytest_alembic-0.11.1.tar.gz",
"platform": null,
"description": "\n[](https://codecov.io/gh/schireson/pytest-alembic)\n[](https://pytest-alembic.readthedocs.io/en/latest/?badge=latest)\n\nSee the full documentation [here](https://pytest-alembic.readthedocs.io/en/latest/).\n\n## Introduction\n\nA pytest plugin to test alembic migrations (with default tests) and\nwhich enables you to write tests specific to your migrations.\n\n```bash\n$ pip install pytest-alembic\n$ pytest --test-alembic\n\n...\n::pytest_alembic/tests/model_definitions_match_ddl <- . PASSED [ 25%]\n::pytest_alembic/tests/single_head_revision <- . PASSED [ 50%]\n::pytest_alembic/tests/up_down_consistency <- . PASSED [ 75%]\n::pytest_alembic/tests/upgrade <- . PASSED [100%]\n\n============================== 4 passed in 2.32s ===============================\n```\n\n## The pitch\n\nHave you ever merged a change to your models and you forgot to generate\na migration?\n\nHave you ever written a migration only to realize that it fails when\nthere\u2019s data in the table?\n\nHave you ever written a **perfect** migration only to merge it and later\nfind out that someone else merged also merged a migration and your CD is\nnow broken!?\n\n`pytest-alembic` is meant to (with a little help) solve all these\nproblems and more. Note, due to a few different factors, there **may**\nbe some [minimal required\nsetup](http://pytest-alembic.readthedocs.io/en/latest/setup.html);\nhowever most of it is boilerplate akin to the setup required for alembic\nitself.\n\n### Built-in Tests\n\n- **test_single_head_revision**\n\n Assert that there only exists one head revision.\n\n We\u2019re not sure what realistic scenario involves a diverging history to\n be desirable. We have only seen it be the result of uncaught merge\n conflicts resulting in a diverged history, which lazily breaks during\n deployment.\n\n- **test_upgrade**\n\n Assert that the revision history can be run through from base to head.\n\n- **test_model_definitions_match_ddl**\n\n Assert that the state of the migrations matches the state of the\n models describing the DDL.\n\n In general, the set of migrations in the history should coalesce into\n DDL which is described by the current set of models. Therefore, a call\n to `revision --autogenerate` should always generate an empty migration\n (e.g.\u00a0find no difference between your database (i.e.\u00a0migrations\n history) and your models).\n\n- **test_up_down_consistency**\n\n Assert that all downgrades succeed.\n\n While downgrading may not be lossless operation data-wise, there\u2019s a\n theory of database migrations that says that the revisions in\n existence for a database should be able to go from an entirely blank\n schema to the finished product, and back again.\n\n- [Experimental\n tests](http://pytest-alembic.readthedocs.io/en/latest/experimental_tests.html)\n\n - all_models_register_on_metadata\n\n Assert that all defined models are imported statically.\n\n Prevents scenarios in which the minimal import of your models in your `env.py`\n does not import all extant models, leading alembic to not autogenerate all\n your models, or (worse!) suggest the deletion of tables which should still exist.\n\n - downgrade_leaves_no_trace\n\n Assert that there is no difference between the state of the database pre/post downgrade.\n\n In essence this is a much more strict version of `test_up_down_consistency`,\n where the state of a MetaData before and after a downgrade are identical as\n far as alembic (autogenerate) is concerned.\n\n These tests will need to be enabled manually because their semantics or API are\n not yet guaranteed to stay the same. See the linked docs for more details!\n\nLet us know if you have any ideas for more built-in tests which would be\ngenerally useful for most alembic histories!\n\n### Custom Tests\n\nFor more information, see the docs for [custom\ntests](http://pytest-alembic.readthedocs.io/en/latest/custom_tests.html)\n(example below) or [custom static\ndata](http://pytest-alembic.readthedocs.io/en/latest/custom_data.html)\n(to be inserted automatically before a given revision).\n\nSometimes when writing a particularly gnarly data migration, it helps to\nbe able to practice a little timely TDD, since there\u2019s always the\npotential you\u2019ll trash your actual production data.\n\nWith `pytest-alembic`, you can write tests directly, in the same way\nthat you would normally, through the use of the `alembic_runner`\nfixture.\n\n```python\ndef test_gnarly_migration_xyz123(alembic_engine, alembic_runner):\n # Migrate up to, but not including this new migration\n alembic_runner.migrate_up_before('xyz123')\n\n # Perform some very specific data setup, because this migration is sooooo complex.\n # ...\n alembic_engine.execute(table.insert(id=1, name='foo'))\n\n alembic_runner.migrate_up_one()\n```\n\n`alembic_runner` has a number of methods designed to make it convenient\nto change the state of your database up, down, and all around.\n\n## Installing\n\n```bash\npip install \"pytest-alembic\"\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A pytest plugin for verifying alembic migrations.",
"version": "0.11.1",
"project_urls": {
"Homepage": "https://github.com/schireson/pytest-alembic",
"Repository": "https://github.com/schireson/pytest-alembic"
},
"split_keywords": [
"pytest",
" sqlalchemy",
" alembic",
" migration",
" revision"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "401cb2b34ee85c01582fb0bd4088a12b4e243f5edb4dc2caa0c6c3b90edf42a4",
"md5": "af8ac8d3ac2db43fed8d2cfe18f0ce58",
"sha256": "f83e8c1534d50ced053aa4b1dbf6e261f4674aa626cb852fc1dcb565049ae152"
},
"downloads": -1,
"filename": "pytest_alembic-0.11.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "af8ac8d3ac2db43fed8d2cfe18f0ce58",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 35970,
"upload_time": "2024-07-29T15:33:31",
"upload_time_iso_8601": "2024-07-29T15:33:31.217966Z",
"url": "https://files.pythonhosted.org/packages/40/1c/b2b34ee85c01582fb0bd4088a12b4e243f5edb4dc2caa0c6c3b90edf42a4/pytest_alembic-0.11.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7e7bcd3c7a07dcdf01d66ed14aa8cea89f5877c3d0a8e657be196f87ac38dfd1",
"md5": "e5ea346795a470107782b6a60a788e1f",
"sha256": "a920d8770b5be77326c5c1b2bd8d4d4a0dd8fc2c2d57abbcd1fec28a21131b85"
},
"downloads": -1,
"filename": "pytest_alembic-0.11.1.tar.gz",
"has_sig": false,
"md5_digest": "e5ea346795a470107782b6a60a788e1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 29977,
"upload_time": "2024-07-29T15:33:32",
"upload_time_iso_8601": "2024-07-29T15:33:32.892067Z",
"url": "https://files.pythonhosted.org/packages/7e/7b/cd3c7a07dcdf01d66ed14aa8cea89f5877c3d0a8e657be196f87ac38dfd1/pytest_alembic-0.11.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-29 15:33:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "schireson",
"github_project": "pytest-alembic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytest-alembic"
}
JSON
