Debian Codegraph @

django/test/utils.py

raw
1 import collections
2 import gc
3 import logging
4 import os
5 import re
6 import sys
7 import time
8 import warnings
9 from contextlib import contextmanager
10 from functools import wraps
11 from io import StringIO
12 from itertools import chain
13 from types import SimpleNamespace
14 from unittest import TestCase, skipIf, skipUnless
15 from xml.dom.minidom import Node, parseString
16
17 from asgiref.sync import iscoroutinefunction
18
19 from django.apps import apps
20 from django.apps.registry import Apps
21 from django.conf import UserSettingsHolder, settings
22 from django.core import mail
23 from django.core.exceptions import ImproperlyConfigured
24 from django.core.signals import request_started, setting_changed
25 from django.db import DEFAULT_DB_ALIAS, connections, reset_queries
26 from django.db.models.options import Options
27 from django.template import Template
28 from django.test.signals import template_rendered
29 from django.urls import get_script_prefix, set_script_prefix
30 from django.utils.translation import deactivate
31 from django.utils.version import PYPY
32
33 try:
34 import jinja2
35 except ImportError:
36 jinja2 = None
37
38
39 __all__ = (
40 "Approximate",
41 "ContextList",
42 "isolate_lru_cache",
43 "garbage_collect",
44 "get_runner",
45 "CaptureQueriesContext",
46 "ignore_warnings",
47 "isolate_apps",
48 "modify_settings",
49 "override_settings",
50 "override_system_checks",
51 "tag",
52 "requires_tz_support",
53 "setup_databases",
54 "setup_test_environment",
55 "teardown_test_environment",
56 )
57
58 TZ_SUPPORT = hasattr(time, "tzset")
59
60
61 class Approximate:
62 def __init__(self, val, places=7):
63 self.val = val
64 self.places = places
65
66 def __repr__(self):
67 return repr(self.val)
68
69 def __eq__(self, other):
70 return self.val == other or round(abs(self.val - other), self.places) == 0
71
72
73 class ContextList(list):
74 """
75 A wrapper that provides direct key access to context items contained
76 in a list of context objects.
77 """
78
79 def __getitem__(self, key):
80 if isinstance(key, str):
81 for subcontext in self:
82 if key in subcontext:
83 return subcontext[key]
84 raise KeyError(key)
85 else:
86 return super().__getitem__(key)
87
88 def get(self, key, default=None):
89 try:
90 return self.__getitem__(key)
91 except KeyError:
92 return default
93
94 def __contains__(self, key):
95 try:
96 self[key]
97 except KeyError:
98 return False
99 return True
100
101 def keys(self):
102 """
103 Flattened keys of subcontexts.
104 """
105 return set(chain.from_iterable(d for subcontext in self for d in subcontext))
106
107
108 def instrumented_test_render(self, context):
109 """
110 An instrumented Template render method, providing a signal that can be
111 intercepted by the test Client.
112 """
113 template_rendered.send(sender=self, template=self, context=context)
114 return self.nodelist.render(context)
115
116
117 class _TestState:
118 pass
119
120
121 def setup_test_environment(debug=None):
122 """
123 Perform global pre-test setup, such as installing the instrumented template
124 renderer and setting the email backend to the locmem email backend.
125 """
126 if hasattr(_TestState, "saved_data"):
127 # Executing this function twice would overwrite the saved values.
128 raise RuntimeError(
129 "setup_test_environment() was already called and can't be called "
130 "again without first calling teardown_test_environment()."
131 )
132
133 if debug is None:
134 debug = settings.DEBUG
135
136 saved_data = SimpleNamespace()
137 _TestState.saved_data = saved_data
138
139 saved_data.allowed_hosts = settings.ALLOWED_HOSTS
140 # Add the default host of the test client.
141 settings.ALLOWED_HOSTS = [*settings.ALLOWED_HOSTS, "testserver"]
142
143 saved_data.debug = settings.DEBUG
144 settings.DEBUG = debug
145
146 saved_data.email_backend = settings.EMAIL_BACKEND
147 settings.EMAIL_BACKEND = "django.core.mail.backends.locmem.EmailBackend"
148
149 saved_data.template_render = Template._render
150 Template._render = instrumented_test_render
151
152 mail.outbox = []
153
154 deactivate()
155
156
157 def teardown_test_environment():
158 """
159 Perform any global post-test teardown, such as restoring the original
160 template renderer and restoring the email sending functions.
161 """
162 saved_data = _TestState.saved_data
163
164 settings.ALLOWED_HOSTS = saved_data.allowed_hosts
165 settings.DEBUG = saved_data.debug
166 settings.EMAIL_BACKEND = saved_data.email_backend
167 Template._render = saved_data.template_render
168
169 del _TestState.saved_data
170 del mail.outbox
171
172
173 def setup_databases(
174 verbosity,
175 interactive,
176 *,
177 time_keeper=None,
178 keepdb=False,
179 debug_sql=False,
180 parallel=0,
181 aliases=None,
182 serialized_aliases=None,
183 **kwargs,
184 ):
185 """Create the test databases."""
186 if time_keeper is None:
187 time_keeper = NullTimeKeeper()
188
189 test_databases, mirrored_aliases = get_unique_databases_and_mirrors(aliases)
190
191 old_names = []
192 serialize_connections = []
193
194 for db_name, aliases in test_databases.values():
195 first_alias = None
196 for alias in aliases:
197 connection = connections[alias]
198 old_names.append((connection, db_name, first_alias is None))
199
200 # Actually create the database for the first connection
201 if first_alias is None:
202 first_alias = alias
203 with time_keeper.timed(" Creating '%s'" % alias):
204 connection.creation.create_test_db(
205 verbosity=verbosity,
206 autoclobber=not interactive,
207 keepdb=keepdb,
208 serialize=False,
209 )
210 if serialized_aliases is None or alias in serialized_aliases:
211 serialize_connections.append(connection)
212 if parallel > 1:
213 for index in range(parallel):
214 with time_keeper.timed(" Cloning '%s'" % alias):
215 connection.creation.clone_test_db(
216 suffix=str(index + 1),
217 verbosity=verbosity,
218 keepdb=keepdb,
219 )
220 # Configure all other connections as mirrors of the first one
221 else:
222 connections[alias].creation.set_as_test_mirror(
223 connections[first_alias].settings_dict
224 )
225
226 # Configure the test mirrors.
227 for alias, mirror_alias in mirrored_aliases.items():
228 connections[alias].creation.set_as_test_mirror(
229 connections[mirror_alias].settings_dict
230 )
231
232 # Serialize content of test databases only once all of them are setup to
233 # account for database mirroring and routing during serialization. This
234 # slightly horrific process is so people who are testing on databases
235 # without transactions or using TransactionTestCase still get a clean
236 # database on every test run.
237 for serialize_connection in serialize_connections:
238 serialize_connection._test_serialized_contents = (
239 serialize_connection.creation.serialize_db_to_string()
240 )
241
242 if debug_sql:
243 for alias in connections:
244 connections[alias].force_debug_cursor = True
245
246 return old_names
247
248
249 def iter_test_cases(tests):
250 """
251 Return an iterator over a test suite's unittest.TestCase objects.
252
253 The tests argument can also be an iterable of TestCase objects.
254 """
255 for test in tests:
256 if isinstance(test, str):
257 # Prevent an unfriendly RecursionError that can happen with
258 # strings.
259 raise TypeError(
260 f"Test {test!r} must be a test case or test suite not string "
261 f"(was found in {tests!r})."
262 )
263 if isinstance(test, TestCase):
264 yield test
265 else:
266 # Otherwise, assume it is a test suite.
267 yield from iter_test_cases(test)
268
269
270 def dependency_ordered(test_databases, dependencies):
271 """
272 Reorder test_databases into an order that honors the dependencies
273 described in TEST[DEPENDENCIES].
274 """
275 ordered_test_databases = []
276 resolved_databases = set()
277
278 # Maps db signature to dependencies of all its aliases
279 dependencies_map = {}
280
281 # Check that no database depends on its own alias
282 for sig, (_, aliases) in test_databases:
283 all_deps = set()
284 for alias in aliases:
285 all_deps.update(dependencies.get(alias, []))
286 if not all_deps.isdisjoint(aliases):
287 raise ImproperlyConfigured(
288 "Circular dependency: databases %r depend on each other, "
289 "but are aliases." % aliases
290 )
291 dependencies_map[sig] = all_deps
292
293 while test_databases:
294 changed = False
295 deferred = []
296
297 # Try to find a DB that has all its dependencies met
298 for signature, (db_name, aliases) in test_databases:
299 if dependencies_map[signature].issubset(resolved_databases):
300 resolved_databases.update(aliases)
301 ordered_test_databases.append((signature, (db_name, aliases)))
302 changed = True
303 else:
304 deferred.append((signature, (db_name, aliases)))
305
306 if not changed:
307 raise ImproperlyConfigured("Circular dependency in TEST[DEPENDENCIES]")
308 test_databases = deferred
309 return ordered_test_databases
310
311
312 def get_unique_databases_and_mirrors(aliases=None):
313 """
314 Figure out which databases actually need to be created.
315
316 Deduplicate entries in DATABASES that correspond the same database or are
317 configured as test mirrors.
318
319 Return two values:
320 - test_databases: ordered mapping of signatures to (name, list of aliases)
321 where all aliases share the same underlying database.
322 - mirrored_aliases: mapping of mirror aliases to original aliases.
323 """
324 if aliases is None:
325 aliases = connections
326 mirrored_aliases = {}
327 test_databases = {}
328 dependencies = {}
329 default_sig = connections[DEFAULT_DB_ALIAS].creation.test_db_signature()
330
331 for alias in connections:
332 connection = connections[alias]
333 test_settings = connection.settings_dict["TEST"]
334
335 if test_settings["MIRROR"]:
336 # If the database is marked as a test mirror, save the alias.
337 mirrored_aliases[alias] = test_settings["MIRROR"]
338 elif alias in aliases:
339 # Store a tuple with DB parameters that uniquely identify it.
340 # If we have two aliases with the same values for that tuple,
341 # we only need to create the test database once.
342 item = test_databases.setdefault(
343 connection.creation.test_db_signature(),
344 (connection.settings_dict["NAME"], []),
345 )
346 # The default database must be the first because data migrations
347 # use the default alias by default.
348 if alias == DEFAULT_DB_ALIAS:
349 item[1].insert(0, alias)
350 else:
351 item[1].append(alias)
352
353 if "DEPENDENCIES" in test_settings:
354 dependencies[alias] = test_settings["DEPENDENCIES"]
355 else:
356 if (
357 alias != DEFAULT_DB_ALIAS
358 and connection.creation.test_db_signature() != default_sig
359 ):
360 dependencies[alias] = test_settings.get(
361 "DEPENDENCIES", [DEFAULT_DB_ALIAS]
362 )
363
364 test_databases = dict(dependency_ordered(test_databases.items(), dependencies))
365 return test_databases, mirrored_aliases
366
367
368 def teardown_databases(old_config, verbosity, parallel=0, keepdb=False):
369 """Destroy all the non-mirror databases."""
370 for connection, old_name, destroy in old_config:
371 if destroy:
372 if parallel > 1:
373 for index in range(parallel):
374 connection.creation.destroy_test_db(
375 suffix=str(index + 1),
376 verbosity=verbosity,
377 keepdb=keepdb,
378 )
379 connection.creation.destroy_test_db(old_name, verbosity, keepdb)
380
381
382 def get_runner(settings, test_runner_class=None):
383 test_runner_class = test_runner_class or settings.TEST_RUNNER
384 test_path = test_runner_class.split(".")
385 # Allow for relative paths
386 if len(test_path) > 1:
387 test_module_name = ".".join(test_path[:-1])
388 else:
389 test_module_name = "."
390 test_module = __import__(test_module_name, {}, {}, test_path[-1])
391 return getattr(test_module, test_path[-1])
392
393
394 class TestContextDecorator:
395 """
396 A base class that can either be used as a context manager during tests
397 or as a test function or unittest.TestCase subclass decorator to perform
398 temporary alterations.
399
400 `attr_name`: attribute assigned the return value of enable() if used as
401 a class decorator.
402
403 `kwarg_name`: keyword argument passing the return value of enable() if
404 used as a function decorator.
405 """
406
407 def __init__(self, attr_name=None, kwarg_name=None):
408 self.attr_name = attr_name
409 self.kwarg_name = kwarg_name
410
411 def enable(self):
412 raise NotImplementedError
413
414 def disable(self):
415 raise NotImplementedError
416
417 def __enter__(self):
418 return self.enable()
419
420 def __exit__(self, exc_type, exc_value, traceback):
421 self.disable()
422
423 def decorate_class(self, cls):
424 if issubclass(cls, TestCase):
425 decorated_setUp = cls.setUp
426
427 def setUp(inner_self):
428 context = self.enable()
429 inner_self.addCleanup(self.disable)
430 if self.attr_name:
431 setattr(inner_self, self.attr_name, context)
432 decorated_setUp(inner_self)
433
434 cls.setUp = setUp
435 return cls
436 raise TypeError("Can only decorate subclasses of unittest.TestCase")
437
438 def decorate_callable(self, func):
439 if iscoroutinefunction(func):
440 # If the inner function is an async function, we must execute async
441 # as well so that the `with` statement executes at the right time.
442 @wraps(func)
443 async def inner(*args, **kwargs):
444 with self as context:
445 if self.kwarg_name:
446 kwargs[self.kwarg_name] = context
447 return await func(*args, **kwargs)
448
449 else:
450
451 @wraps(func)
452 def inner(*args, **kwargs):
453 with self as context:
454 if self.kwarg_name:
455 kwargs[self.kwarg_name] = context
456 return func(*args, **kwargs)
457
458 return inner
459
460 def __call__(self, decorated):
461 if isinstance(decorated, type):
462 return self.decorate_class(decorated)
463 elif callable(decorated):
464 return self.decorate_callable(decorated)
465 raise TypeError("Cannot decorate object of type %s" % type(decorated))
466
467
468 class override_settings(TestContextDecorator):
469 """
470 Act as either a decorator or a context manager. If it's a decorator, take a
471 function and return a wrapped function. If it's a contextmanager, use it
472 with the ``with`` statement. In either event, entering/exiting are called
473 before and after, respectively, the function/block is executed.
474 """
475
476 enable_exception = None
477
478 def __init__(self, **kwargs):
479 self.options = kwargs
480 super().__init__()
481
482 def enable(self):
483 # Keep this code at the beginning to leave the settings unchanged
484 # in case it raises an exception because INSTALLED_APPS is invalid.
485 if "INSTALLED_APPS" in self.options:
486 try:
487 apps.set_installed_apps(self.options["INSTALLED_APPS"])
488 except Exception:
489 apps.unset_installed_apps()
490 raise
491 override = UserSettingsHolder(settings._wrapped)
492 for key, new_value in self.options.items():
493 setattr(override, key, new_value)
494 self.wrapped = settings._wrapped
495 settings._wrapped = override
496 for key, new_value in self.options.items():
497 try:
498 setting_changed.send(
499 sender=settings._wrapped.__class__,
500 setting=key,
501 value=new_value,
502 enter=True,
503 )
504 except Exception as exc:
505 self.enable_exception = exc
506 self.disable()
507
508 def disable(self):
509 if "INSTALLED_APPS" in self.options:
510 apps.unset_installed_apps()
511 settings._wrapped = self.wrapped
512 del self.wrapped
513 responses = []
514 for key in self.options:
515 new_value = getattr(settings, key, None)
516 responses_for_setting = setting_changed.send_robust(
517 sender=settings._wrapped.__class__,
518 setting=key,
519 value=new_value,
520 enter=False,
521 )
522 responses.extend(responses_for_setting)
523 if self.enable_exception is not None:
524 exc = self.enable_exception
525 self.enable_exception = None
526 raise exc
527 for _, response in responses:
528 if isinstance(response, Exception):
529 raise response
530
531 def save_options(self, test_func):
532 if test_func._overridden_settings is None:
533 test_func._overridden_settings = self.options
534 else:
535 # Duplicate dict to prevent subclasses from altering their parent.
536 test_func._overridden_settings = {
537 **test_func._overridden_settings,
538 **self.options,
539 }
540
541 def decorate_class(self, cls):
542 from django.test import SimpleTestCase
543
544 if not issubclass(cls, SimpleTestCase):
545 raise ValueError(
546 "Only subclasses of Django SimpleTestCase can be decorated "
547 "with override_settings"
548 )
549 self.save_options(cls)
550 return cls
551
552
553 class modify_settings(override_settings):
554 """
555 Like override_settings, but makes it possible to append, prepend, or remove
556 items instead of redefining the entire list.
557 """
558
559 def __init__(self, *args, **kwargs):
560 if args:
561 # Hack used when instantiating from SimpleTestCase.setUpClass.
562 assert not kwargs
563 self.operations = args[0]
564 else:
565 assert not args
566 self.operations = list(kwargs.items())
567 super(override_settings, self).__init__()
568
569 def save_options(self, test_func):
570 if test_func._modified_settings is None:
571 test_func._modified_settings = self.operations
572 else:
573 # Duplicate list to prevent subclasses from altering their parent.
574 test_func._modified_settings = (
575 list(test_func._modified_settings) + self.operations
576 )
577
578 def enable(self):
579 self.options = {}
580 for name, operations in self.operations:
581 try:
582 # When called from SimpleTestCase.setUpClass, values may be
583 # overridden several times; cumulate changes.
584 value = self.options[name]
585 except KeyError:
586 value = list(getattr(settings, name, []))
587 for action, items in operations.items():
588 # items may be a single value or an iterable.
589 if isinstance(items, str):
590 items = [items]
591 if action == "append":
592 value += [item for item in items if item not in value]
593 elif action == "prepend":
594 value = [item for item in items if item not in value] + value
595 elif action == "remove":
596 value = [item for item in value if item not in items]
597 else:
598 raise ValueError("Unsupported action: %s" % action)
599 self.options[name] = value
600 super().enable()
601
602
603 class override_system_checks(TestContextDecorator):
604 """
605 Act as a decorator. Override list of registered system checks.
606 Useful when you override `INSTALLED_APPS`, e.g. if you exclude `auth` app,
607 you also need to exclude its system checks.
608 """
609
610 def __init__(self, new_checks, deployment_checks=None):
611 from django.core.checks.registry import registry
612
613 self.registry = registry
614 self.new_checks = new_checks
615 self.deployment_checks = deployment_checks
616 super().__init__()
617
618 def enable(self):
619 self.old_checks = self.registry.registered_checks
620 self.registry.registered_checks = set()
621 for check in self.new_checks:
622 self.registry.register(check, *getattr(check, "tags", ()))
623 self.old_deployment_checks = self.registry.deployment_checks
624 if self.deployment_checks is not None:
625 self.registry.deployment_checks = set()
626 for check in self.deployment_checks:
627 self.registry.register(check, *getattr(check, "tags", ()), deploy=True)
628
629 def disable(self):
630 self.registry.registered_checks = self.old_checks
631 self.registry.deployment_checks = self.old_deployment_checks
632
633
634 def compare_xml(want, got):
635 """
636 Try to do a 'xml-comparison' of want and got. Plain string comparison
637 doesn't always work because, for example, attribute ordering should not be
638 important. Ignore comment nodes, processing instructions, document type
639 node, and leading and trailing whitespaces.
640
641 Based on https://github.com/lxml/lxml/blob/master/src/lxml/doctestcompare.py
642 """
643 _norm_whitespace_re = re.compile(r"[ \t\n][ \t\n]+")
644
645 def norm_whitespace(v):
646 return _norm_whitespace_re.sub(" ", v)
647
648 def child_text(element):
649 return "".join(
650 c.data for c in element.childNodes if c.nodeType == Node.TEXT_NODE
651 )
652
653 def children(element):
654 return [c for c in element.childNodes if c.nodeType == Node.ELEMENT_NODE]
655
656 def norm_child_text(element):
657 return norm_whitespace(child_text(element))
658
659 def attrs_dict(element):
660 return dict(element.attributes.items())
661
662 def check_element(want_element, got_element):
663 if want_element.tagName != got_element.tagName:
664 return False
665 if norm_child_text(want_element) != norm_child_text(got_element):
666 return False
667 if attrs_dict(want_element) != attrs_dict(got_element):
668 return False
669 want_children = children(want_element)
670 got_children = children(got_element)
671 if len(want_children) != len(got_children):
672 return False
673 return all(
674 check_element(want, got) for want, got in zip(want_children, got_children)
675 )
676
677 def first_node(document):
678 for node in document.childNodes:
679 if node.nodeType not in (
680 Node.COMMENT_NODE,
681 Node.DOCUMENT_TYPE_NODE,
682 Node.PROCESSING_INSTRUCTION_NODE,
683 ):
684 return node
685
686 want = want.strip().replace("\\n", "\n")
687 got = got.strip().replace("\\n", "\n")
688
689 # If the string is not a complete xml document, we may need to add a
690 # root element. This allow us to compare fragments, like "<foo/><bar/>"
691 if not want.startswith("<?xml"):
692 wrapper = "<root>%s</root>"
693 want = wrapper % want
694 got = wrapper % got
695
696 # Parse the want and got strings, and compare the parsings.
697 want_root = first_node(parseString(want))
698 got_root = first_node(parseString(got))
699
700 return check_element(want_root, got_root)
701
702
703 class CaptureQueriesContext:
704 """
705 Context manager that captures queries executed by the specified connection.
706 """
707
708 def __init__(self, connection):
709 self.connection = connection
710
711 def __iter__(self):
712 return iter(self.captured_queries)
713
714 def __getitem__(self, index):
715 return self.captured_queries[index]
716
717 def __len__(self):
718 return len(self.captured_queries)
719
720 @property
721 def captured_queries(self):
722 return self.connection.queries[self.initial_queries : self.final_queries]
723
724 def __enter__(self):
725 self.force_debug_cursor = self.connection.force_debug_cursor
726 self.connection.force_debug_cursor = True
727 # Run any initialization queries if needed so that they won't be
728 # included as part of the count.
729 self.connection.ensure_connection()
730 self.initial_queries = len(self.connection.queries_log)
731 self.final_queries = None
732 request_started.disconnect(reset_queries)
733 return self
734
735 def __exit__(self, exc_type, exc_value, traceback):
736 self.connection.force_debug_cursor = self.force_debug_cursor
737 request_started.connect(reset_queries)
738 if exc_type is not None:
739 return
740 self.final_queries = len(self.connection.queries_log)
741
742
743 class ignore_warnings(TestContextDecorator):
744 def __init__(self, **kwargs):
745 self.ignore_kwargs = kwargs
746 if "message" in self.ignore_kwargs or "module" in self.ignore_kwargs:
747 self.filter_func = warnings.filterwarnings
748 else:
749 self.filter_func = warnings.simplefilter
750 super().__init__()
751
752 def enable(self):
753 self.catch_warnings = warnings.catch_warnings()
754 self.catch_warnings.__enter__()
755 self.filter_func("ignore", **self.ignore_kwargs)
756
757 def disable(self):
758 self.catch_warnings.__exit__(*sys.exc_info())
759
760
761 # On OSes that don't provide tzset (Windows), we can't set the timezone
762 # in which the program runs. As a consequence, we must skip tests that
763 # don't enforce a specific timezone (with timezone.override or equivalent),
764 # or attempt to interpret naive datetimes in the default timezone.
765
766 requires_tz_support = skipUnless(
767 TZ_SUPPORT,
768 "This test relies on the ability to run a program in an arbitrary "
769 "time zone, but your operating system isn't able to do that.",
770 )
771
772
773 @contextmanager
774 def extend_sys_path(*paths):
775 """Context manager to temporarily add paths to sys.path."""
776 _orig_sys_path = sys.path[:]
777 sys.path.extend(paths)
778 try:
779 yield
780 finally:
781 sys.path = _orig_sys_path
782
783
784 @contextmanager
785 def isolate_lru_cache(lru_cache_object):
786 """Clear the cache of an LRU cache object on entering and exiting."""
787 lru_cache_object.cache_clear()
788 try:
789 yield
790 finally:
791 lru_cache_object.cache_clear()
792
793
794 @contextmanager
795 def captured_output(stream_name):
796 """Return a context manager used by captured_stdout/stdin/stderr
797 that temporarily replaces the sys stream *stream_name* with a StringIO.
798
799 Note: This function and the following ``captured_std*`` are copied
800 from CPython's ``test.support`` module."""
801 orig_stdout = getattr(sys, stream_name)
802 setattr(sys, stream_name, StringIO())
803 try:
804 yield getattr(sys, stream_name)
805 finally:
806 setattr(sys, stream_name, orig_stdout)
807
808
809 def captured_stdout():
810 """Capture the output of sys.stdout:
811
812 with captured_stdout() as stdout:
813 print("hello")
814 self.assertEqual(stdout.getvalue(), "hello\n")
815 """
816 return captured_output("stdout")
817
818
819 def captured_stderr():
820 """Capture the output of sys.stderr:
821
822 with captured_stderr() as stderr:
823 print("hello", file=sys.stderr)
824 self.assertEqual(stderr.getvalue(), "hello\n")
825 """
826 return captured_output("stderr")
827
828
829 def captured_stdin():
830 """Capture the input to sys.stdin:
831
832 with captured_stdin() as stdin:
833 stdin.write('hello\n')
834 stdin.seek(0)
835 # call test code that consumes from sys.stdin
836 captured = input()
837 self.assertEqual(captured, "hello")
838 """
839 return captured_output("stdin")
840
841
842 @contextmanager
843 def freeze_time(t):
844 """
845 Context manager to temporarily freeze time.time(). This temporarily
846 modifies the time function of the time module. Modules which import the
847 time function directly (e.g. `from time import time`) won't be affected
848 This isn't meant as a public API, but helps reduce some repetitive code in
849 Django's test suite.
850 """
851 _real_time = time.time
852 time.time = lambda: t
853 try:
854 yield
855 finally:
856 time.time = _real_time
857
858
859 def require_jinja2(test_func):
860 """
861 Decorator to enable a Jinja2 template engine in addition to the regular
862 Django template engine for a test or skip it if Jinja2 isn't available.
863 """
864 test_func = skipIf(jinja2 is None, "this test requires jinja2")(test_func)
865 return override_settings(
866 TEMPLATES=[
867 {
868 "BACKEND": "django.template.backends.django.DjangoTemplates",
869 "APP_DIRS": True,
870 },
871 {
872 "BACKEND": "django.template.backends.jinja2.Jinja2",
873 "APP_DIRS": True,
874 "OPTIONS": {"keep_trailing_newline": True},
875 },
876 ]
877 )(test_func)
878
879
880 class override_script_prefix(TestContextDecorator):
881 """Decorator or context manager to temporary override the script prefix."""
882
883 def __init__(self, prefix):
884 self.prefix = prefix
885 super().__init__()
886
887 def enable(self):
888 self.old_prefix = get_script_prefix()
889 set_script_prefix(self.prefix)
890
891 def disable(self):
892 set_script_prefix(self.old_prefix)
893
894
895 class LoggingCaptureMixin:
896 """
897 Capture the output from the 'django' logger and store it on the class's
898 logger_output attribute.
899 """
900
901 def setUp(self):
902 self.logger = logging.getLogger("django")
903 self.old_stream = self.logger.handlers[0].stream
904 self.logger_output = StringIO()
905 self.logger.handlers[0].stream = self.logger_output
906
907 def tearDown(self):
908 self.logger.handlers[0].stream = self.old_stream
909
910
911 class isolate_apps(TestContextDecorator):
912 """
913 Act as either a decorator or a context manager to register models defined
914 in its wrapped context to an isolated registry.
915
916 The list of installed apps the isolated registry should contain must be
917 passed as arguments.
918
919 Two optional keyword arguments can be specified:
920
921 `attr_name`: attribute assigned the isolated registry if used as a class
922 decorator.
923
924 `kwarg_name`: keyword argument passing the isolated registry if used as a
925 function decorator.
926 """
927
928 def __init__(self, *installed_apps, **kwargs):
929 self.installed_apps = installed_apps
930 super().__init__(**kwargs)
931
932 def enable(self):
933 self.old_apps = Options.default_apps
934 apps = Apps(self.installed_apps)
935 setattr(Options, "default_apps", apps)
936 return apps
937
938 def disable(self):
939 setattr(Options, "default_apps", self.old_apps)
940
941
942 class TimeKeeper:
943 def __init__(self):
944 self.records = collections.defaultdict(list)
945
946 @contextmanager
947 def timed(self, name):
948 self.records[name]
949 start_time = time.perf_counter()
950 try:
951 yield
952 finally:
953 end_time = time.perf_counter() - start_time
954 self.records[name].append(end_time)
955
956 def print_results(self):
957 for name, end_times in self.records.items():
958 for record_time in end_times:
959 record = "%s took %.3fs" % (name, record_time)
960 sys.stderr.write(record + os.linesep)
961
962
963 class NullTimeKeeper:
964 @contextmanager
965 def timed(self, name):
966 yield
967
968 def print_results(self):
969 pass
970
971
972 def tag(*tags):
973 """Decorator to add tags to a test class or method."""
974
975 def decorator(obj):
976 if hasattr(obj, "tags"):
977 obj.tags = obj.tags.union(tags)
978 else:
979 setattr(obj, "tags", set(tags))
980 return obj
981
982 return decorator
983
984
985 @contextmanager
986 def register_lookup(field, *lookups, lookup_name=None):
987 """
988 Context manager to temporarily register lookups on a model field using
989 lookup_name (or the lookup's lookup_name if not provided).
990 """
991 try:
992 for lookup in lookups:
993 field.register_lookup(lookup, lookup_name)
994 yield
995 finally:
996 for lookup in lookups:
997 field._unregister_lookup(lookup, lookup_name)
998
999
1000 def garbage_collect():
1001 gc.collect()
1002 if PYPY:
1003 # Collecting weakreferences can take two collections on PyPy.
1004 gc.collect()