diff --git a/docs/reference/settings.md b/docs/reference/settings.md index 61b5a66..62149b6 100644 --- a/docs/reference/settings.md +++ b/docs/reference/settings.md @@ -22,7 +22,7 @@ before enabling it in production. When this setting is `True`, [`run_after_commit`][django_subatomic.db.run_after_commit] will ensure that it knows whether or not after-commit callbacks should be simulated in tests. To avoid silently doing the wrong thing when it is not sure, -[`run_after_commit`][django_subatomic.db.run_after_commit] will raise `subatomic.db._AmbiguousAfterCommitTestBehaviour`. +[`run_after_commit`][django_subatomic.db.run_after_commit] will raise `django_subatomic.db._AmbiguousAfterCommitTestBehaviour`. (This setting starts with an underscore because it is not intended to be caught and handled.) This can happen in tests when [`run_after_commit`][django_subatomic.db.run_after_commit] is called @@ -33,7 +33,7 @@ after-commit callbacks would not normally be run. Where after-commit callbacks should be run, this can be fixed by replacing (or wrapping) the `atomic` block with -[`subatomic.db.transaction`][django_subatomic.db.transaction] +[`django_subatomic.db.transaction`][django_subatomic.db.transaction] (or [`transaction_if_not_already`][django_subatomic.db.transaction_if_not_already] if necessary). In tests where after-commit callbacks should not be run, @@ -63,11 +63,11 @@ on a per-test basis. [`transaction`][django_subatomic.db.transaction] and [`transaction_if_not_already`][django_subatomic.db.transaction_if_not_already] -will raise `subatomic.db._UnhandledCallbacks` in tests +will raise `django_subatomic.db._UnhandledCallbacks` in tests if they detect any lingering unhandled after-commit callbacks when they are called. [`part_of_a_transaction`][django_subatomic.test.part_of_a_transaction] -will raise `subatomic.test._UnhandledCallbacks` instead. +will raise `django_subatomic.test._UnhandledCallbacks` instead. Note: because these exceptions each represent a programming error, they start with an underscore to discourage anyone from catching them. diff --git a/docs/testing-after-commit-callbacks.md b/docs/testing-after-commit-callbacks.md index 69ab785..b5f4d66 100644 --- a/docs/testing-after-commit-callbacks.md +++ b/docs/testing-after-commit-callbacks.md @@ -85,7 +85,7 @@ from django.test import TestCase class TestBuildABCD(TestCase): def test_build_ABCD(self): - with self.captureOnCommitCallbacks(execute=True) + with self.captureOnCommitCallbacks(execute=True): built = build_ABCD() # This returns `["A", "B", "D", "C"]` assert built == ["A", "B", "C", "D"] # This will fail! ``` @@ -99,7 +99,7 @@ While the callbacks do run, the execution order differs from production, potenti ```python from django.test import TransactionTestCase -class TestBuildABCD(TransactionTestCase) +class TestBuildABCD(TransactionTestCase): def test_build_ABCD(): built = build_ABCD() # This returns `["A", "B", "C", "D"]` assert built == ["A", "B", "C", "D"] diff --git a/docs/transactions-savepoints-and-atomic.md b/docs/transactions-savepoints-and-atomic.md index c8ce957..4542774 100644 --- a/docs/transactions-savepoints-and-atomic.md +++ b/docs/transactions-savepoints-and-atomic.md @@ -95,7 +95,7 @@ to make it raise an exception when someone tries to run it without first opening The trade-off is that lower-level tests will see this error too. If you're testing [`transaction_required`][django_subatomic.db.transaction_required] code directly, and you're _sure_ that the code shouldn't be responsible for opening a transaction, - use the [`part_of_a_transaction`][django_subatomic.test.part_of_a_transaction] decorator/context-manager + use the [`part_of_a_transaction`][django_subatomic.test.part_of_a_transaction] context manager to get things working. This will not run after-commit hooks. If you'd like those to run, create a [transaction](#transactions) instead.