---
id: mock-alchemy
version: "0.2.6"
license: MIT
license_treatment: permissive
maintenance: dormant
---

# mock-alchemy — SQLAlchemy mock helpers.

License: permissive · Maintenance: dormant · Downloads: 153.0K/mo

## What it is and what it does

mock-alchemy wraps SQLAlchemy's session object with mock helpers that let you assert on query and filter calls during unit tests without touching a real database. It provides three main tools: ExpressionMatcher for comparing SQLAlchemy binary expressions, AlchemyMagicMock for basic session mocking, and UnifiedAlchemyMagicMock for more complex scenarios where a session is queried multiple times with different filters. The library also supports stubbing real data by query criteria and partially fakes session mutations like add() and delete().

The package is lightweight—it depends only on SQLAlchemy—and installs as a pure Python wheel. However, it has been dormant since early 2023, with no recent commits or releases, so it may not track the latest SQLAlchemy API changes. It is classified as Pre-Alpha and is best suited for teams already committed to its design patterns.

Use it for:

- Assert that your code calls session.query() and filter() with the correct model and conditions during unit tests.
- Stub test data by matching specific query and filter call sequences, returning different results for different filter combinations.
- Verify that add() and delete() operations are called on the session without running actual database migrations.
- Test query logic in isolation by mocking the session layer and checking filter expressions are built correctly.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides mock helpers for SQLAlchemy sessions in unit tests, enabling assertion on query calls and filter operations without accessing a real database.

Yes, if you are already using SQLAlchemy and need to mock sessions in unit tests without database access. The low install friction and permissive license make it straightforward to adopt. However, be aware that maintenance is dormant—last release was 2023-03-26—so compatibility with very recent SQLAlchemy versions is uncertain. Test against your specific SQLAlchemy version before relying on it in production test suites.

## Install

pip install mock-alchemy
uv add mock-alchemy
poetry add mock-alchemy

## Installing mock-alchemy

Before you install: Low friction: pure Python wheel with only SQLAlchemy as a runtime dependency. Maintenance is dormant—last release was 2023-03-26 and last commit 2023-11-01—so expect no active bug fixes or feature updates.

License in practice: MIT license (permissive) means you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install mock-alchemy

from mock_alchemy.mocking import UnifiedAlchemyMagicMock
session = UnifiedAlchemyMagicMock()
session.query(Model).filter(Model.foo == 5).all()
session.filter.assert_has_calls([mock.call(Model.foo == 5)])

Requires Python 3.7 or later (supports 3.7–3.11); SQLAlchemy must be installed separately.

Verify before relying:

- Whether the dormant maintenance status affects compatibility with recent SQLAlchemy versions (1.4+, 2.0+).
- Whether the partial filtering and deletion limitations documented in the description are acceptable for your test scenarios.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 153.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy mock testing, mock sqlalchemy session, unit test database mocking, sqlalchemy query assertions, test fixtures sqlalchemy, fake database session, sqlalchemy-testing, mock-helpers

[View on SkillFed](https://skillfed.io/packages/mock-alchemy) · [View on PyPI](https://pypi.org/project/mock-alchemy/)