unittest

 25class TestResult(object):
 26    """Holder for test result information.
 27
 28    Test results are automatically managed by the TestCase and TestSuite
 29    classes, and do not need to be explicitly manipulated by writers of tests.
 30
 31    Each instance holds the total number of tests run, and collections of
 32    failures and errors that occurred among those test runs. The collections
 33    contain tuples of (testcase, exceptioninfo), where exceptioninfo is the
 34    formatted traceback of the error that occurred.
 35    """
 36    _previousTestClass = None
 37    _testRunEntered = False
 38    _moduleSetUpFailed = False
 39    def __init__(self, stream=None, descriptions=None, verbosity=None):
 40        self.failfast = False
 41        self.failures = []
 42        self.errors = []
 43        self.testsRun = 0
 44        self.skipped = []
 45        self.expectedFailures = []
 46        self.unexpectedSuccesses = []
 47        self.collectedDurations = []
 48        self.shouldStop = False
 49        self.buffer = False
 50        self.tb_locals = False
 51        self._stdout_buffer = None
 52        self._stderr_buffer = None
 53        self._original_stdout = sys.stdout
 54        self._original_stderr = sys.stderr
 55        self._mirrorOutput = False
 56
 57    def printErrors(self):
 58        "Called by TestRunner after test run"
 59
 60    def startTest(self, test):
 61        "Called when the given test is about to be run"
 62        self.testsRun += 1
 63        self._mirrorOutput = False
 64        self._setupStdout()
 65
 66    def _setupStdout(self):
 67        if self.buffer:
 68            if self._stderr_buffer is None:
 69                self._stderr_buffer = io.StringIO()
 70                self._stdout_buffer = io.StringIO()
 71            sys.stdout = self._stdout_buffer
 72            sys.stderr = self._stderr_buffer
 73
 74    def startTestRun(self):
 75        """Called once before any tests are executed.
 76
 77        See startTest for a method called before each test.
 78        """
 79
 80    def stopTest(self, test):
 81        """Called when the given test has been run"""
 82        self._restoreStdout()
 83        self._mirrorOutput = False
 84
 85    def _restoreStdout(self):
 86        if self.buffer:
 87            if self._mirrorOutput:
 88                output = sys.stdout.getvalue()
 89                error = sys.stderr.getvalue()
 90                if output:
 91                    if not output.endswith('\n'):
 92                        output += '\n'
 93                    self._original_stdout.write(STDOUT_LINE % output)
 94                if error:
 95                    if not error.endswith('\n'):
 96                        error += '\n'
 97                    self._original_stderr.write(STDERR_LINE % error)
 98
 99            sys.stdout = self._original_stdout
100            sys.stderr = self._original_stderr
101            self._stdout_buffer.seek(0)
102            self._stdout_buffer.truncate()
103            self._stderr_buffer.seek(0)
104            self._stderr_buffer.truncate()
105
106    def stopTestRun(self):
107        """Called once after all tests are executed.
108
109        See stopTest for a method called after each test.
110        """
111
112    @failfast
113    def addError(self, test, err):
114        """Called when an error has occurred. 'err' is a tuple of values as
115        returned by sys.exc_info().
116        """
117        self.errors.append((test, self._exc_info_to_string(err, test)))
118        self._mirrorOutput = True
119
120    @failfast
121    def addFailure(self, test, err):
122        """Called when an error has occurred. 'err' is a tuple of values as
123        returned by sys.exc_info()."""
124        self.failures.append((test, self._exc_info_to_string(err, test)))
125        self._mirrorOutput = True
126
127    def addSubTest(self, test, subtest, err):
128        """Called at the end of a subtest.
129        'err' is None if the subtest ended successfully, otherwise it's a
130        tuple of values as returned by sys.exc_info().
131        """
132        # By default, we don't do anything with successful subtests, but
133        # more sophisticated test results might want to record them.
134        if err is not None:
135            if getattr(self, 'failfast', False):
136                self.stop()
137            if issubclass(err[0], test.failureException):
138                errors = self.failures
139            else:
140                errors = self.errors
141            errors.append((subtest, self._exc_info_to_string(err, test)))
142            self._mirrorOutput = True
143
144    def addSuccess(self, test):
145        "Called when a test has completed successfully"
146        pass
147
148    def addSkip(self, test, reason):
149        """Called when a test is skipped."""
150        self.skipped.append((test, reason))
151
152    def addExpectedFailure(self, test, err):
153        """Called when an expected failure/error occurred."""
154        self.expectedFailures.append(
155            (test, self._exc_info_to_string(err, test)))
156
157    @failfast
158    def addUnexpectedSuccess(self, test):
159        """Called when a test was expected to fail, but succeed."""
160        self.unexpectedSuccesses.append(test)
161
162    def addDuration(self, test, elapsed):
163        """Called when a test finished to run, regardless of its outcome.
164        *test* is the test case corresponding to the test method.
165        *elapsed* is the time represented in seconds, and it includes the
166        execution of cleanup functions.
167        """
168        # support for a TextTestRunner using an old TestResult class
169        if hasattr(self, "collectedDurations"):
170            # Pass test repr and not the test object itself to avoid resources leak
171            self.collectedDurations.append((str(test), elapsed))
172
173    def wasSuccessful(self):
174        """Tells whether or not this result was a success."""
175        # The hasattr check is for test_result's OldResult test.  That
176        # way this method works on objects that lack the attribute.
177        # (where would such result instances come from? old stored pickles?)
178        return ((len(self.failures) == len(self.errors) == 0) and
179                (not hasattr(self, 'unexpectedSuccesses') or
180                 len(self.unexpectedSuccesses) == 0))
181
182    def stop(self):
183        """Indicates that the tests should be aborted."""
184        self.shouldStop = True
185
186    def _exc_info_to_string(self, err, test):
187        """Converts a sys.exc_info()-style tuple of values into a string."""
188        exctype, value, tb = err
189        tb = self._clean_tracebacks(exctype, value, tb, test)
190        tb_e = traceback.TracebackException(
191            exctype, value, tb,
192            capture_locals=self.tb_locals, compact=True)
193        msgLines = list(tb_e.format())
194
195        if self.buffer:
196            output = sys.stdout.getvalue()
197            error = sys.stderr.getvalue()
198            if output:
199                if not output.endswith('\n'):
200                    output += '\n'
201                msgLines.append(STDOUT_LINE % output)
202            if error:
203                if not error.endswith('\n'):
204                    error += '\n'
205                msgLines.append(STDERR_LINE % error)
206        return ''.join(msgLines)
207
208    def _clean_tracebacks(self, exctype, value, tb, test):
209        ret = None
210        first = True
211        excs = [(exctype, value, tb)]
212        seen = {id(value)}  # Detect loops in chained exceptions.
213        while excs:
214            (exctype, value, tb) = excs.pop()
215            # Skip test runner traceback levels
216            while tb and self._is_relevant_tb_level(tb):
217                tb = tb.tb_next
218
219            # Skip assert*() traceback levels
220            if exctype is test.failureException:
221                self._remove_unittest_tb_frames(tb)
222
223            if first:
224                ret = tb
225                first = False
226            else:
227                value.__traceback__ = tb
228
229            if value is not None:
230                for c in (value.__cause__, value.__context__):
231                    if c is not None and id(c) not in seen:
232                        excs.append((type(c), c, c.__traceback__))
233                        seen.add(id(c))
234        return ret
235
236    def _is_relevant_tb_level(self, tb):
237        return '__unittest' in tb.tb_frame.f_globals
238
239    def _remove_unittest_tb_frames(self, tb):
240        '''Truncates usercode tb at the first unittest frame.
241
242        If the first frame of the traceback is in user code,
243        the prefix up to the first unittest frame is returned.
244        If the first frame is already in the unittest module,
245        the traceback is not modified.
246        '''
247        prev = None
248        while tb and not self._is_relevant_tb_level(tb):
249            prev = tb
250            tb = tb.tb_next
251        if prev is not None:
252            prev.tb_next = None
253
254    def __repr__(self):
255        return ("<%s run=%i errors=%i failures=%i>" %
256               (util.strclass(self.__class__), self.testsRun, len(self.errors),
257                len(self.failures)))

 363class TestCase(object):
 364    """A class whose instances are single test cases.
 365
 366    By default, the test code itself should be placed in a method named
 367    'runTest'.
 368
 369    If the fixture may be used for many test cases, create as
 370    many test methods as are needed. When instantiating such a TestCase
 371    subclass, specify in the constructor arguments the name of the test method
 372    that the instance is to execute.
 373
 374    Test authors should subclass TestCase for their own tests. Construction
 375    and deconstruction of the test's environment ('fixture') can be
 376    implemented by overriding the 'setUp' and 'tearDown' methods respectively.
 377
 378    If it is necessary to override the __init__ method, the base class
 379    __init__ method must always be called. It is important that subclasses
 380    should not change the signature of their __init__ method, since instances
 381    of the classes are instantiated automatically by parts of the framework
 382    in order to be run.
 383
 384    When subclassing TestCase, you can set these attributes:
 385    * failureException: determines which exception will be raised when
 386        the instance's assertion methods fail; test methods raising this
 387        exception will be deemed to have 'failed' rather than 'errored'.
 388    * longMessage: determines whether long messages (including repr of
 389        objects used in assert methods) will be printed on failure in *addition*
 390        to any explicit message passed.
 391    * maxDiff: sets the maximum length of a diff in failure messages
 392        by assert methods using difflib. It is looked up as an instance
 393        attribute so can be configured by individual tests if required.
 394    """
 395
 396    failureException = AssertionError
 397
 398    longMessage = True
 399
 400    maxDiff = 80*8
 401
 402    # If a string is longer than _diffThreshold, use normal comparison instead
 403    # of difflib.  See #11763.
 404    _diffThreshold = 2**16
 405
 406    def __init_subclass__(cls, *args, **kwargs):
 407        # Attribute used by TestSuite for classSetUp
 408        cls._classSetupFailed = False
 409        cls._class_cleanups = []
 410        super().__init_subclass__(*args, **kwargs)
 411
 412    def __init__(self, methodName='runTest'):
 413        """Create an instance of the class that will use the named test
 414           method when executed. Raises a ValueError if the instance does
 415           not have a method with the specified name.
 416        """
 417        self._testMethodName = methodName
 418        self._outcome = None
 419        self._testMethodDoc = 'No test'
 420        try:
 421            testMethod = getattr(self, methodName)
 422        except AttributeError:
 423            if methodName != 'runTest':
 424                # we allow instantiation with no explicit method name
 425                # but not an *incorrect* or missing method name
 426                raise ValueError("no such test method in %s: %s" %
 427                      (self.__class__, methodName))
 428        else:
 429            self._testMethodDoc = testMethod.__doc__
 430        self._cleanups = []
 431        self._subtest = None
 432
 433        # Map types to custom assertEqual functions that will compare
 434        # instances of said type in more detail to generate a more useful
 435        # error message.
 436        self._type_equality_funcs = {}
 437        self.addTypeEqualityFunc(dict, 'assertDictEqual')
 438        self.addTypeEqualityFunc(list, 'assertListEqual')
 439        self.addTypeEqualityFunc(tuple, 'assertTupleEqual')
 440        self.addTypeEqualityFunc(set, 'assertSetEqual')
 441        self.addTypeEqualityFunc(frozenset, 'assertSetEqual')
 442        self.addTypeEqualityFunc(str, 'assertMultiLineEqual')
 443
 444    def addTypeEqualityFunc(self, typeobj, function):
 445        """Add a type specific assertEqual style function to compare a type.
 446
 447        This method is for use by TestCase subclasses that need to register
 448        their own type equality functions to provide nicer error messages.
 449
 450        Args:
 451            typeobj: The data type to call this function on when both values
 452                    are of the same type in assertEqual().
 453            function: The callable taking two arguments and an optional
 454                    msg= argument that raises self.failureException with a
 455                    useful error message when the two arguments are not equal.
 456        """
 457        self._type_equality_funcs[typeobj] = function
 458
 459    def addCleanup(self, function, /, *args, **kwargs):
 460        """Add a function, with arguments, to be called when the test is
 461        completed. Functions added are called on a LIFO basis and are
 462        called after tearDown on test failure or success.
 463
 464        Cleanup items are called even if setUp fails (unlike tearDown)."""
 465        self._cleanups.append((function, args, kwargs))
 466
 467    def enterContext(self, cm):
 468        """Enters the supplied context manager.
 469
 470        If successful, also adds its __exit__ method as a cleanup
 471        function and returns the result of the __enter__ method.
 472        """
 473        return _enter_context(cm, self.addCleanup)
 474
 475    @classmethod
 476    def addClassCleanup(cls, function, /, *args, **kwargs):
 477        """Same as addCleanup, except the cleanup items are called even if
 478        setUpClass fails (unlike tearDownClass)."""
 479        cls._class_cleanups.append((function, args, kwargs))
 480
 481    @classmethod
 482    def enterClassContext(cls, cm):
 483        """Same as enterContext, but class-wide."""
 484        return _enter_context(cm, cls.addClassCleanup)
 485
 486    def setUp(self):
 487        "Hook method for setting up the test fixture before exercising it."
 488        pass
 489
 490    def tearDown(self):
 491        "Hook method for deconstructing the test fixture after testing it."
 492        pass
 493
 494    @classmethod
 495    def setUpClass(cls):
 496        "Hook method for setting up class fixture before running tests in the class."
 497
 498    @classmethod
 499    def tearDownClass(cls):
 500        "Hook method for deconstructing the class fixture after running all tests in the class."
 501
 502    def countTestCases(self):
 503        return 1
 504
 505    def defaultTestResult(self):
 506        return result.TestResult()
 507
 508    def shortDescription(self):
 509        """Returns a one-line description of the test, or None if no
 510        description has been provided.
 511
 512        The default implementation of this method returns the first line of
 513        the specified test method's docstring.
 514        """
 515        doc = self._testMethodDoc
 516        return doc.strip().split("\n")[0].strip() if doc else None
 517
 518
 519    def id(self):
 520        return "%s.%s" % (strclass(self.__class__), self._testMethodName)
 521
 522    def __eq__(self, other):
 523        if type(self) is not type(other):
 524            return NotImplemented
 525
 526        return self._testMethodName == other._testMethodName
 527
 528    def __hash__(self):
 529        return hash((type(self), self._testMethodName))
 530
 531    def __str__(self):
 532        return "%s (%s.%s)" % (self._testMethodName, strclass(self.__class__), self._testMethodName)
 533
 534    def __repr__(self):
 535        return "<%s testMethod=%s>" % \
 536               (strclass(self.__class__), self._testMethodName)
 537
 538    @contextlib.contextmanager
 539    def subTest(self, msg=_subtest_msg_sentinel, **params):
 540        """Return a context manager that will return the enclosed block
 541        of code in a subtest identified by the optional message and
 542        keyword parameters.  A failure in the subtest marks the test
 543        case as failed but resumes execution at the end of the enclosed
 544        block, allowing further test code to be executed.
 545        """
 546        if self._outcome is None or not self._outcome.result_supports_subtests:
 547            yield
 548            return
 549        parent = self._subtest
 550        if parent is None:
 551            params_map = _OrderedChainMap(params)
 552        else:
 553            params_map = parent.params.new_child(params)
 554        self._subtest = _SubTest(self, msg, params_map)
 555        try:
 556            with self._outcome.testPartExecutor(self._subtest, subTest=True):
 557                yield
 558            if not self._outcome.success:
 559                result = self._outcome.result
 560                if result is not None and result.failfast:
 561                    raise _ShouldStop
 562            elif self._outcome.expectedFailure:
 563                # If the test is expecting a failure, we really want to
 564                # stop now and register the expected failure.
 565                raise _ShouldStop
 566        finally:
 567            self._subtest = parent
 568
 569    def _addExpectedFailure(self, result, exc_info):
 570        try:
 571            addExpectedFailure = result.addExpectedFailure
 572        except AttributeError:
 573            warnings.warn("TestResult has no addExpectedFailure method, reporting as passes",
 574                          RuntimeWarning)
 575            result.addSuccess(self)
 576        else:
 577            addExpectedFailure(self, exc_info)
 578
 579    def _addUnexpectedSuccess(self, result):
 580        try:
 581            addUnexpectedSuccess = result.addUnexpectedSuccess
 582        except AttributeError:
 583            warnings.warn("TestResult has no addUnexpectedSuccess method, reporting as failure",
 584                          RuntimeWarning)
 585            # We need to pass an actual exception and traceback to addFailure,
 586            # otherwise the legacy result can choke.
 587            try:
 588                raise _UnexpectedSuccess from None
 589            except _UnexpectedSuccess:
 590                result.addFailure(self, sys.exc_info())
 591        else:
 592            addUnexpectedSuccess(self)
 593
 594    def _addDuration(self, result, elapsed):
 595        try:
 596            addDuration = result.addDuration
 597        except AttributeError:
 598            warnings.warn("TestResult has no addDuration method",
 599                          RuntimeWarning)
 600        else:
 601            addDuration(self, elapsed)
 602
 603    def _callSetUp(self):
 604        self.setUp()
 605
 606    def _callTestMethod(self, method):
 607        if method() is not None:
 608            warnings.warn(f'It is deprecated to return a value that is not None from a '
 609                          f'test case ({method})', DeprecationWarning, stacklevel=3)
 610
 611    def _callTearDown(self):
 612        self.tearDown()
 613
 614    def _callCleanup(self, function, /, *args, **kwargs):
 615        function(*args, **kwargs)
 616
 617    def run(self, result=None):
 618        if result is None:
 619            result = self.defaultTestResult()
 620            startTestRun = getattr(result, 'startTestRun', None)
 621            stopTestRun = getattr(result, 'stopTestRun', None)
 622            if startTestRun is not None:
 623                startTestRun()
 624        else:
 625            stopTestRun = None
 626
 627        result.startTest(self)
 628        try:
 629            testMethod = getattr(self, self._testMethodName)
 630            if (getattr(self.__class__, "__unittest_skip__", False) or
 631                getattr(testMethod, "__unittest_skip__", False)):
 632                # If the class or method was skipped.
 633                skip_why = (getattr(self.__class__, '__unittest_skip_why__', '')
 634                            or getattr(testMethod, '__unittest_skip_why__', ''))
 635                _addSkip(result, self, skip_why)
 636                return result
 637
 638            expecting_failure = (
 639                getattr(self, "__unittest_expecting_failure__", False) or
 640                getattr(testMethod, "__unittest_expecting_failure__", False)
 641            )
 642            outcome = _Outcome(result)
 643            start_time = time.perf_counter()
 644            try:
 645                self._outcome = outcome
 646
 647                with outcome.testPartExecutor(self):
 648                    self._callSetUp()
 649                if outcome.success:
 650                    outcome.expecting_failure = expecting_failure
 651                    with outcome.testPartExecutor(self):
 652                        self._callTestMethod(testMethod)
 653                    outcome.expecting_failure = False
 654                    with outcome.testPartExecutor(self):
 655                        self._callTearDown()
 656                self.doCleanups()
 657                self._addDuration(result, (time.perf_counter() - start_time))
 658
 659                if outcome.success:
 660                    if expecting_failure:
 661                        if outcome.expectedFailure:
 662                            self._addExpectedFailure(result, outcome.expectedFailure)
 663                        else:
 664                            self._addUnexpectedSuccess(result)
 665                    else:
 666                        result.addSuccess(self)
 667                return result
 668            finally:
 669                # explicitly break reference cycle:
 670                # outcome.expectedFailure -> frame -> outcome -> outcome.expectedFailure
 671                outcome.expectedFailure = None
 672                outcome = None
 673
 674                # clear the outcome, no more needed
 675                self._outcome = None
 676
 677        finally:
 678            result.stopTest(self)
 679            if stopTestRun is not None:
 680                stopTestRun()
 681
 682    def doCleanups(self):
 683        """Execute all cleanup functions. Normally called for you after
 684        tearDown."""
 685        outcome = self._outcome or _Outcome()
 686        while self._cleanups:
 687            function, args, kwargs = self._cleanups.pop()
 688            with outcome.testPartExecutor(self):
 689                self._callCleanup(function, *args, **kwargs)
 690
 691        # return this for backwards compatibility
 692        # even though we no longer use it internally
 693        return outcome.success
 694
 695    @classmethod
 696    def doClassCleanups(cls):
 697        """Execute all class cleanup functions. Normally called for you after
 698        tearDownClass."""
 699        cls.tearDown_exceptions = []
 700        while cls._class_cleanups:
 701            function, args, kwargs = cls._class_cleanups.pop()
 702            try:
 703                function(*args, **kwargs)
 704            except Exception:
 705                cls.tearDown_exceptions.append(sys.exc_info())
 706
 707    def __call__(self, *args, **kwds):
 708        return self.run(*args, **kwds)
 709
 710    def debug(self):
 711        """Run the test without collecting errors in a TestResult"""
 712        testMethod = getattr(self, self._testMethodName)
 713        if (getattr(self.__class__, "__unittest_skip__", False) or
 714            getattr(testMethod, "__unittest_skip__", False)):
 715            # If the class or method was skipped.
 716            skip_why = (getattr(self.__class__, '__unittest_skip_why__', '')
 717                        or getattr(testMethod, '__unittest_skip_why__', ''))
 718            raise SkipTest(skip_why)
 719
 720        self._callSetUp()
 721        self._callTestMethod(testMethod)
 722        self._callTearDown()
 723        while self._cleanups:
 724            function, args, kwargs = self._cleanups.pop()
 725            self._callCleanup(function, *args, **kwargs)
 726
 727    def skipTest(self, reason):
 728        """Skip this test."""
 729        raise SkipTest(reason)
 730
 731    def fail(self, msg=None):
 732        """Fail immediately, with the given message."""
 733        raise self.failureException(msg)
 734
 735    def assertFalse(self, expr, msg=None):
 736        """Check that the expression is false."""
 737        if expr:
 738            msg = self._formatMessage(msg, "%s is not false" % safe_repr(expr))
 739            raise self.failureException(msg)
 740
 741    def assertTrue(self, expr, msg=None):
 742        """Check that the expression is true."""
 743        if not expr:
 744            msg = self._formatMessage(msg, "%s is not true" % safe_repr(expr))
 745            raise self.failureException(msg)
 746
 747    def _formatMessage(self, msg, standardMsg):
 748        """Honour the longMessage attribute when generating failure messages.
 749        If longMessage is False this means:
 750        * Use only an explicit message if it is provided
 751        * Otherwise use the standard message for the assert
 752
 753        If longMessage is True:
 754        * Use the standard message
 755        * If an explicit message is provided, plus ' : ' and the explicit message
 756        """
 757        if not self.longMessage:
 758            return msg or standardMsg
 759        if msg is None:
 760            return standardMsg
 761        try:
 762            # don't switch to '{}' formatting in Python 2.X
 763            # it changes the way unicode input is handled
 764            return '%s : %s' % (standardMsg, msg)
 765        except UnicodeDecodeError:
 766            return  '%s : %s' % (safe_repr(standardMsg), safe_repr(msg))
 767
 768    def assertRaises(self, expected_exception, *args, **kwargs):
 769        """Fail unless an exception of class expected_exception is raised
 770           by the callable when invoked with specified positional and
 771           keyword arguments. If a different type of exception is
 772           raised, it will not be caught, and the test case will be
 773           deemed to have suffered an error, exactly as for an
 774           unexpected exception.
 775
 776           If called with the callable and arguments omitted, will return a
 777           context object used like this::
 778
 779                with self.assertRaises(SomeException):
 780                    do_something()
 781
 782           An optional keyword argument 'msg' can be provided when assertRaises
 783           is used as a context object.
 784
 785           The context manager keeps a reference to the exception as
 786           the 'exception' attribute. This allows you to inspect the
 787           exception after the assertion::
 788
 789               with self.assertRaises(SomeException) as cm:
 790                   do_something()
 791               the_exception = cm.exception
 792               self.assertEqual(the_exception.error_code, 3)
 793        """
 794        context = _AssertRaisesContext(expected_exception, self)
 795        try:
 796            return context.handle('assertRaises', args, kwargs)
 797        finally:
 798            # bpo-23890: manually break a reference cycle
 799            context = None
 800
 801    def assertWarns(self, expected_warning, *args, **kwargs):
 802        """Fail unless a warning of class warnClass is triggered
 803           by the callable when invoked with specified positional and
 804           keyword arguments.  If a different type of warning is
 805           triggered, it will not be handled: depending on the other
 806           warning filtering rules in effect, it might be silenced, printed
 807           out, or raised as an exception.
 808
 809           If called with the callable and arguments omitted, will return a
 810           context object used like this::
 811
 812                with self.assertWarns(SomeWarning):
 813                    do_something()
 814
 815           An optional keyword argument 'msg' can be provided when assertWarns
 816           is used as a context object.
 817
 818           The context manager keeps a reference to the first matching
 819           warning as the 'warning' attribute; similarly, the 'filename'
 820           and 'lineno' attributes give you information about the line
 821           of Python code from which the warning was triggered.
 822           This allows you to inspect the warning after the assertion::
 823
 824               with self.assertWarns(SomeWarning) as cm:
 825                   do_something()
 826               the_warning = cm.warning
 827               self.assertEqual(the_warning.some_attribute, 147)
 828        """
 829        context = _AssertWarnsContext(expected_warning, self)
 830        return context.handle('assertWarns', args, kwargs)
 831
 832    def _assertNotWarns(self, expected_warning, *args, **kwargs):
 833        """The opposite of assertWarns. Private due to low demand."""
 834        context = _AssertNotWarnsContext(expected_warning, self)
 835        return context.handle('_assertNotWarns', args, kwargs)
 836
 837    def assertLogs(self, logger=None, level=None):
 838        """Fail unless a log message of level *level* or higher is emitted
 839        on *logger_name* or its children.  If omitted, *level* defaults to
 840        INFO and *logger* defaults to the root logger.
 841
 842        This method must be used as a context manager, and will yield
 843        a recording object with two attributes: `output` and `records`.
 844        At the end of the context manager, the `output` attribute will
 845        be a list of the matching formatted log messages and the
 846        `records` attribute will be a list of the corresponding LogRecord
 847        objects.
 848
 849        Example::
 850
 851            with self.assertLogs('foo', level='INFO') as cm:
 852                logging.getLogger('foo').info('first message')
 853                logging.getLogger('foo.bar').error('second message')
 854            self.assertEqual(cm.output, ['INFO:foo:first message',
 855                                         'ERROR:foo.bar:second message'])
 856        """
 857        # Lazy import to avoid importing logging if it is not needed.
 858        from ._log import _AssertLogsContext
 859        return _AssertLogsContext(self, logger, level, no_logs=False)
 860
 861    def assertNoLogs(self, logger=None, level=None):
 862        """ Fail unless no log messages of level *level* or higher are emitted
 863        on *logger_name* or its children.
 864
 865        This method must be used as a context manager.
 866        """
 867        from ._log import _AssertLogsContext
 868        return _AssertLogsContext(self, logger, level, no_logs=True)
 869
 870    def _getAssertEqualityFunc(self, first, second):
 871        """Get a detailed comparison function for the types of the two args.
 872
 873        Returns: A callable accepting (first, second, msg=None) that will
 874        raise a failure exception if first != second with a useful human
 875        readable error message for those types.
 876        """
 877        #
 878        # NOTE(gregory.p.smith): I considered isinstance(first, type(second))
 879        # and vice versa.  I opted for the conservative approach in case
 880        # subclasses are not intended to be compared in detail to their super
 881        # class instances using a type equality func.  This means testing
 882        # subtypes won't automagically use the detailed comparison.  Callers
 883        # should use their type specific assertSpamEqual method to compare
 884        # subclasses if the detailed comparison is desired and appropriate.
 885        # See the discussion in http://bugs.python.org/issue2578.
 886        #
 887        if type(first) is type(second):
 888            asserter = self._type_equality_funcs.get(type(first))
 889            if asserter is not None:
 890                if isinstance(asserter, str):
 891                    asserter = getattr(self, asserter)
 892                return asserter
 893
 894        return self._baseAssertEqual
 895
 896    def _baseAssertEqual(self, first, second, msg=None):
 897        """The default assertEqual implementation, not type specific."""
 898        if not first == second:
 899            standardMsg = '%s != %s' % _common_shorten_repr(first, second)
 900            msg = self._formatMessage(msg, standardMsg)
 901            raise self.failureException(msg)
 902
 903    def assertEqual(self, first, second, msg=None):
 904        """Fail if the two objects are unequal as determined by the '=='
 905           operator.
 906        """
 907        assertion_func = self._getAssertEqualityFunc(first, second)
 908        assertion_func(first, second, msg=msg)
 909
 910    def assertNotEqual(self, first, second, msg=None):
 911        """Fail if the two objects are equal as determined by the '!='
 912           operator.
 913        """
 914        if not first != second:
 915            msg = self._formatMessage(msg, '%s == %s' % (safe_repr(first),
 916                                                          safe_repr(second)))
 917            raise self.failureException(msg)
 918
 919    def assertAlmostEqual(self, first, second, places=None, msg=None,
 920                          delta=None):
 921        """Fail if the two objects are unequal as determined by their
 922           difference rounded to the given number of decimal places
 923           (default 7) and comparing to zero, or by comparing that the
 924           difference between the two objects is more than the given
 925           delta.
 926
 927           Note that decimal places (from zero) are usually not the same
 928           as significant digits (measured from the most significant digit).
 929
 930           If the two objects compare equal then they will automatically
 931           compare almost equal.
 932        """
 933        if first == second:
 934            # shortcut
 935            return
 936        if delta is not None and places is not None:
 937            raise TypeError("specify delta or places not both")
 938
 939        diff = abs(first - second)
 940        if delta is not None:
 941            if diff <= delta:
 942                return
 943
 944            standardMsg = '%s != %s within %s delta (%s difference)' % (
 945                safe_repr(first),
 946                safe_repr(second),
 947                safe_repr(delta),
 948                safe_repr(diff))
 949        else:
 950            if places is None:
 951                places = 7
 952
 953            if round(diff, places) == 0:
 954                return
 955
 956            standardMsg = '%s != %s within %r places (%s difference)' % (
 957                safe_repr(first),
 958                safe_repr(second),
 959                places,
 960                safe_repr(diff))
 961        msg = self._formatMessage(msg, standardMsg)
 962        raise self.failureException(msg)
 963
 964    def assertNotAlmostEqual(self, first, second, places=None, msg=None,
 965                             delta=None):
 966        """Fail if the two objects are equal as determined by their
 967           difference rounded to the given number of decimal places
 968           (default 7) and comparing to zero, or by comparing that the
 969           difference between the two objects is less than the given delta.
 970
 971           Note that decimal places (from zero) are usually not the same
 972           as significant digits (measured from the most significant digit).
 973
 974           Objects that are equal automatically fail.
 975        """
 976        if delta is not None and places is not None:
 977            raise TypeError("specify delta or places not both")
 978        diff = abs(first - second)
 979        if delta is not None:
 980            if not (first == second) and diff > delta:
 981                return
 982            standardMsg = '%s == %s within %s delta (%s difference)' % (
 983                safe_repr(first),
 984                safe_repr(second),
 985                safe_repr(delta),
 986                safe_repr(diff))
 987        else:
 988            if places is None:
 989                places = 7
 990            if not (first == second) and round(diff, places) != 0:
 991                return
 992            standardMsg = '%s == %s within %r places' % (safe_repr(first),
 993                                                         safe_repr(second),
 994                                                         places)
 995
 996        msg = self._formatMessage(msg, standardMsg)
 997        raise self.failureException(msg)
 998
 999    def assertSequenceEqual(self, seq1, seq2, msg=None, seq_type=None):
1000        """An equality assertion for ordered sequences (like lists and tuples).
1001
1002        For the purposes of this function, a valid ordered sequence type is one
1003        which can be indexed, has a length, and has an equality operator.
1004
1005        Args:
1006            seq1: The first sequence to compare.
1007            seq2: The second sequence to compare.
1008            seq_type: The expected datatype of the sequences, or None if no
1009                    datatype should be enforced.
1010            msg: Optional message to use on failure instead of a list of
1011                    differences.
1012        """
1013        if seq_type is not None:
1014            seq_type_name = seq_type.__name__
1015            if not isinstance(seq1, seq_type):
1016                raise self.failureException('First sequence is not a %s: %s'
1017                                        % (seq_type_name, safe_repr(seq1)))
1018            if not isinstance(seq2, seq_type):
1019                raise self.failureException('Second sequence is not a %s: %s'
1020                                        % (seq_type_name, safe_repr(seq2)))
1021        else:
1022            seq_type_name = "sequence"
1023
1024        differing = None
1025        try:
1026            len1 = len(seq1)
1027        except (TypeError, NotImplementedError):
1028            differing = 'First %s has no length.    Non-sequence?' % (
1029                    seq_type_name)
1030
1031        if differing is None:
1032            try:
1033                len2 = len(seq2)
1034            except (TypeError, NotImplementedError):
1035                differing = 'Second %s has no length.    Non-sequence?' % (
1036                        seq_type_name)
1037
1038        if differing is None:
1039            if seq1 == seq2:
1040                return
1041
1042            differing = '%ss differ: %s != %s\n' % (
1043                    (seq_type_name.capitalize(),) +
1044                    _common_shorten_repr(seq1, seq2))
1045
1046            for i in range(min(len1, len2)):
1047                try:
1048                    item1 = seq1[i]
1049                except (TypeError, IndexError, NotImplementedError):
1050                    differing += ('\nUnable to index element %d of first %s\n' %
1051                                 (i, seq_type_name))
1052                    break
1053
1054                try:
1055                    item2 = seq2[i]
1056                except (TypeError, IndexError, NotImplementedError):
1057                    differing += ('\nUnable to index element %d of second %s\n' %
1058                                 (i, seq_type_name))
1059                    break
1060
1061                if item1 != item2:
1062                    differing += ('\nFirst differing element %d:\n%s\n%s\n' %
1063                                 ((i,) + _common_shorten_repr(item1, item2)))
1064                    break
1065            else:
1066                if (len1 == len2 and seq_type is None and
1067                    type(seq1) != type(seq2)):
1068                    # The sequences are the same, but have differing types.
1069                    return
1070
1071            if len1 > len2:
1072                differing += ('\nFirst %s contains %d additional '
1073                             'elements.\n' % (seq_type_name, len1 - len2))
1074                try:
1075                    differing += ('First extra element %d:\n%s\n' %
1076                                  (len2, safe_repr(seq1[len2])))
1077                except (TypeError, IndexError, NotImplementedError):
1078                    differing += ('Unable to index element %d '
1079                                  'of first %s\n' % (len2, seq_type_name))
1080            elif len1 < len2:
1081                differing += ('\nSecond %s contains %d additional '
1082                             'elements.\n' % (seq_type_name, len2 - len1))
1083                try:
1084                    differing += ('First extra element %d:\n%s\n' %
1085                                  (len1, safe_repr(seq2[len1])))
1086                except (TypeError, IndexError, NotImplementedError):
1087                    differing += ('Unable to index element %d '
1088                                  'of second %s\n' % (len1, seq_type_name))
1089        standardMsg = differing
1090        diffMsg = '\n' + '\n'.join(
1091            difflib.ndiff(pprint.pformat(seq1).splitlines(),
1092                          pprint.pformat(seq2).splitlines()))
1093
1094        standardMsg = self._truncateMessage(standardMsg, diffMsg)
1095        msg = self._formatMessage(msg, standardMsg)
1096        self.fail(msg)
1097
1098    def _truncateMessage(self, message, diff):
1099        max_diff = self.maxDiff
1100        if max_diff is None or len(diff) <= max_diff:
1101            return message + diff
1102        return message + (DIFF_OMITTED % len(diff))
1103
1104    def assertListEqual(self, list1, list2, msg=None):
1105        """A list-specific equality assertion.
1106
1107        Args:
1108            list1: The first list to compare.
1109            list2: The second list to compare.
1110            msg: Optional message to use on failure instead of a list of
1111                    differences.
1112
1113        """
1114        self.assertSequenceEqual(list1, list2, msg, seq_type=list)
1115
1116    def assertTupleEqual(self, tuple1, tuple2, msg=None):
1117        """A tuple-specific equality assertion.
1118
1119        Args:
1120            tuple1: The first tuple to compare.
1121            tuple2: The second tuple to compare.
1122            msg: Optional message to use on failure instead of a list of
1123                    differences.
1124        """
1125        self.assertSequenceEqual(tuple1, tuple2, msg, seq_type=tuple)
1126
1127    def assertSetEqual(self, set1, set2, msg=None):
1128        """A set-specific equality assertion.
1129
1130        Args:
1131            set1: The first set to compare.
1132            set2: The second set to compare.
1133            msg: Optional message to use on failure instead of a list of
1134                    differences.
1135
1136        assertSetEqual uses ducktyping to support different types of sets, and
1137        is optimized for sets specifically (parameters must support a
1138        difference method).
1139        """
1140        try:
1141            difference1 = set1.difference(set2)
1142        except TypeError as e:
1143            self.fail('invalid type when attempting set difference: %s' % e)
1144        except AttributeError as e:
1145            self.fail('first argument does not support set difference: %s' % e)
1146
1147        try:
1148            difference2 = set2.difference(set1)
1149        except TypeError as e:
1150            self.fail('invalid type when attempting set difference: %s' % e)
1151        except AttributeError as e:
1152            self.fail('second argument does not support set difference: %s' % e)
1153
1154        if not (difference1 or difference2):
1155            return
1156
1157        lines = []
1158        if difference1:
1159            lines.append('Items in the first set but not the second:')
1160            for item in difference1:
1161                lines.append(repr(item))
1162        if difference2:
1163            lines.append('Items in the second set but not the first:')
1164            for item in difference2:
1165                lines.append(repr(item))
1166
1167        standardMsg = '\n'.join(lines)
1168        self.fail(self._formatMessage(msg, standardMsg))
1169
1170    def assertIn(self, member, container, msg=None):
1171        """Just like self.assertTrue(a in b), but with a nicer default message."""
1172        if member not in container:
1173            standardMsg = '%s not found in %s' % (safe_repr(member),
1174                                                  safe_repr(container))
1175            self.fail(self._formatMessage(msg, standardMsg))
1176
1177    def assertNotIn(self, member, container, msg=None):
1178        """Just like self.assertTrue(a not in b), but with a nicer default message."""
1179        if member in container:
1180            standardMsg = '%s unexpectedly found in %s' % (safe_repr(member),
1181                                                        safe_repr(container))
1182            self.fail(self._formatMessage(msg, standardMsg))
1183
1184    def assertIs(self, expr1, expr2, msg=None):
1185        """Just like self.assertTrue(a is b), but with a nicer default message."""
1186        if expr1 is not expr2:
1187            standardMsg = '%s is not %s' % (safe_repr(expr1),
1188                                             safe_repr(expr2))
1189            self.fail(self._formatMessage(msg, standardMsg))
1190
1191    def assertIsNot(self, expr1, expr2, msg=None):
1192        """Just like self.assertTrue(a is not b), but with a nicer default message."""
1193        if expr1 is expr2:
1194            standardMsg = 'unexpectedly identical: %s' % (safe_repr(expr1),)
1195            self.fail(self._formatMessage(msg, standardMsg))
1196
1197    def assertDictEqual(self, d1, d2, msg=None):
1198        self.assertIsInstance(d1, dict, 'First argument is not a dictionary')
1199        self.assertIsInstance(d2, dict, 'Second argument is not a dictionary')
1200
1201        if d1 != d2:
1202            standardMsg = '%s != %s' % _common_shorten_repr(d1, d2)
1203            diff = ('\n' + '\n'.join(difflib.ndiff(
1204                           pprint.pformat(d1).splitlines(),
1205                           pprint.pformat(d2).splitlines())))
1206            standardMsg = self._truncateMessage(standardMsg, diff)
1207            self.fail(self._formatMessage(msg, standardMsg))
1208
1209    def assertCountEqual(self, first, second, msg=None):
1210        """Asserts that two iterables have the same elements, the same number of
1211        times, without regard to order.
1212
1213            self.assertEqual(Counter(list(first)),
1214                             Counter(list(second)))
1215
1216         Example:
1217            - [0, 1, 1] and [1, 0, 1] compare equal.
1218            - [0, 0, 1] and [0, 1] compare unequal.
1219
1220        """
1221        first_seq, second_seq = list(first), list(second)
1222        try:
1223            first = collections.Counter(first_seq)
1224            second = collections.Counter(second_seq)
1225        except TypeError:
1226            # Handle case with unhashable elements
1227            differences = _count_diff_all_purpose(first_seq, second_seq)
1228        else:
1229            if first == second:
1230                return
1231            differences = _count_diff_hashable(first_seq, second_seq)
1232
1233        if differences:
1234            standardMsg = 'Element counts were not equal:\n'
1235            lines = ['First has %d, Second has %d:  %r' % diff for diff in differences]
1236            diffMsg = '\n'.join(lines)
1237            standardMsg = self._truncateMessage(standardMsg, diffMsg)
1238            msg = self._formatMessage(msg, standardMsg)
1239            self.fail(msg)
1240
1241    def assertMultiLineEqual(self, first, second, msg=None):
1242        """Assert that two multi-line strings are equal."""
1243        self.assertIsInstance(first, str, "First argument is not a string")
1244        self.assertIsInstance(second, str, "Second argument is not a string")
1245
1246        if first != second:
1247            # Don't use difflib if the strings are too long
1248            if (len(first) > self._diffThreshold or
1249                len(second) > self._diffThreshold):
1250                self._baseAssertEqual(first, second, msg)
1251
1252            # Append \n to both strings if either is missing the \n.
1253            # This allows the final ndiff to show the \n difference. The
1254            # exception here is if the string is empty, in which case no
1255            # \n should be added
1256            first_presplit = first
1257            second_presplit = second
1258            if first and second:
1259                if first[-1] != '\n' or second[-1] != '\n':
1260                    first_presplit += '\n'
1261                    second_presplit += '\n'
1262            elif second and second[-1] != '\n':
1263                second_presplit += '\n'
1264            elif first and first[-1] != '\n':
1265                first_presplit += '\n'
1266
1267            firstlines = first_presplit.splitlines(keepends=True)
1268            secondlines = second_presplit.splitlines(keepends=True)
1269
1270            # Generate the message and diff, then raise the exception
1271            standardMsg = '%s != %s' % _common_shorten_repr(first, second)
1272            diff = '\n' + ''.join(difflib.ndiff(firstlines, secondlines))
1273            standardMsg = self._truncateMessage(standardMsg, diff)
1274            self.fail(self._formatMessage(msg, standardMsg))
1275
1276    def assertLess(self, a, b, msg=None):
1277        """Just like self.assertTrue(a < b), but with a nicer default message."""
1278        if not a < b:
1279            standardMsg = '%s not less than %s' % (safe_repr(a), safe_repr(b))
1280            self.fail(self._formatMessage(msg, standardMsg))
1281
1282    def assertLessEqual(self, a, b, msg=None):
1283        """Just like self.assertTrue(a <= b), but with a nicer default message."""
1284        if not a <= b:
1285            standardMsg = '%s not less than or equal to %s' % (safe_repr(a), safe_repr(b))
1286            self.fail(self._formatMessage(msg, standardMsg))
1287
1288    def assertGreater(self, a, b, msg=None):
1289        """Just like self.assertTrue(a > b), but with a nicer default message."""
1290        if not a > b:
1291            standardMsg = '%s not greater than %s' % (safe_repr(a), safe_repr(b))
1292            self.fail(self._formatMessage(msg, standardMsg))
1293
1294    def assertGreaterEqual(self, a, b, msg=None):
1295        """Just like self.assertTrue(a >= b), but with a nicer default message."""
1296        if not a >= b:
1297            standardMsg = '%s not greater than or equal to %s' % (safe_repr(a), safe_repr(b))
1298            self.fail(self._formatMessage(msg, standardMsg))
1299
1300    def assertIsNone(self, obj, msg=None):
1301        """Same as self.assertTrue(obj is None), with a nicer default message."""
1302        if obj is not None:
1303            standardMsg = '%s is not None' % (safe_repr(obj),)
1304            self.fail(self._formatMessage(msg, standardMsg))
1305
1306    def assertIsNotNone(self, obj, msg=None):
1307        """Included for symmetry with assertIsNone."""
1308        if obj is None:
1309            standardMsg = 'unexpectedly None'
1310            self.fail(self._formatMessage(msg, standardMsg))
1311
1312    def assertIsInstance(self, obj, cls, msg=None):
1313        """Same as self.assertTrue(isinstance(obj, cls)), with a nicer
1314        default message."""
1315        if not isinstance(obj, cls):
1316            standardMsg = '%s is not an instance of %r' % (safe_repr(obj), cls)
1317            self.fail(self._formatMessage(msg, standardMsg))
1318
1319    def assertNotIsInstance(self, obj, cls, msg=None):
1320        """Included for symmetry with assertIsInstance."""
1321        if isinstance(obj, cls):
1322            standardMsg = '%s is an instance of %r' % (safe_repr(obj), cls)
1323            self.fail(self._formatMessage(msg, standardMsg))
1324
1325    def assertRaisesRegex(self, expected_exception, expected_regex,
1326                          *args, **kwargs):
1327        """Asserts that the message in a raised exception matches a regex.
1328
1329        Args:
1330            expected_exception: Exception class expected to be raised.
1331            expected_regex: Regex (re.Pattern object or string) expected
1332                    to be found in error message.
1333            args: Function to be called and extra positional args.
1334            kwargs: Extra kwargs.
1335            msg: Optional message used in case of failure. Can only be used
1336                    when assertRaisesRegex is used as a context manager.
1337        """
1338        context = _AssertRaisesContext(expected_exception, self, expected_regex)
1339        return context.handle('assertRaisesRegex', args, kwargs)
1340
1341    def assertWarnsRegex(self, expected_warning, expected_regex,
1342                         *args, **kwargs):
1343        """Asserts that the message in a triggered warning matches a regexp.
1344        Basic functioning is similar to assertWarns() with the addition
1345        that only warnings whose messages also match the regular expression
1346        are considered successful matches.
1347
1348        Args:
1349            expected_warning: Warning class expected to be triggered.
1350            expected_regex: Regex (re.Pattern object or string) expected
1351                    to be found in error message.
1352            args: Function to be called and extra positional args.
1353            kwargs: Extra kwargs.
1354            msg: Optional message used in case of failure. Can only be used
1355                    when assertWarnsRegex is used as a context manager.
1356        """
1357        context = _AssertWarnsContext(expected_warning, self, expected_regex)
1358        return context.handle('assertWarnsRegex', args, kwargs)
1359
1360    def assertRegex(self, text, expected_regex, msg=None):
1361        """Fail the test unless the text matches the regular expression."""
1362        if isinstance(expected_regex, (str, bytes)):
1363            assert expected_regex, "expected_regex must not be empty."
1364            expected_regex = re.compile(expected_regex)
1365        if not expected_regex.search(text):
1366            standardMsg = "Regex didn't match: %r not found in %r" % (
1367                expected_regex.pattern, text)
1368            # _formatMessage ensures the longMessage option is respected
1369            msg = self._formatMessage(msg, standardMsg)
1370            raise self.failureException(msg)
1371
1372    def assertNotRegex(self, text, unexpected_regex, msg=None):
1373        """Fail the test if the text matches the regular expression."""
1374        if isinstance(unexpected_regex, (str, bytes)):
1375            unexpected_regex = re.compile(unexpected_regex)
1376        match = unexpected_regex.search(text)
1377        if match:
1378            standardMsg = 'Regex matched: %r matches %r in %r' % (
1379                text[match.start() : match.end()],
1380                unexpected_regex.pattern,
1381                text)
1382            # _formatMessage ensures the longMessage option is respected
1383            msg = self._formatMessage(msg, standardMsg)
1384            raise self.failureException(msg)