#29513: Improve testing multi_db documentation
-------------------------------------------------+------------------------
Reporter: Adam (Chainz) Johnson | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Testing framework | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------------------+------------------------
I had a pull request that took me two years to resolve (okay, I deferred
it quite a lot): https://github.com/adamchainz/django-mysql/pull/278 .
This was adding `pytest-randomly` to my project, which randomly sorts the
tests and exposes test interdependence. It turned out the failure was due
to interdependence between tests that touched a secondary database, with
the `TestCase` classes not resetting the secondary database, because
`multi_db=True` was missing from such `TestCase`s to get the secondary DB
wiped between tests.
Part of the trouble debugging this was that `multi_db` is not easy to
find:
* The page on multiple databases doesn't mention or link to testing
considerations at all: https://docs.djangoproject.com/en/2.0/topics/db
/multi-db/
* The 'test database' section of 'writing and running tests' *does*
mention and link to 'advanced multi-db testing topics' :
https://docs.djangoproject.com/en/2.0/topics/testing/overview/#the-test-
database -> https://docs.djangoproject.com/en/2.0/topics/testing/advanced
/#topics-testing-advanced-multidb . However the linked section, "Tests and
multiple databases", doesn't mention `multi_db` - it's only in the
"Advanced features of TransactionTestCase" section - and I'd argue it's
not an advanced feature but a basic one, even a risk that you'll end up
taking 2 years to debug an issue :)
* When `multi_db` is mentioned, it's only in the context of
`TransactionTestCase` . `TestCase` isn't mentioned, which yes does inherit
from `TransactionTestCase`, but it also has more behaviour, in the scope
of class-level `atomic()`s that also obey the `multi_db` flag
I think we should fix the docs for these problems 🎉.
Secondarily, the feature is confusing and I'd flip the default of the flag
to `True` and allow setting it to `False` as an optimization - but this is
a much bigger change.
--
Ticket URL: <https://code.djangoproject.com/ticket/29513>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/053.2ff90e313642a4318ab0352d09ab73fa%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
