pytest-orm-boundaries

💡 Even if you control your imports — boundaries still can leak through the ORM

A pytest-orm-boundaries is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.

Currently works with Django ORM.

In domain-driven design, an aggregate is a consistency boundary: code in one aggregate should not reach into the internals of another. Django's __ relation lookups make it easy to cross those boundaries silently:

# Purchase and Client belong to different aggregates — this query couples them.
Purchase.objects.get(client__name="John")

pytest-orm-boundaries watches the queries your test suite executes and reports the ones that step outside their aggregate, whether through __ lookups, subqueries, or other joins.

Install

pip install pytest-orm-boundaries

pytest picks the plugin up automatically.

Configure

Declare your aggregates in boundaries.toml at the project root (or point at the file with --boundaries-config / the boundaries_config ini option):

[aggregates]
client   = ["bookshop.Client"]
book     = ["bookshop.Book"]
purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]

Models are written as app_label.Model. Models not listed in any aggregate are not checked. Without a config file the plugin emits a warning and runs no checks.

The report

At the end of the run, the plugin prints one grouped entry per offending place:

===================== orm-boundaries: boundary violations ======================
1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):

bookshop/purchases.py:29
    code: return list(Purchase.objects.filter(client__name=name))
    crosses: client, purchase
    affected tests (1):
      test_purchases.py::test_get_purchases_by_client_name

orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.

The run exits non-zero when there are violations, so CI catches them. Pass -v to list all affected tests.

Ignoring files

Add exceptions so that known offenders keep passing while you fix them one file at a time:

[ignore]
files = [
    "app/billing.py",
    "app/legacy/*",
]

Each entry is a glob (fnmatch, resolved relative to pytest's root directory and matched against either:

the file that issues the query, or
the test file.

If an ignored file runs queries through the whole suite without ever crossing a boundary, the plugin says so at the end:

======================= orm-boundaries: stale ignores ========================
These [ignore] entries no longer suppress any boundary violation - their files are clean now.
Remove them from boundaries.toml:
  - app/billing.py

Status

Alpha - testing basic version.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest_orm_boundaries-0.3.0.tar.gz (8.8 kB view details)

Uploaded Jul 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pytest_orm_boundaries-0.3.0-py3-none-any.whl (12.2 kB view details)

Uploaded Jul 6, 2026 Python 3

File details

Details for the file pytest_orm_boundaries-0.3.0.tar.gz.

File metadata

Download URL: pytest_orm_boundaries-0.3.0.tar.gz
Upload date: Jul 6, 2026
Size: 8.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pytest_orm_boundaries-0.3.0.tar.gz
Algorithm	Hash digest
SHA256	`b9463d547cda078edd431c0694162301d81c61373ec0dececc9dd7064d311702`
MD5	`bb6134c85e9f3501fa64fcfa592d2356`
BLAKE2b-256	`146ad235035ee442c42e82a8207f3a0869657fd1584a3a20d3e4678c5ef638c7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pytest_orm_boundaries-0.3.0.tar.gz:

Publisher: publish.yml on evchibisova/pytest-orm-boundaries

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: pytest_orm_boundaries-0.3.0.tar.gz
- Subject digest: b9463d547cda078edd431c0694162301d81c61373ec0dececc9dd7064d311702
- Sigstore transparency entry: 2088655165
- Sigstore integration time: Jul 6, 2026
Source repository:
- Permalink: evchibisova/pytest-orm-boundaries@925bdca518654a42c5575dd5dc6bde17575edbda
- Branch / Tag: refs/tags/v0.3.0
- Owner: https://github.com/evchibisova
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@925bdca518654a42c5575dd5dc6bde17575edbda
- Trigger Event: release