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)))

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