Document @isolate_apps

[Adam Johnson]

django.test.utils.isolate_apps is a key tool for keeping Django's test suite fast and maintainable. It can also be useful for testing third party packages and projects. For example, I'm currently writing about a custom system check for model names. The best way I can find to test this check is to use @isolate_apps and create temporary model classes that fail the check.

isolate_apps was added in ​https://github.com/django/django/commit/7bb373e3097fe8e000e0bba005ff2dcfc18ab9a5 and has remained stable since, minus refactoring to extract TestContextDecorator.

I can't find much use in the wild, indeed the only result I found in the first few pages of a GitHub search is from Sage's JSONField backport package: ​https://github.com/laymonage/django-jsonfield-backport/blob/2072fb39b6681f2bf8741e033702920b59238941/tests/test_invalid_models.py#L12

I think it's worth documenting and supporting this tool, which can be useful in many situations.

[Mariusz Felisiak]

Personally, I'm not convinced. As far as I'm aware it's stable because we now how and when it works fine. Sometimes it's trickier to use, e.g. in schema tests or when a model with the same name already exists. I'm afraid that docs will quickly grow to the list of caveats.

[Adam Johnson]

If there are too many concerns, we could document it similarly to available_apps (​https://docs.djangoproject.com/en/stable/topics/testing/advanced/#django.test.TransactionTestCase.available_apps) with a note that it is still regarded as private and liable to change. I think noting some caveats is fine.

Is there a good way to create an isolated model class for a test without isolated_apps? It seems like a common enough problem when making custom model classes, fields, or similar.

[Simon Charette]

Is there a good way to create an isolated model class for a test without isolated_apps? It seems like a common enough problem when making custom model classes, fields, or similar.

You can use the undocumented Model.Meta.apps option to point to a dedicated Apps instance, some tests do it when defining models at the module level, but it involves a lot of boilerplate and is easy to forget that you're polluting the main registry hence why isolated_apps is useful.

[Carlton Gibson]

I think documenting @isolate_apps is probably a good idea. (One alternative that I've used is a custom test-only app using Simon's setup_test_app idea/proposal on https://code.djangoproject.com/ticket/7835#comment:46 — but…)

I agree we shouldn't document every caveat… Perhaps noting the more complex cases, and then we can come up with patterns as a group on the forum, and maybe address some of the issues as folks hit them 🤔

[Christopher Adams]

Cool, happy to take this on.

Looks like there's already some kind of instructions written on how to use this function, with no caveat about it being a private API. In fact, the instruction seems to encourage developers to actively use the function. This is located in the contributing guide however, so I don't know what normative authoritative weight that recommendation has. Here's the source, at "Unit tests > Tips for writing tests > Isolating model registration":
​https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/#django.test.utils.isolate_apps

I did just write a PR to include the function spec in the django.test.utils section of the Django documentation, which is where I would have expected it to be. Here's my PR: ​https://github.com/django/django/pull/15735
@adam: want to take a quick look and see if this is what you are looking for?

For the moment, I did not include a warning about isolate_apps having an unstable API, because the reference in "Tips for writing tests" did not have that warning. Let me know if you want me to add that however.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 90d2f9f4:

Fixed #33422 -- Improved docs about isolating apps.

[Mariusz Felisiak <felisiak.mariusz@…>]

In aed1a73e:

[4.1.x] Fixed #33422 -- Improved docs about isolating apps.

Backport of 90d2f9f41671ef01c8e8e7b5648f95c9bf512aae from main