id summary reporter owner description type status component version severity resolution keywords cc stage has_patch needs_docs needs_tests needs_better_patch easy ui_ux 29513 Make TransactionTestCase.multi_db documentation more discoverable. Adam Johnson nobody "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." Cleanup/optimization closed Documentation dev Normal fixed Accepted 0 0 0 0 0 0