Skip to main content

pytest-django-asyncio

pytest-django-asyncio is a small temporary compatibility plugin for projects that need async Django ORM access to work correctly with pytest-django database fixtures before the equivalent upstream support lands.

It backports the async database fixture behavior proposed in pytest-django PR #1223 and exposes it as an installed pytest plugin through pytest11, so downstream projects get the fix automatically after installation.

I'll deprecate it from pypi once the linked MR gets merged into pytest-django.

What does this fix/why do tests fail in async contexts?

pytest-django's normal db fixture wraps each test in a transaction and rolls it back afterwards. In async tests, Django's async ORM work runs via sync_to_async on a dedicated thread, so the transaction setup and teardown also need to happen on that thread or database state can escape the rollback boundary.

This package backports the fixture split and async helper approach from pytest-django PR #1223 so async tests marked with @pytest.mark.asyncio can use Django DB fixtures safely when this plugin is installed as a normal dependency.

Installation

pip install pytest-django-asyncio

You still need the usual pytest stack in the consuming project:

  • pytest
  • pytest-django
  • pytest-asyncio
  • Django

Supported versions

Package Minimum Tested up to
Python 3.10 3.14
Django 4.2 6.1
asgiref 3.9.1 3.13
pytest 8.2 9.2
pytest-django 4.11.1 4.14
pytest-asyncio 1.1.0 1.4

asgiref 3.13 needs Python 3.11 or newer, and Django 6.x needs Python 3.12 or newer. CI runs the oldest supported combination, recent Django and asgiref pairs, and Django 6.1 on PostgreSQL.

Usage

After installation, pytest auto-loads the plugin through its pytest11 entry point. That means it should be ready to go as long as you have the package installed in your python environment.

Typical usage:

import pytest


@pytest.mark.asyncio
@pytest.mark.django_db
async def test_async_orm_works():
    ...

The same backport also works when tests request db or transactional_db directly.

Caveats

  • If a project disables pytest plugin auto-loading, it must explicitly add pytest_django_asyncio.pytest_plugin to its plugin list.

How It Works

The package exposes a thin pytest_plugin.py entry module. During pytest_configure, it applies the small DjangoDbBlocker.unblock(async_only=...) backport needed by the async path and then registers the real fixture override module late with @pytest.hookimpl(trylast=True).

That late registration lets this package's _django_db_helper override win over pytest-django.

The sync path delegates back to pytest-django; the async path uses a separate helper modeled on pytest-django PR #1223: the transaction start/stop run in the same sync_to_async worker thread that executes the test's ORM calls.

For non-transactional async tests, the main thread and the sync_to_async worker thread share one set of database connections: the main thread's regular connections, so the test transaction covers ORM calls from either thread. During the test, connections._connections is replaced by a small stand-in that hands those connections to the two threads, and Django's inc_thread_sharing() allows their use across threads. Other threads keep their own connections and are still blocked from database access.

Transactional async tests close the worker thread's connections after each test, so PostgreSQL can drop the test database at the end of the session.

Development

Run the test suite against a specific dependency combination with uv:

uv run --isolated --no-project --python 3.13 --with-editable . \
  --with "Django~=6.1.0" --with "asgiref~=3.13.0" pytest

Set POSTGRES_HOST (and optionally POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD) and add --with "psycopg[binary]" to run against PostgreSQL instead of SQLite. The compat job in .github/workflows/ci.yml lists the combinations CI runs.

Metadata

Release files for pytest-django-asyncio 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-django-asyncio 0.2.1
File Size Uploaded Provenance Actions
pytest_django_asyncio-0.2.1.tar.gz 7.0 kB Without provenance Details for pytest_django_asyncio-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-django-asyncio 0.2.1
File Interpreter ABI Platform Actions
pytest_django_asyncio-0.2.1-py3-none-any.whl Python 3 none any Details for pytest_django_asyncio-0.2.1-py3-none-any.whl

Total release size: 15.7 kB

Release files / pytest_django_asyncio-0.2.1.tar.gz

Download URL pytest_django_asyncio-0.2.1.tar.gz
Size 7.0 kB
Tags Source
SHA-256 checksum
How to use checksums
743b79237b76551273f0c7a92ccd989e09113b8a4b256767319a040a006ff1c8
BLAKE2b-256 checksum
How to use checksums
2256d56aa2ef88c0e4f7c0f293c8506881f2ec8b6edf25fd2c200d44a2fa01d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / pytest_django_asyncio-0.2.1-py3-none-any.whl

Download URL pytest_django_asyncio-0.2.1-py3-none-any.whl
Size 8.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6b91df9c472c5c0e34c953d2ea7039038379e0e74573a6a547a9c7aee5388c33
BLAKE2b-256 checksum
How to use checksums
c1dd18ed78efc128b652be307fe6beafbcb5c4f7aef45e8f73fa6d808272b5bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for pytest-django-asyncio 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page