[Django] #33422: Document @isolate_apps
Django
------------------------------------------------+------------------------
Reporter: Adam Johnson | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Testing framework | Version: dev
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 |
------------------------------------------------+------------------------
`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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33422>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: nobody
Cleanup/optimization |
Component: Testing framework | Version: dev
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: nobody
Cleanup/optimization |
Component: Testing framework | Version: dev
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: nobody
Cleanup/optimization |
Component: Testing framework | Version: dev
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner: nobody
Cleanup/optimization |
Component: Testing framework | Version: dev
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by 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 🤔
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: Adam Johnson | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Testing framework | Version: dev
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner:
Cleanup/optimization | Status: assigned
Component: Testing framework | Version: dev
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Christopher Adams):
* owner: nobody => Christopher Adams
* status: new => assigned
Comment:
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.
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner:
Type: | Christopher Adams
Cleanup/optimization | Status: assigned
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* needs_better_patch: 0 => 1
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner:
Type: | Christopher Adams
Cleanup/optimization | Status: assigned
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner:
Type: | Christopher Adams
Component: Testing framework | Version: dev
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"90d2f9f41671ef01c8e8e7b5648f95c9bf512aae" 90d2f9f4]:
{{{
#!CommitTicketReference repository=""
revision="90d2f9f41671ef01c8e8e7b5648f95c9bf512aae"
Fixed #33422 -- Improved docs about isolating apps.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Adam Johnson | Owner:
Type: | Christopher Adams
Cleanup/optimization | Status: closed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"aed1a73e0a848c5368abe57a6b57119acfdbbd67" aed1a73e]:
{{{
#!CommitTicketReference repository=""
revision="aed1a73e0a848c5368abe57a6b57119acfdbbd67"
[4.1.x] Fixed #33422 -- Improved docs about isolating apps.
Backport of 90d2f9f41671ef01c8e8e7b5648f95c9bf512aae from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/33422#comment:10>