Skip to content
Capture and make assertions on transaction.on_commit() callbacks.
Python
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows Test with Python 3.9 (#11) May 25, 2020
requirements Test with Python 3.9 (#11) May 25, 2020
src ☝️ Avoid capturing rolled back callbacks (#7) May 24, 2020
tests ☝️ Avoid capturing rolled back callbacks (#7) May 24, 2020
.editorconfig 🍓 Initial version 🍎 May 20, 2020
.gitignore 🍓 Initial version 🍎 May 20, 2020
HISTORY.rst Version 1.1.0 May 24, 2020
LICENSE 🍓 Initial version 🍎 May 20, 2020
MANIFEST.in 🍓 Initial version 🍎 May 20, 2020
README.rst Version 1.1.0 May 24, 2020
pytest.ini 🍓 Initial version 🍎 May 20, 2020
setup.cfg Test with Python 3.9 (#11) May 25, 2020
setup.py 🍓 Initial version 🍎 May 20, 2020
tox.ini Test with Python 3.9 (#11) May 25, 2020

README.rst

django-capture-on-commit-callbacks

https://github.com/adamchainz/django-capture-on-commit-callbacks/workflows/CI/badge.svg?branch=master

Capture and make assertions on transaction.on_commit() callbacks. This allows you to write your tests with the TestCase, rather than needing the slower TransactionTestCase to actually commit the transactions.

This package was made as a first pass for Django PR #12944, which is a solution for Ticket #30457 “on_commit should be triggered in a TestCase”.

Read more in my blog post The Fast Way to Test Django transaction.on_commit() Callbacks.

Installation

Use pip:

python -m pip install django-capture-on-commit-callbacks

Requirements

Python 3.5 to 3.8 supported.

Django 2.0 to 3.0 suppported.

API

capture_on_commit_callbacks(*, using="default", execute=False)

Acts as a context manager that captures on_commit callbacks for the given database connection. It returns a list that contains, on exit of the context, the captured callback functions. From this list you can make assertions on the callbacks or call them to invoke their side effects, emulating a commit.

All arguments must be passed as keyword arguments.

using is the alias of the database connection to capture callbacks for.

execute specifies whether to call all the callbacks automatically as the context manager exits, if no exception has been raised.

For example, you can test a commit hook that sends an email like so:

from django.core import mail
from django.test import TestCase
from django_capture_on_commit_callbacks import capture_on_commit_callbacks


class ContactTests(TestCase):
    def test_post(self):
        with capture_on_commit_callbacks() as callbacks:
            response = self.client.post(
                "/contact/",
                {"message": "I like your site"},
            )

        self.assertEqual(response.status_code, 200)

        self.assertEqual(len(callbacks), 1)
        # Execute the callback
        callbacks[0]()

        self.assertEqual(len(mail.outbox), 1)
        self.assertEqual(mail.outbox[0].subject, "Contact Form")
        self.assertEqual(mail.outbox[0].body, "I like your site")

The same test can be written a bit more succinctly with execute=True:

from django.core import mail
from django.test import TestCase
from django_capture_on_commit_callbacks import capture_on_commit_callbacks


class ContactTests(TestCase):
    def test_post(self):
        with capture_on_commit_callbacks(execute=True) as callbacks:
            response = self.client.post(
                "/contact/",
                {"message": "I like your site"},
            )

        self.assertEqual(response.status_code, 200)

        self.assertEqual(len(callbacks), 1)

        self.assertEqual(len(mail.outbox), 1)
        self.assertEqual(mail.outbox[0].subject, "Contact Form")
        self.assertEqual(mail.outbox[0].body, "I like your site")

TestCaseMixin

A mixin class to be added to your custom TestCase subclass. It adds one method, captureOnCommitCallbacks() that aliases capture_on_commit_callbacks(), to match the camelCase style of unittest assertions.

You can add to your custom TestCase classes like so:

from django import test
from django_capture_on_commit_callbacks import TestCaseMixin


class TestCase(TestCaseMixin, test.TestCase):
    pass

You could then rewrite the above tests with your custom TestCase class like so:

from django.core import mail
from example.test import TestCase


class ContactTests(TestCase):
    def test_post(self):
        with self.captureOnCommitCallbacks(execute=True) as callbacks:
            response = self.client.post(
                "/contact/",
                {"message": "I like your site"},
            )

        self.assertEqual(response.status_code, 200)

        self.assertEqual(len(callbacks), 1)

        self.assertEqual(len(mail.outbox), 1)
        self.assertEqual(mail.outbox[0].subject, "Contact Form")
        self.assertEqual(mail.outbox[0].body, "I like your site")
You can’t perform that action at this time.