Debian Codegraph @

django/test/testcases.py

raw
1 import difflib
2 import json
3 import logging
4 import pickle
5 import posixpath
6 import sys
7 import threading
8 import unittest
9 from collections import Counter
10 from contextlib import contextmanager
11 from copy import copy, deepcopy
12 from difflib import get_close_matches
13 from functools import wraps
14 from unittest import mock
15 from unittest.suite import _DebugResult
16 from unittest.util import safe_repr
17 from urllib.parse import (
18 parse_qsl,
19 unquote,
20 urlencode,
21 urljoin,
22 urlparse,
23 urlsplit,
24 urlunsplit,
25 )
26 from urllib.request import url2pathname
27
28 from asgiref.sync import async_to_sync, iscoroutinefunction
29
30 from django.apps import apps
31 from django.conf import settings
32 from django.core import mail
33 from django.core.exceptions import ImproperlyConfigured, ValidationError
34 from django.core.files import locks
35 from django.core.handlers.wsgi import WSGIHandler, get_path_info
36 from django.core.management import call_command
37 from django.core.management.color import no_style
38 from django.core.management.sql import emit_post_migrate_signal
39 from django.core.servers.basehttp import ThreadedWSGIServer, WSGIRequestHandler
40 from django.core.signals import setting_changed
41 from django.db import DEFAULT_DB_ALIAS, connection, connections, transaction
42 from django.db.backends.base.base import NO_DB_ALIAS, BaseDatabaseWrapper
43 from django.forms.fields import CharField
44 from django.http import QueryDict
45 from django.http.request import split_domain_port, validate_host
46 from django.test.client import AsyncClient, Client
47 from django.test.html import HTMLParseError, parse_html
48 from django.test.signals import template_rendered
49 from django.test.utils import (
50 CaptureQueriesContext,
51 ContextList,
52 compare_xml,
53 modify_settings,
54 override_settings,
55 )
56 from django.utils.functional import classproperty
57 from django.utils.version import PY311
58 from django.views.static import serve
59
60 logger = logging.getLogger("django.test")
61
62 __all__ = (
63 "TestCase",
64 "TransactionTestCase",
65 "SimpleTestCase",
66 "skipIfDBFeature",
67 "skipUnlessDBFeature",
68 )
69
70 # Make unittest ignore frames in this module when reporting failures.
71 __unittest = True
72
73
74 if not PY311:
75 # Backport of unittest.case._enter_context() from Python 3.11.
76 def _enter_context(cm, addcleanup):
77 # Look up the special methods on the type to match the with statement.
78 cls = type(cm)
79 try:
80 enter = cls.__enter__
81 exit = cls.__exit__
82 except AttributeError:
83 raise TypeError(
84 f"'{cls.__module__}.{cls.__qualname__}' object does not support the "
85 f"context manager protocol"
86 ) from None
87 result = enter(cm)
88 addcleanup(exit, cm, None, None, None)
89 return result
90
91
92 def to_list(value):
93 """Put value into a list if it's not already one."""
94 if not isinstance(value, list):
95 value = [value]
96 return value
97
98
99 def is_pickable(obj):
100 """
101 Returns true if the object can be dumped and loaded through the pickle
102 module.
103 """
104 try:
105 pickle.loads(pickle.dumps(obj))
106 except (AttributeError, TypeError, pickle.PickleError):
107 return False
108 return True
109
110
111 def assert_and_parse_html(self, html, user_msg, msg):
112 try:
113 dom = parse_html(html)
114 except HTMLParseError as e:
115 standardMsg = "%s\n%s" % (msg, e)
116 self.fail(self._formatMessage(user_msg, standardMsg))
117 return dom
118
119
120 class _AssertNumQueriesContext(CaptureQueriesContext):
121 def __init__(self, test_case, num, connection):
122 self.test_case = test_case
123 self.num = num
124 super().__init__(connection)
125
126 def __exit__(self, exc_type, exc_value, traceback):
127 super().__exit__(exc_type, exc_value, traceback)
128 if exc_type is not None:
129 return
130 executed = len(self)
131 self.test_case.assertEqual(
132 executed,
133 self.num,
134 "%d queries executed, %d expected\nCaptured queries were:\n%s"
135 % (
136 executed,
137 self.num,
138 "\n".join(
139 "%d. %s" % (i, query["sql"])
140 for i, query in enumerate(self.captured_queries, start=1)
141 ),
142 ),
143 )
144
145
146 class _AssertTemplateUsedContext:
147 def __init__(self, test_case, template_name, msg_prefix="", count=None):
148 self.test_case = test_case
149 self.template_name = template_name
150 self.msg_prefix = msg_prefix
151 self.count = count
152
153 self.rendered_templates = []
154 self.context = ContextList()
155
156 def on_template_render(self, sender, signal, template, context, **kwargs):
157 self.rendered_templates.append(template)
158 self.context.append(copy(context))
159
160 def test(self):
161 self.test_case._assert_template_used(
162 self.template_name,
163 [t.name for t in self.rendered_templates if t.name is not None],
164 self.msg_prefix,
165 self.count,
166 )
167
168 def __enter__(self):
169 template_rendered.connect(self.on_template_render)
170 return self
171
172 def __exit__(self, exc_type, exc_value, traceback):
173 template_rendered.disconnect(self.on_template_render)
174 if exc_type is not None:
175 return
176 self.test()
177
178
179 class _AssertTemplateNotUsedContext(_AssertTemplateUsedContext):
180 def test(self):
181 rendered_template_names = [
182 t.name for t in self.rendered_templates if t.name is not None
183 ]
184 self.test_case.assertFalse(
185 self.template_name in rendered_template_names,
186 f"{self.msg_prefix}Template '{self.template_name}' was used "
187 f"unexpectedly in rendering the response",
188 )
189
190
191 class DatabaseOperationForbidden(AssertionError):
192 pass
193
194
195 class _DatabaseFailure:
196 def __init__(self, wrapped, message):
197 self.wrapped = wrapped
198 self.message = message
199
200 def __call__(self):
201 raise DatabaseOperationForbidden(self.message)
202
203
204 class SimpleTestCase(unittest.TestCase):
205 # The class we'll use for the test client self.client.
206 # Can be overridden in derived classes.
207 client_class = Client
208 async_client_class = AsyncClient
209 _overridden_settings = None
210 _modified_settings = None
211 _pre_setup_ran_eagerly = False
212
213 databases = set()
214 _disallowed_database_msg = (
215 "Database %(operation)s to %(alias)r are not allowed in SimpleTestCase "
216 "subclasses. Either subclass TestCase or TransactionTestCase to ensure "
217 "proper test isolation or add %(alias)r to %(test)s.databases to silence "
218 "this failure."
219 )
220 _disallowed_connection_methods = [
221 ("connect", "connections"),
222 ("temporary_connection", "connections"),
223 ("cursor", "queries"),
224 ("chunked_cursor", "queries"),
225 ]
226
227 @classmethod
228 def setUpClass(cls):
229 super().setUpClass()
230 if cls._overridden_settings:
231 cls.enterClassContext(override_settings(**cls._overridden_settings))
232 if cls._modified_settings:
233 cls.enterClassContext(modify_settings(cls._modified_settings))
234 cls._add_databases_failures()
235 cls.addClassCleanup(cls._remove_databases_failures)
236
237 @classmethod
238 def _validate_databases(cls):
239 if cls.databases == "__all__":
240 return frozenset(connections)
241 for alias in cls.databases:
242 if alias not in connections:
243 message = (
244 "%s.%s.databases refers to %r which is not defined in "
245 "settings.DATABASES."
246 % (
247 cls.__module__,
248 cls.__qualname__,
249 alias,
250 )
251 )
252 close_matches = get_close_matches(alias, list(connections))
253 if close_matches:
254 message += " Did you mean %r?" % close_matches[0]
255 raise ImproperlyConfigured(message)
256 return frozenset(cls.databases)
257
258 @classmethod
259 def _add_databases_failures(cls):
260 cls.databases = cls._validate_databases()
261 for alias in connections:
262 if alias in cls.databases:
263 continue
264 connection = connections[alias]
265 for name, operation in cls._disallowed_connection_methods:
266 message = cls._disallowed_database_msg % {
267 "test": "%s.%s" % (cls.__module__, cls.__qualname__),
268 "alias": alias,
269 "operation": operation,
270 }
271 method = getattr(connection, name)
272 setattr(connection, name, _DatabaseFailure(method, message))
273 cls.enterClassContext(
274 mock.patch.object(
275 BaseDatabaseWrapper,
276 "ensure_connection",
277 new=cls.ensure_connection_patch_method(),
278 )
279 )
280
281 @classmethod
282 def _remove_databases_failures(cls):
283 for alias in connections:
284 if alias in cls.databases:
285 continue
286 connection = connections[alias]
287 for name, _ in cls._disallowed_connection_methods:
288 method = getattr(connection, name)
289 setattr(connection, name, method.wrapped)
290
291 @classmethod
292 def ensure_connection_patch_method(cls):
293 real_ensure_connection = BaseDatabaseWrapper.ensure_connection
294
295 def patched_ensure_connection(self, *args, **kwargs):
296 if (
297 self.connection is None
298 and self.alias not in cls.databases
299 and self.alias != NO_DB_ALIAS
300 # Dynamically created connections are always allowed.
301 and self.alias in connections
302 ):
303 # Connection has not yet been established, but the alias is not allowed.
304 message = cls._disallowed_database_msg % {
305 "test": f"{cls.__module__}.{cls.__qualname__}",
306 "alias": self.alias,
307 "operation": "threaded connections",
308 }
309 return _DatabaseFailure(self.ensure_connection, message)()
310
311 real_ensure_connection(self, *args, **kwargs)
312
313 return patched_ensure_connection
314
315 def __call__(self, result=None):
316 """
317 Wrapper around default __call__ method to perform common Django test
318 set up. This means that user-defined TestCases aren't required to
319 include a call to super().setUp().
320 """
321 self._setup_and_call(result)
322
323 def __getstate__(self):
324 """
325 Make SimpleTestCase picklable for parallel tests using subtests.
326 """
327 state = super().__dict__
328 # _outcome and _subtest cannot be tested on picklability, since they
329 # contain the TestCase itself, leading to an infinite recursion.
330 if state["_outcome"]:
331 pickable_state = {"_outcome": None, "_subtest": None}
332 for key, value in state.items():
333 if key in pickable_state or not is_pickable(value):
334 continue
335 pickable_state[key] = value
336 return pickable_state
337
338 return state
339
340 def debug(self):
341 """Perform the same as __call__(), without catching the exception."""
342 debug_result = _DebugResult()
343 self._setup_and_call(debug_result, debug=True)
344
345 def _setup_and_call(self, result, debug=False):
346 """
347 Perform the following in order: pre-setup, run test, post-teardown,
348 skipping pre/post hooks if test is set to be skipped.
349
350 If debug=True, reraise any errors in setup and use super().debug()
351 instead of __call__() to run the test.
352 """
353 testMethod = getattr(self, self._testMethodName)
354 skipped = getattr(self.__class__, "__unittest_skip__", False) or getattr(
355 testMethod, "__unittest_skip__", False
356 )
357
358 # Convert async test methods.
359 if iscoroutinefunction(testMethod):
360 setattr(self, self._testMethodName, async_to_sync(testMethod))
361
362 if not skipped:
363 try:
364 if self.__class__._pre_setup_ran_eagerly:
365 self.__class__._pre_setup_ran_eagerly = False
366 else:
367 self._pre_setup()
368 except Exception:
369 if debug:
370 raise
371 result.addError(self, sys.exc_info())
372 return
373 if debug:
374 super().debug()
375 else:
376 super().__call__(result)
377 if not skipped:
378 try:
379 self._post_teardown()
380 except Exception:
381 if debug:
382 raise
383 result.addError(self, sys.exc_info())
384 return
385
386 @classmethod
387 def _pre_setup(cls):
388 """
389 Perform pre-test setup:
390 * Create a test client.
391 * Clear the mail test outbox.
392 """
393 cls.client = cls.client_class()
394 cls.async_client = cls.async_client_class()
395 mail.outbox = []
396
397 def _post_teardown(self):
398 """Perform post-test things."""
399 pass
400
401 if not PY311:
402 # Backport of unittest.TestCase.enterClassContext() from Python 3.11.
403 @classmethod
404 def enterClassContext(cls, cm):
405 return _enter_context(cm, cls.addClassCleanup)
406
407 # Backport of unittest.TestCase.enterContext() from Python 3.11.
408 def enterContext(self, cm):
409 return _enter_context(cm, self.addCleanup)
410
411 def settings(self, **kwargs):
412 """
413 A context manager that temporarily sets a setting and reverts to the
414 original value when exiting the context.
415 """
416 return override_settings(**kwargs)
417
418 def modify_settings(self, **kwargs):
419 """
420 A context manager that temporarily applies changes to a list setting
421 and reverts back to the original value when exiting the context.
422 """
423 return modify_settings(**kwargs)
424
425 def assertRedirects(
426 self,
427 response,
428 expected_url,
429 status_code=302,
430 target_status_code=200,
431 msg_prefix="",
432 fetch_redirect_response=True,
433 ):
434 """
435 Assert that a response redirected to a specific URL and that the
436 redirect URL can be loaded.
437
438 Won't work for external links since it uses the test client to do a
439 request (use fetch_redirect_response=False to check such links without
440 fetching them).
441 """
442 if msg_prefix:
443 msg_prefix += ": "
444
445 if hasattr(response, "redirect_chain"):
446 # The request was a followed redirect
447 self.assertTrue(
448 response.redirect_chain,
449 msg_prefix
450 + (
451 "Response didn't redirect as expected: Response code was %d "
452 "(expected %d)"
453 )
454 % (response.status_code, status_code),
455 )
456
457 self.assertEqual(
458 response.redirect_chain[0][1],
459 status_code,
460 msg_prefix
461 + (
462 "Initial response didn't redirect as expected: Response code was "
463 "%d (expected %d)"
464 )
465 % (response.redirect_chain[0][1], status_code),
466 )
467
468 url, status_code = response.redirect_chain[-1]
469
470 self.assertEqual(
471 response.status_code,
472 target_status_code,
473 msg_prefix
474 + (
475 "Response didn't redirect as expected: Final Response code was %d "
476 "(expected %d)"
477 )
478 % (response.status_code, target_status_code),
479 )
480
481 else:
482 # Not a followed redirect
483 self.assertEqual(
484 response.status_code,
485 status_code,
486 msg_prefix
487 + (
488 "Response didn't redirect as expected: Response code was %d "
489 "(expected %d)"
490 )
491 % (response.status_code, status_code),
492 )
493
494 url = response.url
495 scheme, netloc, path, query, fragment = urlsplit(url)
496
497 # Prepend the request path to handle relative path redirects.
498 if not path.startswith("/"):
499 url = urljoin(response.request["PATH_INFO"], url)
500 path = urljoin(response.request["PATH_INFO"], path)
501
502 if fetch_redirect_response:
503 # netloc might be empty, or in cases where Django tests the
504 # HTTP scheme, the convention is for netloc to be 'testserver'.
505 # Trust both as "internal" URLs here.
506 domain, port = split_domain_port(netloc)
507 if domain and not validate_host(domain, settings.ALLOWED_HOSTS):
508 raise ValueError(
509 "The test client is unable to fetch remote URLs (got %s). "
510 "If the host is served by Django, add '%s' to ALLOWED_HOSTS. "
511 "Otherwise, use "
512 "assertRedirects(..., fetch_redirect_response=False)."
513 % (url, domain)
514 )
515 # Get the redirection page, using the same client that was used
516 # to obtain the original response.
517 extra = response.client.extra or {}
518 headers = response.client.headers or {}
519 redirect_response = response.client.get(
520 path,
521 QueryDict(query),
522 secure=(scheme == "https"),
523 headers=headers,
524 **extra,
525 )
526 self.assertEqual(
527 redirect_response.status_code,
528 target_status_code,
529 msg_prefix
530 + (
531 "Couldn't retrieve redirection page '%s': response code was %d "
532 "(expected %d)"
533 )
534 % (path, redirect_response.status_code, target_status_code),
535 )
536
537 self.assertURLEqual(
538 url,
539 expected_url,
540 msg_prefix
541 + "Response redirected to '%s', expected '%s'" % (url, expected_url),
542 )
543
544 def assertURLEqual(self, url1, url2, msg_prefix=""):
545 """
546 Assert that two URLs are the same, ignoring the order of query string
547 parameters except for parameters with the same name.
548
549 For example, /path/?x=1&y=2 is equal to /path/?y=2&x=1, but
550 /path/?a=1&a=2 isn't equal to /path/?a=2&a=1.
551 """
552
553 def normalize(url):
554 """Sort the URL's query string parameters."""
555 url = str(url) # Coerce reverse_lazy() URLs.
556 scheme, netloc, path, query, fragment = urlsplit(url)
557 query_parts = sorted(parse_qsl(query))
558 return urlunsplit((scheme, netloc, path, urlencode(query_parts), fragment))
559
560 if msg_prefix:
561 msg_prefix += ": "
562 self.assertEqual(
563 normalize(url1),
564 normalize(url2),
565 msg_prefix + "Expected '%s' to equal '%s'." % (url1, url2),
566 )
567
568 def _assert_contains(self, response, text, status_code, msg_prefix, html):
569 # If the response supports deferred rendering and hasn't been rendered
570 # yet, then ensure that it does get rendered before proceeding further.
571 if (
572 hasattr(response, "render")
573 and callable(response.render)
574 and not response.is_rendered
575 ):
576 response.render()
577
578 if msg_prefix:
579 msg_prefix += ": "
580
581 self.assertEqual(
582 response.status_code,
583 status_code,
584 msg_prefix + "Couldn't retrieve content: Response code was %d"
585 " (expected %d)" % (response.status_code, status_code),
586 )
587
588 if response.streaming:
589 content = b"".join(response.streaming_content)
590 else:
591 content = response.content
592 content_repr = safe_repr(content)
593 if not isinstance(text, bytes) or html:
594 text = str(text)
595 content = content.decode(response.charset)
596 text_repr = "'%s'" % text
597 else:
598 text_repr = repr(text)
599 if html:
600 content = assert_and_parse_html(
601 self, content, None, "Response's content is not valid HTML:"
602 )
603 text = assert_and_parse_html(
604 self, text, None, "Second argument is not valid HTML:"
605 )
606 real_count = content.count(text)
607 return text_repr, real_count, msg_prefix, content_repr
608
609 def assertContains(
610 self, response, text, count=None, status_code=200, msg_prefix="", html=False
611 ):
612 """
613 Assert that a response indicates that some content was retrieved
614 successfully, (i.e., the HTTP status code was as expected) and that
615 ``text`` occurs ``count`` times in the content of the response.
616 If ``count`` is None, the count doesn't matter - the assertion is true
617 if the text occurs at least once in the response.
618 """
619 text_repr, real_count, msg_prefix, content_repr = self._assert_contains(
620 response, text, status_code, msg_prefix, html
621 )
622
623 if count is not None:
624 self.assertEqual(
625 real_count,
626 count,
627 (
628 f"{msg_prefix}Found {real_count} instances of {text_repr} "
629 f"(expected {count}) in the following response\n{content_repr}"
630 ),
631 )
632 else:
633 self.assertTrue(
634 real_count != 0,
635 (
636 f"{msg_prefix}Couldn't find {text_repr} in the following response\n"
637 f"{content_repr}"
638 ),
639 )
640
641 def assertNotContains(
642 self, response, text, status_code=200, msg_prefix="", html=False
643 ):
644 """
645 Assert that a response indicates that some content was retrieved
646 successfully, (i.e., the HTTP status code was as expected) and that
647 ``text`` doesn't occur in the content of the response.
648 """
649 text_repr, real_count, msg_prefix, content_repr = self._assert_contains(
650 response, text, status_code, msg_prefix, html
651 )
652
653 self.assertEqual(
654 real_count,
655 0,
656 (
657 f"{msg_prefix}{text_repr} unexpectedly found in the following response"
658 f"\n{content_repr}"
659 ),
660 )
661
662 def _check_test_client_response(self, response, attribute, method_name):
663 """
664 Raise a ValueError if the given response doesn't have the required
665 attribute.
666 """
667 if not hasattr(response, attribute):
668 raise ValueError(
669 f"{method_name}() is only usable on responses fetched using "
670 "the Django test Client."
671 )
672
673 def _assert_form_error(self, form, field, errors, msg_prefix, form_repr):
674 if not form.is_bound:
675 self.fail(
676 f"{msg_prefix}The {form_repr} is not bound, it will never have any "
677 f"errors."
678 )
679
680 if field is not None and field not in form.fields:
681 self.fail(
682 f"{msg_prefix}The {form_repr} does not contain the field {field!r}."
683 )
684 if field is None:
685 field_errors = form.non_field_errors()
686 failure_message = f"The non-field errors of {form_repr} don't match."
687 else:
688 field_errors = form.errors.get(field, [])
689 failure_message = (
690 f"The errors of field {field!r} on {form_repr} don't match."
691 )
692
693 self.assertEqual(field_errors, errors, msg_prefix + failure_message)
694
695 def assertFormError(self, form, field, errors, msg_prefix=""):
696 """
697 Assert that a field named "field" on the given form object has specific
698 errors.
699
700 errors can be either a single error message or a list of errors
701 messages. Using errors=[] test that the field has no errors.
702
703 You can pass field=None to check the form's non-field errors.
704 """
705 if msg_prefix:
706 msg_prefix += ": "
707 errors = to_list(errors)
708 self._assert_form_error(form, field, errors, msg_prefix, f"form {form!r}")
709
710 def assertFormSetError(self, formset, form_index, field, errors, msg_prefix=""):
711 """
712 Similar to assertFormError() but for formsets.
713
714 Use form_index=None to check the formset's non-form errors (in that
715 case, you must also use field=None).
716 Otherwise use an integer to check the formset's n-th form for errors.
717
718 Other parameters are the same as assertFormError().
719 """
720 if form_index is None and field is not None:
721 raise ValueError("You must use field=None with form_index=None.")
722
723 if msg_prefix:
724 msg_prefix += ": "
725 errors = to_list(errors)
726
727 if not formset.is_bound:
728 self.fail(
729 f"{msg_prefix}The formset {formset!r} is not bound, it will never have "
730 f"any errors."
731 )
732 if form_index is not None and form_index >= formset.total_form_count():
733 form_count = formset.total_form_count()
734 form_or_forms = "forms" if form_count > 1 else "form"
735 self.fail(
736 f"{msg_prefix}The formset {formset!r} only has {form_count} "
737 f"{form_or_forms}."
738 )
739 if form_index is not None:
740 form_repr = f"form {form_index} of formset {formset!r}"
741 self._assert_form_error(
742 formset.forms[form_index], field, errors, msg_prefix, form_repr
743 )
744 else:
745 failure_message = f"The non-form errors of formset {formset!r} don't match."
746 self.assertEqual(
747 formset.non_form_errors(), errors, msg_prefix + failure_message
748 )
749
750 def _get_template_used(self, response, template_name, msg_prefix, method_name):
751 if response is None and template_name is None:
752 raise TypeError("response and/or template_name argument must be provided")
753
754 if msg_prefix:
755 msg_prefix += ": "
756
757 if template_name is not None and response is not None:
758 self._check_test_client_response(response, "templates", method_name)
759
760 if not hasattr(response, "templates") or (response is None and template_name):
761 if response:
762 template_name = response
763 response = None
764 # use this template with context manager
765 return template_name, None, msg_prefix
766
767 template_names = [t.name for t in response.templates if t.name is not None]
768 return None, template_names, msg_prefix
769
770 def _assert_template_used(self, template_name, template_names, msg_prefix, count):
771 if not template_names:
772 self.fail(msg_prefix + "No templates used to render the response")
773 self.assertTrue(
774 template_name in template_names,
775 msg_prefix + "Template '%s' was not a template used to render"
776 " the response. Actual template(s) used: %s"
777 % (template_name, ", ".join(template_names)),
778 )
779
780 if count is not None:
781 self.assertEqual(
782 template_names.count(template_name),
783 count,
784 msg_prefix + "Template '%s' was expected to be rendered %d "
785 "time(s) but was actually rendered %d time(s)."
786 % (template_name, count, template_names.count(template_name)),
787 )
788
789 def assertTemplateUsed(
790 self, response=None, template_name=None, msg_prefix="", count=None
791 ):
792 """
793 Assert that the template with the provided name was used in rendering
794 the response. Also usable as context manager.
795 """
796 context_mgr_template, template_names, msg_prefix = self._get_template_used(
797 response,
798 template_name,
799 msg_prefix,
800 "assertTemplateUsed",
801 )
802 if context_mgr_template:
803 # Use assertTemplateUsed as context manager.
804 return _AssertTemplateUsedContext(
805 self, context_mgr_template, msg_prefix, count
806 )
807
808 self._assert_template_used(template_name, template_names, msg_prefix, count)
809
810 def assertTemplateNotUsed(self, response=None, template_name=None, msg_prefix=""):
811 """
812 Assert that the template with the provided name was NOT used in
813 rendering the response. Also usable as context manager.
814 """
815 context_mgr_template, template_names, msg_prefix = self._get_template_used(
816 response,
817 template_name,
818 msg_prefix,
819 "assertTemplateNotUsed",
820 )
821 if context_mgr_template:
822 # Use assertTemplateNotUsed as context manager.
823 return _AssertTemplateNotUsedContext(self, context_mgr_template, msg_prefix)
824
825 self.assertFalse(
826 template_name in template_names,
827 msg_prefix
828 + "Template '%s' was used unexpectedly in rendering the response"
829 % template_name,
830 )
831
832 @contextmanager
833 def _assert_raises_or_warns_cm(
834 self, func, cm_attr, expected_exception, expected_message
835 ):
836 with func(expected_exception) as cm:
837 yield cm
838 self.assertIn(expected_message, str(getattr(cm, cm_attr)))
839
840 def _assertFooMessage(
841 self, func, cm_attr, expected_exception, expected_message, *args, **kwargs
842 ):
843 callable_obj = None
844 if args:
845 callable_obj, *args = args
846 cm = self._assert_raises_or_warns_cm(
847 func, cm_attr, expected_exception, expected_message
848 )
849 # Assertion used in context manager fashion.
850 if callable_obj is None:
851 return cm
852 # Assertion was passed a callable.
853 with cm:
854 callable_obj(*args, **kwargs)
855
856 def assertRaisesMessage(
857 self, expected_exception, expected_message, *args, **kwargs
858 ):
859 """
860 Assert that expected_message is found in the message of a raised
861 exception.
862
863 Args:
864 expected_exception: Exception class expected to be raised.
865 expected_message: expected error message string value.
866 args: Function to be called and extra positional args.
867 kwargs: Extra kwargs.
868 """
869 return self._assertFooMessage(
870 self.assertRaises,
871 "exception",
872 expected_exception,
873 expected_message,
874 *args,
875 **kwargs,
876 )
877
878 def assertWarnsMessage(self, expected_warning, expected_message, *args, **kwargs):
879 """
880 Same as assertRaisesMessage but for assertWarns() instead of
881 assertRaises().
882 """
883 return self._assertFooMessage(
884 self.assertWarns,
885 "warning",
886 expected_warning,
887 expected_message,
888 *args,
889 **kwargs,
890 )
891
892 def assertFieldOutput(
893 self,
894 fieldclass,
895 valid,
896 invalid,
897 field_args=None,
898 field_kwargs=None,
899 empty_value="",
900 ):
901 """
902 Assert that a form field behaves correctly with various inputs.
903
904 Args:
905 fieldclass: the class of the field to be tested.
906 valid: a dictionary mapping valid inputs to their expected
907 cleaned values.
908 invalid: a dictionary mapping invalid inputs to one or more
909 raised error messages.
910 field_args: the args passed to instantiate the field
911 field_kwargs: the kwargs passed to instantiate the field
912 empty_value: the expected clean output for inputs in empty_values
913 """
914 if field_args is None:
915 field_args = []
916 if field_kwargs is None:
917 field_kwargs = {}
918 required = fieldclass(*field_args, **field_kwargs)
919 optional = fieldclass(*field_args, **{**field_kwargs, "required": False})
920 # test valid inputs
921 for input, output in valid.items():
922 self.assertEqual(required.clean(input), output)
923 self.assertEqual(optional.clean(input), output)
924 # test invalid inputs
925 for input, errors in invalid.items():
926 with self.assertRaises(ValidationError) as context_manager:
927 required.clean(input)
928 self.assertEqual(context_manager.exception.messages, errors)
929
930 with self.assertRaises(ValidationError) as context_manager:
931 optional.clean(input)
932 self.assertEqual(context_manager.exception.messages, errors)
933 # test required inputs
934 error_required = [required.error_messages["required"]]
935 for e in required.empty_values:
936 with self.assertRaises(ValidationError) as context_manager:
937 required.clean(e)
938 self.assertEqual(context_manager.exception.messages, error_required)
939 self.assertEqual(optional.clean(e), empty_value)
940 # test that max_length and min_length are always accepted
941 if issubclass(fieldclass, CharField):
942 field_kwargs.update({"min_length": 2, "max_length": 20})
943 self.assertIsInstance(fieldclass(*field_args, **field_kwargs), fieldclass)
944
945 def assertHTMLEqual(self, html1, html2, msg=None):
946 """
947 Assert that two HTML snippets are semantically the same.
948 Whitespace in most cases is ignored, and attribute ordering is not
949 significant. The arguments must be valid HTML.
950 """
951 dom1 = assert_and_parse_html(
952 self, html1, msg, "First argument is not valid HTML:"
953 )
954 dom2 = assert_and_parse_html(
955 self, html2, msg, "Second argument is not valid HTML:"
956 )
957
958 if dom1 != dom2:
959 standardMsg = "%s != %s" % (safe_repr(dom1, True), safe_repr(dom2, True))
960 diff = "\n" + "\n".join(
961 difflib.ndiff(
962 str(dom1).splitlines(),
963 str(dom2).splitlines(),
964 )
965 )
966 standardMsg = self._truncateMessage(standardMsg, diff)
967 self.fail(self._formatMessage(msg, standardMsg))
968
969 def assertHTMLNotEqual(self, html1, html2, msg=None):
970 """Assert that two HTML snippets are not semantically equivalent."""
971 dom1 = assert_and_parse_html(
972 self, html1, msg, "First argument is not valid HTML:"
973 )
974 dom2 = assert_and_parse_html(
975 self, html2, msg, "Second argument is not valid HTML:"
976 )
977
978 if dom1 == dom2:
979 standardMsg = "%s == %s" % (safe_repr(dom1, True), safe_repr(dom2, True))
980 self.fail(self._formatMessage(msg, standardMsg))
981
982 def assertInHTML(self, needle, haystack, count=None, msg_prefix=""):
983 parsed_needle = assert_and_parse_html(
984 self, needle, None, "First argument is not valid HTML:"
985 )
986 parsed_haystack = assert_and_parse_html(
987 self, haystack, None, "Second argument is not valid HTML:"
988 )
989 real_count = parsed_haystack.count(parsed_needle)
990 if msg_prefix:
991 msg_prefix += ": "
992 haystack_repr = safe_repr(haystack)
993 if count is not None:
994 if count == 0:
995 msg = (
996 f"{needle!r} unexpectedly found in the following response\n"
997 f"{haystack_repr}"
998 )
999 else:
1000 msg = (
1001 f"Found {real_count} instances of {needle!r} (expected {count}) in "
1002 f"the following response\n{haystack_repr}"
1003 )
1004 self.assertEqual(real_count, count, f"{msg_prefix}{msg}")
1005 else:
1006 self.assertTrue(
1007 real_count != 0,
1008 (
1009 f"{msg_prefix}Couldn't find {needle!r} in the following response\n"
1010 f"{haystack_repr}"
1011 ),
1012 )
1013
1014 def assertNotInHTML(self, needle, haystack, msg_prefix=""):
1015 self.assertInHTML(needle, haystack, count=0, msg_prefix=msg_prefix)
1016
1017 def assertJSONEqual(self, raw, expected_data, msg=None):
1018 """
1019 Assert that the JSON fragments raw and expected_data are equal.
1020 Usual JSON non-significant whitespace rules apply as the heavyweight
1021 is delegated to the json library.
1022 """
1023 try:
1024 data = json.loads(raw)
1025 except json.JSONDecodeError:
1026 self.fail("First argument is not valid JSON: %r" % raw)
1027 if isinstance(expected_data, str):
1028 try:
1029 expected_data = json.loads(expected_data)
1030 except ValueError:
1031 self.fail("Second argument is not valid JSON: %r" % expected_data)
1032 self.assertEqual(data, expected_data, msg=msg)
1033
1034 def assertJSONNotEqual(self, raw, expected_data, msg=None):
1035 """
1036 Assert that the JSON fragments raw and expected_data are not equal.
1037 Usual JSON non-significant whitespace rules apply as the heavyweight
1038 is delegated to the json library.
1039 """
1040 try:
1041 data = json.loads(raw)
1042 except json.JSONDecodeError:
1043 self.fail("First argument is not valid JSON: %r" % raw)
1044 if isinstance(expected_data, str):
1045 try:
1046 expected_data = json.loads(expected_data)
1047 except json.JSONDecodeError:
1048 self.fail("Second argument is not valid JSON: %r" % expected_data)
1049 self.assertNotEqual(data, expected_data, msg=msg)
1050
1051 def assertXMLEqual(self, xml1, xml2, msg=None):
1052 """
1053 Assert that two XML snippets are semantically the same.
1054 Whitespace in most cases is ignored and attribute ordering is not
1055 significant. The arguments must be valid XML.
1056 """
1057 try:
1058 result = compare_xml(xml1, xml2)
1059 except Exception as e:
1060 standardMsg = "First or second argument is not valid XML\n%s" % e
1061 self.fail(self._formatMessage(msg, standardMsg))
1062 else:
1063 if not result:
1064 standardMsg = "%s != %s" % (
1065 safe_repr(xml1, True),
1066 safe_repr(xml2, True),
1067 )
1068 diff = "\n" + "\n".join(
1069 difflib.ndiff(xml1.splitlines(), xml2.splitlines())
1070 )
1071 standardMsg = self._truncateMessage(standardMsg, diff)
1072 self.fail(self._formatMessage(msg, standardMsg))
1073
1074 def assertXMLNotEqual(self, xml1, xml2, msg=None):
1075 """
1076 Assert that two XML snippets are not semantically equivalent.
1077 Whitespace in most cases is ignored and attribute ordering is not
1078 significant. The arguments must be valid XML.
1079 """
1080 try:
1081 result = compare_xml(xml1, xml2)
1082 except Exception as e:
1083 standardMsg = "First or second argument is not valid XML\n%s" % e
1084 self.fail(self._formatMessage(msg, standardMsg))
1085 else:
1086 if result:
1087 standardMsg = "%s == %s" % (
1088 safe_repr(xml1, True),
1089 safe_repr(xml2, True),
1090 )
1091 self.fail(self._formatMessage(msg, standardMsg))
1092
1093
1094 class TransactionTestCase(SimpleTestCase):
1095 # Subclasses can ask for resetting of auto increment sequence before each
1096 # test case
1097 reset_sequences = False
1098
1099 # Subclasses can enable only a subset of apps for faster tests
1100 available_apps = None
1101 _available_apps_calls_balanced = 0
1102
1103 # Subclasses can define fixtures which will be automatically installed.
1104 fixtures = None
1105
1106 databases = {DEFAULT_DB_ALIAS}
1107 _disallowed_database_msg = (
1108 "Database %(operation)s to %(alias)r are not allowed in this test. "
1109 "Add %(alias)r to %(test)s.databases to ensure proper test isolation "
1110 "and silence this failure."
1111 )
1112
1113 # If transactions aren't available, Django will serialize the database
1114 # contents into a fixture during setup and flush and reload them
1115 # during teardown (as flush does not restore data from migrations).
1116 # This can be slow; this flag allows enabling on a per-case basis.
1117 serialized_rollback = False
1118
1119 @classmethod
1120 def setUpClass(cls):
1121 super().setUpClass()
1122 if not issubclass(cls, TestCase):
1123 cls._pre_setup()
1124 cls._pre_setup_ran_eagerly = True
1125
1126 @classmethod
1127 def tearDownClass(cls):
1128 super().tearDownClass()
1129 if not issubclass(cls, TestCase) and cls._available_apps_calls_balanced > 0:
1130 apps.unset_available_apps()
1131 cls._available_apps_calls_balanced -= 1
1132
1133 @classmethod
1134 def _pre_setup(cls):
1135 """
1136 Perform pre-test setup:
1137 * If the class has an 'available_apps' attribute, restrict the app
1138 registry to these applications, then fire the post_migrate signal --
1139 it must run with the correct set of applications for the test case.
1140 * If the class has a 'fixtures' attribute, install those fixtures.
1141 """
1142 super()._pre_setup()
1143 if cls.available_apps is not None:
1144 apps.set_available_apps(cls.available_apps)
1145 cls._available_apps_calls_balanced += 1
1146 setting_changed.send(
1147 sender=settings._wrapped.__class__,
1148 setting="INSTALLED_APPS",
1149 value=cls.available_apps,
1150 enter=True,
1151 )
1152 for db_name in cls._databases_names(include_mirrors=False):
1153 emit_post_migrate_signal(verbosity=0, interactive=False, db=db_name)
1154 try:
1155 cls._fixture_setup()
1156 except Exception:
1157 if cls.available_apps is not None:
1158 apps.unset_available_apps()
1159 setting_changed.send(
1160 sender=settings._wrapped.__class__,
1161 setting="INSTALLED_APPS",
1162 value=settings.INSTALLED_APPS,
1163 enter=False,
1164 )
1165 raise
1166 # Clear the queries_log so that it's less likely to overflow (a single
1167 # test probably won't execute 9K queries). If queries_log overflows,
1168 # then assertNumQueries() doesn't work.
1169 for db_name in cls._databases_names(include_mirrors=False):
1170 connections[db_name].queries_log.clear()
1171
1172 @classmethod
1173 def _databases_names(cls, include_mirrors=True):
1174 # Only consider allowed database aliases, including mirrors or not.
1175 return [
1176 alias
1177 for alias in connections
1178 if alias in cls.databases
1179 and (
1180 include_mirrors
1181 or not connections[alias].settings_dict["TEST"]["MIRROR"]
1182 )
1183 ]
1184
1185 @staticmethod
1186 def _reset_sequences(db_name):
1187 conn = connections[db_name]
1188 if conn.features.supports_sequence_reset:
1189 sql_list = conn.ops.sequence_reset_by_name_sql(
1190 no_style(), conn.introspection.sequence_list()
1191 )
1192 if sql_list:
1193 with transaction.atomic(using=db_name):
1194 with conn.cursor() as cursor:
1195 for sql in sql_list:
1196 cursor.execute(sql)
1197
1198 @classmethod
1199 def _fixture_setup(cls):
1200 for db_name in cls._databases_names(include_mirrors=False):
1201 # Reset sequences
1202 if cls.reset_sequences:
1203 cls._reset_sequences(db_name)
1204
1205 # Provide replica initial data from migrated apps, if needed.
1206 if cls.serialized_rollback and hasattr(
1207 connections[db_name], "_test_serialized_contents"
1208 ):
1209 if cls.available_apps is not None:
1210 apps.unset_available_apps()
1211 connections[db_name].creation.deserialize_db_from_string(
1212 connections[db_name]._test_serialized_contents
1213 )
1214 if cls.available_apps is not None:
1215 apps.set_available_apps(cls.available_apps)
1216
1217 if cls.fixtures:
1218 call_command("loaddata", *cls.fixtures, verbosity=0, database=db_name)
1219
1220 def _should_reload_connections(self):
1221 return True
1222
1223 def _post_teardown(self):
1224 """
1225 Perform post-test things:
1226 * Flush the contents of the database to leave a clean slate. If the
1227 class has an 'available_apps' attribute, don't fire post_migrate.
1228 * Force-close the connection so the next test gets a clean cursor.
1229 """
1230 try:
1231 self._fixture_teardown()
1232 super()._post_teardown()
1233 if self._should_reload_connections():
1234 # Some DB cursors include SQL statements as part of cursor
1235 # creation. If you have a test that does a rollback, the effect
1236 # of these statements is lost, which can affect the operation of
1237 # tests (e.g., losing a timezone setting causing objects to be
1238 # created with the wrong time). To make sure this doesn't
1239 # happen, get a clean connection at the start of every test.
1240 for conn in connections.all(initialized_only=True):
1241 conn.close()
1242 finally:
1243 if self.__class__.available_apps is not None:
1244 apps.unset_available_apps()
1245 self.__class__._available_apps_calls_balanced -= 1
1246 setting_changed.send(
1247 sender=settings._wrapped.__class__,
1248 setting="INSTALLED_APPS",
1249 value=settings.INSTALLED_APPS,
1250 enter=False,
1251 )
1252
1253 def _fixture_teardown(self):
1254 # Allow TRUNCATE ... CASCADE and don't emit the post_migrate signal
1255 # when flushing only a subset of the apps
1256 for db_name in self._databases_names(include_mirrors=False):
1257 # Flush the database
1258 inhibit_post_migrate = (
1259 self.available_apps is not None
1260 or ( # Inhibit the post_migrate signal when using serialized
1261 # rollback to avoid trying to recreate the serialized data.
1262 self.serialized_rollback
1263 and hasattr(connections[db_name], "_test_serialized_contents")
1264 )
1265 )
1266 call_command(
1267 "flush",
1268 verbosity=0,
1269 interactive=False,
1270 database=db_name,
1271 reset_sequences=False,
1272 allow_cascade=self.available_apps is not None,
1273 inhibit_post_migrate=inhibit_post_migrate,
1274 )
1275
1276 def assertQuerySetEqual(self, qs, values, transform=None, ordered=True, msg=None):
1277 values = list(values)
1278 items = qs
1279 if transform is not None:
1280 items = map(transform, items)
1281 if not ordered:
1282 return self.assertDictEqual(Counter(items), Counter(values), msg=msg)
1283 # For example qs.iterator() could be passed as qs, but it does not
1284 # have 'ordered' attribute.
1285 if len(values) > 1 and hasattr(qs, "ordered") and not qs.ordered:
1286 raise ValueError(
1287 "Trying to compare non-ordered queryset against more than one "
1288 "ordered value."
1289 )
1290 return self.assertEqual(list(items), values, msg=msg)
1291
1292 def assertNumQueries(self, num, func=None, *args, using=DEFAULT_DB_ALIAS, **kwargs):
1293 conn = connections[using]
1294
1295 context = _AssertNumQueriesContext(self, num, conn)
1296 if func is None:
1297 return context
1298
1299 with context:
1300 func(*args, **kwargs)
1301
1302
1303 def connections_support_transactions(aliases=None):
1304 """
1305 Return whether or not all (or specified) connections support
1306 transactions.
1307 """
1308 conns = (
1309 connections.all()
1310 if aliases is None
1311 else (connections[alias] for alias in aliases)
1312 )
1313 return all(conn.features.supports_transactions for conn in conns)
1314
1315
1316 def connections_support_savepoints(aliases=None):
1317 """
1318 Return whether or not all (or specified) connections support savepoints.
1319 """
1320 conns = (
1321 connections.all()
1322 if aliases is None
1323 else (connections[alias] for alias in aliases)
1324 )
1325 return all(conn.features.uses_savepoints for conn in conns)
1326
1327
1328 class TestData:
1329 """
1330 Descriptor to provide TestCase instance isolation for attributes assigned
1331 during the setUpTestData() phase.
1332
1333 Allow safe alteration of objects assigned in setUpTestData() by test
1334 methods by exposing deep copies instead of the original objects.
1335
1336 Objects are deep copied using a memo kept on the test case instance in
1337 order to maintain their original relationships.
1338 """
1339
1340 memo_attr = "_testdata_memo"
1341
1342 def __init__(self, name, data):
1343 self.name = name
1344 self.data = data
1345
1346 def get_memo(self, testcase):
1347 try:
1348 memo = getattr(testcase, self.memo_attr)
1349 except AttributeError:
1350 memo = {}
1351 setattr(testcase, self.memo_attr, memo)
1352 return memo
1353
1354 def __get__(self, instance, owner):
1355 if instance is None:
1356 return self.data
1357 memo = self.get_memo(instance)
1358 data = deepcopy(self.data, memo)
1359 setattr(instance, self.name, data)
1360 return data
1361
1362 def __repr__(self):
1363 return "<TestData: name=%r, data=%r>" % (self.name, self.data)
1364
1365
1366 class TestCase(TransactionTestCase):
1367 """
1368 Similar to TransactionTestCase, but use `transaction.atomic()` to achieve
1369 test isolation.
1370
1371 In most situations, TestCase should be preferred to TransactionTestCase as
1372 it allows faster execution. However, there are some situations where using
1373 TransactionTestCase might be necessary (e.g. testing some transactional
1374 behavior).
1375
1376 On database backends with no transaction support, TestCase behaves as
1377 TransactionTestCase.
1378 """
1379
1380 @classmethod
1381 def _enter_atomics(cls):
1382 """Open atomic blocks for multiple databases."""
1383 atomics = {}
1384 for db_name in cls._databases_names():
1385 atomic = transaction.atomic(using=db_name)
1386 atomic._from_testcase = True
1387 atomic.__enter__()
1388 atomics[db_name] = atomic
1389 return atomics
1390
1391 @classmethod
1392 def _rollback_atomics(cls, atomics):
1393 """Rollback atomic blocks opened by the previous method."""
1394 for db_name in reversed(cls._databases_names()):
1395 transaction.set_rollback(True, using=db_name)
1396 atomics[db_name].__exit__(None, None, None)
1397
1398 @classmethod
1399 def _databases_support_transactions(cls):
1400 return connections_support_transactions(cls.databases)
1401
1402 @classmethod
1403 def _databases_support_savepoints(cls):
1404 return connections_support_savepoints(cls.databases)
1405
1406 @classmethod
1407 def setUpClass(cls):
1408 super().setUpClass()
1409 if not (
1410 cls._databases_support_transactions()
1411 and cls._databases_support_savepoints()
1412 ):
1413 return
1414 cls.cls_atomics = cls._enter_atomics()
1415
1416 if cls.fixtures:
1417 for db_name in cls._databases_names(include_mirrors=False):
1418 try:
1419 call_command(
1420 "loaddata",
1421 *cls.fixtures,
1422 verbosity=0,
1423 database=db_name,
1424 )
1425 except Exception:
1426 cls._rollback_atomics(cls.cls_atomics)
1427 raise
1428 pre_attrs = cls.__dict__.copy()
1429 try:
1430 cls.setUpTestData()
1431 except Exception:
1432 cls._rollback_atomics(cls.cls_atomics)
1433 raise
1434 for name, value in cls.__dict__.items():
1435 if value is not pre_attrs.get(name):
1436 setattr(cls, name, TestData(name, value))
1437
1438 @classmethod
1439 def tearDownClass(cls):
1440 if (
1441 cls._databases_support_transactions()
1442 and cls._databases_support_savepoints()
1443 ):
1444 cls._rollback_atomics(cls.cls_atomics)
1445 for conn in connections.all(initialized_only=True):
1446 conn.close()
1447 super().tearDownClass()
1448
1449 @classmethod
1450 def setUpTestData(cls):
1451 """Load initial data for the TestCase."""
1452 pass
1453
1454 def _should_reload_connections(self):
1455 if self._databases_support_transactions():
1456 return False
1457 return super()._should_reload_connections()
1458
1459 @classmethod
1460 def _fixture_setup(cls):
1461 if not cls._databases_support_transactions():
1462 # If the backend does not support transactions, we should reload
1463 # class data before each test
1464 cls.setUpTestData()
1465 return super()._fixture_setup()
1466
1467 if cls.reset_sequences:
1468 raise TypeError("reset_sequences cannot be used on TestCase instances")
1469 cls.atomics = cls._enter_atomics()
1470 if not cls._databases_support_savepoints():
1471 if cls.fixtures:
1472 for db_name in cls._databases_names(include_mirrors=False):
1473 call_command(
1474 "loaddata",
1475 *cls.fixtures,
1476 **{"verbosity": 0, "database": db_name},
1477 )
1478 cls.setUpTestData()
1479
1480 def _fixture_teardown(self):
1481 if not self._databases_support_transactions():
1482 return super()._fixture_teardown()
1483 try:
1484 for db_name in reversed(self._databases_names()):
1485 if self._should_check_constraints(connections[db_name]):
1486 connections[db_name].check_constraints()
1487 finally:
1488 self._rollback_atomics(self.atomics)
1489
1490 def _should_check_constraints(self, connection):
1491 return (
1492 connection.features.can_defer_constraint_checks
1493 and not connection.needs_rollback
1494 and connection.is_usable()
1495 )
1496
1497 @classmethod
1498 @contextmanager
1499 def captureOnCommitCallbacks(cls, *, using=DEFAULT_DB_ALIAS, execute=False):
1500 """Context manager to capture transaction.on_commit() callbacks."""
1501 callbacks = []
1502 start_count = len(connections[using].run_on_commit)
1503 try:
1504 yield callbacks
1505 finally:
1506 while True:
1507 callback_count = len(connections[using].run_on_commit)
1508 for _, callback, robust in connections[using].run_on_commit[
1509 start_count:
1510 ]:
1511 callbacks.append(callback)
1512 if execute:
1513 if robust:
1514 try:
1515 callback()
1516 except Exception as e:
1517 logger.error(
1518 f"Error calling {callback.__qualname__} in "
1519 f"on_commit() (%s).",
1520 e,
1521 exc_info=True,
1522 )
1523 else:
1524 callback()
1525
1526 if callback_count == len(connections[using].run_on_commit):
1527 break
1528 start_count = callback_count
1529
1530
1531 class CheckCondition:
1532 """Descriptor class for deferred condition checking."""
1533
1534 def __init__(self, *conditions):
1535 self.conditions = conditions
1536
1537 def add_condition(self, condition, reason):
1538 return self.__class__(*self.conditions, (condition, reason))
1539
1540 def __get__(self, instance, cls=None):
1541 # Trigger access for all bases.
1542 if any(getattr(base, "__unittest_skip__", False) for base in cls.__bases__):
1543 return True
1544 for condition, reason in self.conditions:
1545 if condition():
1546 # Override this descriptor's value and set the skip reason.
1547 cls.__unittest_skip__ = True
1548 cls.__unittest_skip_why__ = reason
1549 return True
1550 return False
1551
1552
1553 def _deferredSkip(condition, reason, name):
1554 def decorator(test_func):
1555 nonlocal condition
1556 if not (
1557 isinstance(test_func, type) and issubclass(test_func, unittest.TestCase)
1558 ):
1559
1560 @wraps(test_func)
1561 def skip_wrapper(*args, **kwargs):
1562 if (
1563 args
1564 and isinstance(args[0], unittest.TestCase)
1565 and connection.alias not in getattr(args[0], "databases", {})
1566 ):
1567 raise ValueError(
1568 "%s cannot be used on %s as %s doesn't allow queries "
1569 "against the %r database."
1570 % (
1571 name,
1572 args[0],
1573 args[0].__class__.__qualname__,
1574 connection.alias,
1575 )
1576 )
1577 if condition():
1578 raise unittest.SkipTest(reason)
1579 return test_func(*args, **kwargs)
1580
1581 test_item = skip_wrapper
1582 else:
1583 # Assume a class is decorated
1584 test_item = test_func
1585 databases = getattr(test_item, "databases", None)
1586 if not databases or connection.alias not in databases:
1587 # Defer raising to allow importing test class's module.
1588 def condition():
1589 raise ValueError(
1590 "%s cannot be used on %s as it doesn't allow queries "
1591 "against the '%s' database."
1592 % (
1593 name,
1594 test_item,
1595 connection.alias,
1596 )
1597 )
1598
1599 # Retrieve the possibly existing value from the class's dict to
1600 # avoid triggering the descriptor.
1601 skip = test_func.__dict__.get("__unittest_skip__")
1602 if isinstance(skip, CheckCondition):
1603 test_item.__unittest_skip__ = skip.add_condition(condition, reason)
1604 elif skip is not True:
1605 test_item.__unittest_skip__ = CheckCondition((condition, reason))
1606 return test_item
1607
1608 return decorator
1609
1610
1611 def skipIfDBFeature(*features):
1612 """Skip a test if a database has at least one of the named features."""
1613 return _deferredSkip(
1614 lambda: any(
1615 getattr(connection.features, feature, False) for feature in features
1616 ),
1617 "Database has feature(s) %s" % ", ".join(features),
1618 "skipIfDBFeature",
1619 )
1620
1621
1622 def skipUnlessDBFeature(*features):
1623 """Skip a test unless a database has all the named features."""
1624 return _deferredSkip(
1625 lambda: not all(
1626 getattr(connection.features, feature, False) for feature in features
1627 ),
1628 "Database doesn't support feature(s): %s" % ", ".join(features),
1629 "skipUnlessDBFeature",
1630 )
1631
1632
1633 def skipUnlessAnyDBFeature(*features):
1634 """Skip a test unless a database has any of the named features."""
1635 return _deferredSkip(
1636 lambda: not any(
1637 getattr(connection.features, feature, False) for feature in features
1638 ),
1639 "Database doesn't support any of the feature(s): %s" % ", ".join(features),
1640 "skipUnlessAnyDBFeature",
1641 )
1642
1643
1644 class QuietWSGIRequestHandler(WSGIRequestHandler):
1645 """
1646 A WSGIRequestHandler that doesn't log to standard output any of the
1647 requests received, so as to not clutter the test result output.
1648 """
1649
1650 def log_message(*args):
1651 pass
1652
1653
1654 class FSFilesHandler(WSGIHandler):
1655 """
1656 WSGI middleware that intercepts calls to a directory, as defined by one of
1657 the *_ROOT settings, and serves those files, publishing them under *_URL.
1658 """
1659
1660 def __init__(self, application):
1661 self.application = application
1662 self.base_url = urlparse(self.get_base_url())
1663 super().__init__()
1664
1665 def _should_handle(self, path):
1666 """
1667 Check if the path should be handled. Ignore the path if:
1668 * the host is provided as part of the base_url
1669 * the request's path isn't under the media path (or equal)
1670 """
1671 return path.startswith(self.base_url.path) and not self.base_url.netloc
1672
1673 def file_path(self, url):
1674 """Return the relative path to the file on disk for the given URL."""
1675 relative_url = url.removeprefix(self.base_url.path)
1676 return url2pathname(relative_url)
1677
1678 def get_response(self, request):
1679 from django.http import Http404
1680
1681 if self._should_handle(request.path):
1682 try:
1683 return self.serve(request)
1684 except Http404:
1685 pass
1686 return super().get_response(request)
1687
1688 def serve(self, request):
1689 os_rel_path = self.file_path(request.path)
1690 os_rel_path = posixpath.normpath(unquote(os_rel_path))
1691 # Emulate behavior of django.contrib.staticfiles.views.serve() when it
1692 # invokes staticfiles' finders functionality.
1693 # TODO: Modify if/when that internal API is refactored
1694 final_rel_path = os_rel_path.replace("\\", "/").lstrip("/")
1695 return serve(request, final_rel_path, document_root=self.get_base_dir())
1696
1697 def __call__(self, environ, start_response):
1698 if not self._should_handle(get_path_info(environ)):
1699 return self.application(environ, start_response)
1700 return super().__call__(environ, start_response)
1701
1702
1703 class _StaticFilesHandler(FSFilesHandler):
1704 """
1705 Handler for serving static files. A private class that is meant to be used
1706 solely as a convenience by LiveServerThread.
1707 """
1708
1709 def get_base_dir(self):
1710 return settings.STATIC_ROOT
1711
1712 def get_base_url(self):
1713 return settings.STATIC_URL
1714
1715
1716 class _MediaFilesHandler(FSFilesHandler):
1717 """
1718 Handler for serving the media files. A private class that is meant to be
1719 used solely as a convenience by LiveServerThread.
1720 """
1721
1722 def get_base_dir(self):
1723 return settings.MEDIA_ROOT
1724
1725 def get_base_url(self):
1726 return settings.MEDIA_URL
1727
1728
1729 class LiveServerThread(threading.Thread):
1730 """Thread for running a live HTTP server while the tests are running."""
1731
1732 server_class = ThreadedWSGIServer
1733
1734 def __init__(self, host, static_handler, connections_override=None, port=0):
1735 self.host = host
1736 self.port = port
1737 self.is_ready = threading.Event()
1738 self.error = None
1739 self.static_handler = static_handler
1740 self.connections_override = connections_override
1741 super().__init__()
1742
1743 def run(self):
1744 """
1745 Set up the live server and databases, and then loop over handling
1746 HTTP requests.
1747 """
1748 if self.connections_override:
1749 # Override this thread's database connections with the ones
1750 # provided by the main thread.
1751 for alias, conn in self.connections_override.items():
1752 connections[alias] = conn
1753 try:
1754 # Create the handler for serving static and media files
1755 handler = self.static_handler(_MediaFilesHandler(WSGIHandler()))
1756 self.httpd = self._create_server(
1757 connections_override=self.connections_override,
1758 )
1759 # If binding to port zero, assign the port allocated by the OS.
1760 if self.port == 0:
1761 self.port = self.httpd.server_address[1]
1762 self.httpd.set_app(handler)
1763 self.is_ready.set()
1764 self.httpd.serve_forever()
1765 except Exception as e:
1766 self.error = e
1767 self.is_ready.set()
1768 finally:
1769 connections.close_all()
1770
1771 def _create_server(self, connections_override=None):
1772 return self.server_class(
1773 (self.host, self.port),
1774 QuietWSGIRequestHandler,
1775 allow_reuse_address=False,
1776 connections_override=connections_override,
1777 )
1778
1779 def terminate(self):
1780 if hasattr(self, "httpd"):
1781 # Stop the WSGI server
1782 self.httpd.shutdown()
1783 self.httpd.server_close()
1784 self.join()
1785
1786
1787 class LiveServerTestCase(TransactionTestCase):
1788 """
1789 Do basically the same as TransactionTestCase but also launch a live HTTP
1790 server in a separate thread so that the tests may use another testing
1791 framework, such as Selenium for example, instead of the built-in dummy
1792 client.
1793 It inherits from TransactionTestCase instead of TestCase because the
1794 threads don't share the same transactions (unless if using in-memory sqlite)
1795 and each thread needs to commit all their transactions so that the other
1796 thread can see the changes.
1797 """
1798
1799 host = "localhost"
1800 port = 0
1801 server_thread_class = LiveServerThread
1802 static_handler = _StaticFilesHandler
1803
1804 @classproperty
1805 def live_server_url(cls):
1806 return "http://%s:%s" % (cls.host, cls.server_thread.port)
1807
1808 @classproperty
1809 def allowed_host(cls):
1810 return cls.host
1811
1812 @classmethod
1813 def _make_connections_override(cls):
1814 connections_override = {}
1815 for conn in connections.all():
1816 # If using in-memory sqlite databases, pass the connections to
1817 # the server thread.
1818 if conn.vendor == "sqlite" and conn.is_in_memory_db():
1819 connections_override[conn.alias] = conn
1820 return connections_override
1821
1822 @classmethod
1823 def setUpClass(cls):
1824 super().setUpClass()
1825 cls.enterClassContext(
1826 modify_settings(ALLOWED_HOSTS={"append": cls.allowed_host})
1827 )
1828 cls._start_server_thread()
1829
1830 @classmethod
1831 def _start_server_thread(cls):
1832 connections_override = cls._make_connections_override()
1833 for conn in connections_override.values():
1834 # Explicitly enable thread-shareability for this connection.
1835 conn.inc_thread_sharing()
1836
1837 cls.server_thread = cls._create_server_thread(connections_override)
1838 cls.server_thread.daemon = True
1839 cls.server_thread.start()
1840 cls.addClassCleanup(cls._terminate_thread)
1841
1842 # Wait for the live server to be ready
1843 cls.server_thread.is_ready.wait()
1844 if cls.server_thread.error:
1845 raise cls.server_thread.error
1846
1847 @classmethod
1848 def _create_server_thread(cls, connections_override):
1849 return cls.server_thread_class(
1850 cls.host,
1851 cls.static_handler,
1852 connections_override=connections_override,
1853 port=cls.port,
1854 )
1855
1856 @classmethod
1857 def _terminate_thread(cls):
1858 # Terminate the live server's thread.
1859 cls.server_thread.terminate()
1860 # Restore shared connections' non-shareability.
1861 for conn in cls.server_thread.connections_override.values():
1862 conn.dec_thread_sharing()
1863
1864
1865 class SerializeMixin:
1866 """
1867 Enforce serialization of TestCases that share a common resource.
1868
1869 Define a common 'lockfile' for each set of TestCases to serialize. This
1870 file must exist on the filesystem.
1871
1872 Place it early in the MRO in order to isolate setUpClass()/tearDownClass().
1873 """
1874
1875 lockfile = None
1876
1877 def __init_subclass__(cls, /, **kwargs):
1878 super().__init_subclass__(**kwargs)
1879 if cls.lockfile is None:
1880 raise ValueError(
1881 "{}.lockfile isn't set. Set it to a unique value "
1882 "in the base class.".format(cls.__name__)
1883 )
1884
1885 @classmethod
1886 def setUpClass(cls):
1887 cls._lockfile = open(cls.lockfile)
1888 cls.addClassCleanup(cls._lockfile.close)
1889 locks.lock(cls._lockfile, locks.LOCK_EX)
1890 super().setUpClass()