LEFT | RIGHT |
1 | 1 |
2 :mod:`unittest` --- Unit testing framework | 2 :mod:`unittest` --- Unit testing framework |
3 ========================================== | 3 ========================================== |
4 | 4 |
5 .. module:: unittest | 5 .. module:: unittest |
6 :synopsis: Unit testing framework for Python. | 6 :synopsis: Unit testing framework for Python. |
7 .. moduleauthor:: Steve Purcell <stephen_purcell@yahoo.com> | 7 .. moduleauthor:: Steve Purcell <stephen_purcell@yahoo.com> |
8 .. sectionauthor:: Steve Purcell <stephen_purcell@yahoo.com> | 8 .. sectionauthor:: Steve Purcell <stephen_purcell@yahoo.com> |
9 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> | 9 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
10 .. sectionauthor:: Raymond Hettinger <python@rcn.com> | 10 .. sectionauthor:: Raymond Hettinger <python@rcn.com> |
(...skipping 191 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
202 The simplest :class:`TestCase` subclass will simply override the | 202 The simplest :class:`TestCase` subclass will simply override the |
203 :meth:`~TestCase.runTest` method in order to perform specific testing code:: | 203 :meth:`~TestCase.runTest` method in order to perform specific testing code:: |
204 | 204 |
205 import unittest | 205 import unittest |
206 | 206 |
207 class DefaultWidgetSizeTestCase(unittest.TestCase): | 207 class DefaultWidgetSizeTestCase(unittest.TestCase): |
208 def runTest(self): | 208 def runTest(self): |
209 widget = Widget('The widget') | 209 widget = Widget('The widget') |
210 self.assertEqual(widget.size(), (50, 50), 'incorrect default size') | 210 self.assertEqual(widget.size(), (50, 50), 'incorrect default size') |
211 | 211 |
212 Note that in order to test something, we use the one of the :meth:`assert\*` or | 212 Note that in order to test something, we use the one of the :meth:`assert\*` |
213 :meth:`fail\*` methods provided by the :class:`TestCase` base class. If the | 213 methods provided by the :class:`TestCase` base class. If the |
214 test fails, an exception will be raised, and :mod:`unittest` will identify the | 214 test fails, an exception will be raised, and :mod:`unittest` will identify the |
215 test case as a :dfn:`failure`. Any other exceptions will be treated as | 215 test case as a :dfn:`failure`. Any other exceptions will be treated as |
216 :dfn:`errors`. This helps you identify where the problem is: :dfn:`failures` are | 216 :dfn:`errors`. This helps you identify where the problem is: :dfn:`failures` are |
217 caused by incorrect results - a 5 where you expected a 6. :dfn:`Errors` are | 217 caused by incorrect results - a 5 where you expected a 6. :dfn:`Errors` are |
218 caused by incorrect code - e.g., a :exc:`TypeError` caused by an incorrect | 218 caused by incorrect code - e.g., a :exc:`TypeError` caused by an incorrect |
219 function call. | 219 function call. |
220 | 220 |
221 The way to run a test case will be described later. For now, note that to | 221 The way to run a test case will be described later. For now, note that to |
222 construct an instance of such a test case, we call its constructor without | 222 construct an instance of such a test case, we call its constructor without |
223 arguments:: | 223 arguments:: |
224 | 224 |
225 testCase = DefaultWidgetSizeTestCase() | 225 testCase = DefaultWidgetSizeTestCase() |
226 | 226 |
227 Now, such test cases can be numerous, and their set-up can be repetitive. In | 227 Now, such test cases can be numerous, and their set-up can be repetitive. In |
228 the above case, constructing a :class:`Widget` in each of 100 Widget test case | 228 the above case, constructing a :class:`Widget` in each of 100 Widget test case |
229 subclasses would mean unsightly duplication. | 229 subclasses would mean unsightly duplication. |
230 | 230 |
231 Luckily, we can factor out such set-up code by implementing a method called | 231 Luckily, we can factor out such set-up code by implementing a method called |
232 :meth:`~TestCase.setUp`, which the testing framework will automatically call for | 232 :meth:`~TestCase.setUp`, which the testing framework will automatically call for |
233 us when we run the test:: | 233 us when we run the test:: |
234 | 234 |
235 import unittest | 235 import unittest |
236 | 236 |
237 class SimpleWidgetTestCase(unittest.TestCase): | 237 class SimpleWidgetTestCase(unittest.TestCase): |
238 def setUp(self): | 238 def setUp(self): |
239 self.widget = Widget('The widget') | 239 self.widget = Widget('The widget') |
240 | 240 |
241 class DefaultWidgetSizeTestCase(SimpleWidgetTestCase): | 241 class DefaultWidgetSizeTestCase(SimpleWidgetTestCase): |
242 def runTest(self): | 242 def runTest(self): |
243 self.failUnless(self.widget.size() == (50,50), | 243 self.assertTrue(self.widget.size() == (50,50), |
244 'incorrect default size') | 244 'incorrect default size') |
245 | 245 |
246 class WidgetResizeTestCase(SimpleWidgetTestCase): | 246 class WidgetResizeTestCase(SimpleWidgetTestCase): |
247 def runTest(self): | 247 def runTest(self): |
248 self.widget.resize(100,150) | 248 self.widget.resize(100,150) |
249 self.failUnless(self.widget.size() == (100,150), | 249 self.assertTrue(self.widget.size() == (100,150), |
250 'wrong size after resize') | 250 'wrong size after resize') |
251 | 251 |
252 If the :meth:`~TestCase.setUp` method raises an exception while the test is | 252 If the :meth:`~TestCase.setUp` method raises an exception while the test is |
253 running, the framework will consider the test to have suffered an error, and the | 253 running, the framework will consider the test to have suffered an error, and the |
254 :meth:`~TestCase.runTest` method will not be executed. | 254 :meth:`~TestCase.runTest` method will not be executed. |
255 | 255 |
256 Similarly, we can provide a :meth:`~TestCase.tearDown` method that tidies up | 256 Similarly, we can provide a :meth:`~TestCase.tearDown` method that tidies up |
257 after the :meth:`~TestCase.runTest` method has been run:: | 257 after the :meth:`~TestCase.runTest` method has been run:: |
258 | 258 |
259 import unittest | 259 import unittest |
(...skipping 21 matching lines...) Expand all Loading... |
281 | 281 |
282 class WidgetTestCase(unittest.TestCase): | 282 class WidgetTestCase(unittest.TestCase): |
283 def setUp(self): | 283 def setUp(self): |
284 self.widget = Widget('The widget') | 284 self.widget = Widget('The widget') |
285 | 285 |
286 def tearDown(self): | 286 def tearDown(self): |
287 self.widget.dispose() | 287 self.widget.dispose() |
288 self.widget = None | 288 self.widget = None |
289 | 289 |
290 def testDefaultSize(self): | 290 def testDefaultSize(self): |
291 self.failUnless(self.widget.size() == (50,50), | 291 self.assertTrue(self.widget.size() == (50,50), |
292 'incorrect default size') | 292 'incorrect default size') |
293 | 293 |
294 def testResize(self): | 294 def testResize(self): |
295 self.widget.resize(100,150) | 295 self.widget.resize(100,150) |
296 self.failUnless(self.widget.size() == (100,150), | 296 self.assertTrue(self.widget.size() == (100,150), |
297 'wrong size after resize') | 297 'wrong size after resize') |
298 | 298 |
299 Here we have not provided a :meth:`~TestCase.runTest` method, but have instead | 299 Here we have not provided a :meth:`~TestCase.runTest` method, but have instead |
300 provided two different test methods. Class instances will now each run one of | 300 provided two different test methods. Class instances will now each run one of |
301 the :meth:`test\*` methods, with ``self.widget`` created and destroyed | 301 the :meth:`test\*` methods, with ``self.widget`` created and destroyed |
302 separately for each instance. When creating an instance we must specify the | 302 separately for each instance. When creating an instance we must specify the |
303 test method it is to run. We do this by passing the method name in the | 303 test method it is to run. We do this by passing the method name in the |
304 constructor:: | 304 constructor:: |
305 | 305 |
306 defaultSizeTestCase = WidgetTestCase('testDefaultSize') | 306 defaultSizeTestCase = WidgetTestCase('testDefaultSize') |
(...skipping 292 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
599 .. method:: debug() | 599 .. method:: debug() |
600 | 600 |
601 Run the test without collecting the result. This allows exceptions raised | 601 Run the test without collecting the result. This allows exceptions raised |
602 by the test to be propagated to the caller, and can be used to support | 602 by the test to be propagated to the caller, and can be used to support |
603 running tests under a debugger. | 603 running tests under a debugger. |
604 | 604 |
605 The test code can use any of the following methods to check for and report | 605 The test code can use any of the following methods to check for and report |
606 failures. | 606 failures. |
607 | 607 |
608 | 608 |
609 .. method:: assert_(expr[, msg]) | 609 .. method:: assertTrue(expr[, msg]) |
| 610 assert_(expr[, msg]) |
610 failUnless(expr[, msg]) | 611 failUnless(expr[, msg]) |
611 assertTrue(expr[, msg]) | |
612 | 612 |
613 Signal a test failure if *expr* is false; the explanation for the error | 613 Signal a test failure if *expr* is false; the explanation for the error |
614 will be *msg* if given, otherwise it will be :const:`None`. | 614 will be *msg* if given, otherwise it will be :const:`None`. |
615 | 615 |
616 | 616 |
617 .. method:: assertEqual(first, second[, msg]) | 617 .. method:: assertEqual(first, second[, msg]) |
618 assertEquals(first, second[, msg]) | |
619 failUnlessEqual(first, second[, msg]) | 618 failUnlessEqual(first, second[, msg]) |
620 | 619 |
621 Test that *first* and *second* are equal. If the values do not compare | 620 Test that *first* and *second* are equal. If the values do not compare |
622 equal, the test will fail with the explanation given by *msg*, or | 621 equal, the test will fail with the explanation given by *msg*, or |
623 :const:`None`. Note that using :meth:`failUnlessEqual` improves upon | 622 :const:`None`. Note that using :meth:`assertEqual` improves upon |
624 doing the comparison as the first parameter to :meth:`failUnless`: the | 623 doing the comparison as the first parameter to :meth:`assertTrue`: the |
625 default value for *msg* include representations of both *first* and | 624 default value for *msg* include representations of both *first* and |
626 *second*. | 625 *second*. |
627 | 626 |
628 In addition, if *first* and *second* are the exact same type and one of | 627 In addition, if *first* and *second* are the exact same type and one of |
629 list, tuple, dict, set, or frozenset or any type that a subclass | 628 list, tuple, dict, set, or frozenset or any type that a subclass |
630 registers :meth:`addTypeEqualityFunc` the type specific equality function | 629 registers :meth:`addTypeEqualityFunc` the type specific equality function |
631 will be called in order to generate a more useful default error message. | 630 will be called in order to generate a more useful default error message. |
632 | 631 |
633 .. versionchanged:: 2.7 | 632 .. versionchanged:: 2.7 |
634 Added the automatic calling of type specific equality function. | 633 Added the automatic calling of type specific equality function. |
635 | 634 |
636 | 635 |
637 .. method:: assertNotEqual(first, second[, msg]) | 636 .. method:: assertNotEqual(first, second[, msg]) |
638 failIfEqual(first, second[, msg]) | 637 failIfEqual(first, second[, msg]) |
639 | 638 |
640 Test that *first* and *second* are not equal. If the values do compare | 639 Test that *first* and *second* are not equal. If the values do compare |
641 equal, the test will fail with the explanation given by *msg*, or | 640 equal, the test will fail with the explanation given by *msg*, or |
642 :const:`None`. Note that using :meth:`failIfEqual` improves upon doing | 641 :const:`None`. Note that using :meth:`assertNotEqual` improves upon doing |
643 the comparison as the first parameter to :meth:`failUnless` is that the | 642 the comparison as the first parameter to :meth:`assertTrue` is that the |
644 default value for *msg* can be computed to include representations of both | 643 default value for *msg* can be computed to include representations of both |
645 *first* and *second*. | 644 *first* and *second*. |
646 | 645 |
647 | 646 |
648 .. method:: assertAlmostEqual(first, second[, places[, msg]]) | 647 .. method:: assertAlmostEqual(first, second[, places[, msg]]) |
649 failUnlessAlmostEqual(first, second[, places[, msg]]) | 648 failUnlessAlmostEqual(first, second[, places[, msg]]) |
650 | 649 |
651 Test that *first* and *second* are approximately equal by computing the | 650 Test that *first* and *second* are approximately equal by computing the |
652 difference, rounding to the given number of decimal *places* (default 7), | 651 difference, rounding to the given number of decimal *places* (default 7), |
653 and comparing to zero. | 652 and comparing to zero. |
(...skipping 25 matching lines...) Expand all Loading... |
679 Test that *first* is respectively >, >=, < or <= than *second* depending | 678 Test that *first* is respectively >, >=, < or <= than *second* depending |
680 on the method name. If not, the test will fail with the nice explanation | 679 on the method name. If not, the test will fail with the nice explanation |
681 or with the explanation given by *msg*:: | 680 or with the explanation given by *msg*:: |
682 | 681 |
683 >>> self.assertGreaterEqual(3, 4) | 682 >>> self.assertGreaterEqual(3, 4) |
684 AssertionError: "3" unexpectedly not greater than or equal to "4" | 683 AssertionError: "3" unexpectedly not greater than or equal to "4" |
685 | 684 |
686 .. versionadded:: 2.7 | 685 .. versionadded:: 2.7 |
687 | 686 |
688 | 687 |
689 .. method:: assertMultiLineEquals(self, first, second, msg=None) | 688 .. method:: assertMultiLineEqual(self, first, second, msg=None) |
690 | 689 |
691 Test that the multiline string *first* is equal to the string *second*. | 690 Test that the multiline string *first* is equal to the string *second*. |
692 When not equal a diff of the two strings highlighting the differences | 691 When not equal a diff of the two strings highlighting the differences |
693 will be included in the error message. | 692 will be included in the error message. |
694 | 693 |
695 If specified *msg* will be used as the error message on failure. | 694 If specified *msg* will be used as the error message on failure. |
696 | 695 |
697 .. versionadded:: 2.7 | 696 .. versionadded:: 2.7 |
698 | 697 |
699 | 698 |
(...skipping 22 matching lines...) Expand all Loading... |
722 | 721 |
723 Test that sequence *expected* contains the same elements as *actual*. | 722 Test that sequence *expected* contains the same elements as *actual*. |
724 When they don't an error message listing the differences between the | 723 When they don't an error message listing the differences between the |
725 sequences will be generated. | 724 sequences will be generated. |
726 | 725 |
727 If specified *msg* will be used as the error message on failure. | 726 If specified *msg* will be used as the error message on failure. |
728 | 727 |
729 .. versionadded:: 2.7 | 728 .. versionadded:: 2.7 |
730 | 729 |
731 | 730 |
732 .. method:: assertSetEquals(set1, set2, msg=None) | 731 .. method:: assertSetEqual(set1, set2, msg=None) |
733 | 732 |
734 Tests that two sets are equal. If not, an error message is constructed | 733 Tests that two sets are equal. If not, an error message is constructed |
735 that lists the differences between the sets. | 734 that lists the differences between the sets. |
736 | 735 |
737 Fails if either of *set1* or *set2* does not have a :meth:`set.difference` | 736 Fails if either of *set1* or *set2* does not have a :meth:`set.difference` |
738 method. | 737 method. |
739 | 738 |
740 If specified *msg* will be used as the error message on failure. | 739 If specified *msg* will be used as the error message on failure. |
741 | 740 |
742 .. versionadded:: 2.7 | 741 .. versionadded:: 2.7 |
743 | 742 |
744 | 743 |
745 .. method:: assertDictEquals(expected, actual, msg=None) | 744 .. method:: assertDictEqual(expected, actual, msg=None) |
746 | 745 |
747 Test that two dictionaries are equal. If not, an error message is | 746 Test that two dictionaries are equal. If not, an error message is |
748 constructed that shows the differences in the dictionaries. | 747 constructed that shows the differences in the dictionaries. |
749 | 748 |
750 If specified *msg* will be used as the error message on failure. | 749 If specified *msg* will be used as the error message on failure. |
751 | 750 |
752 .. versionadded:: 2.7 | 751 .. versionadded:: 2.7 |
753 | 752 |
754 | 753 |
755 .. method:: assertDictContainsSubset(expected, actual, msg=None) | 754 .. method:: assertDictContainsSubset(expected, actual, msg=None) |
756 | 755 |
757 Tests whether the key value pairs in dictionary *actual* are a | 756 Tests whether the key value pairs in dictionary *actual* are a |
758 superset of those in *expected*. If not, an error message listing | 757 superset of those in *expected*. If not, an error message listing |
759 the missing keys and mismatched values is generated. | 758 the missing keys and mismatched values is generated. |
760 | 759 |
761 If specified *msg* will be used as the error message on failure. | 760 If specified *msg* will be used as the error message on failure. |
762 | 761 |
763 .. versionadded:: 2.7 | 762 .. versionadded:: 2.7 |
764 | 763 |
765 | 764 |
766 .. method:: assertListEquals(list1, list2, msg=None) | 765 .. method:: assertListEqual(list1, list2, msg=None) |
767 assertTupleEquals(tuple1, tuple2, msg=None) | 766 assertTupleEqual(tuple1, tuple2, msg=None) |
768 | 767 |
769 Tests that two lists or tuples are equal. If not an error message is | 768 Tests that two lists or tuples are equal. If not an error message is |
770 constructed that shows only the differences between the two. An error | 769 constructed that shows only the differences between the two. An error |
771 is also raised if either of the parameters are of the wrong type. | 770 is also raised if either of the parameters are of the wrong type. |
772 | 771 |
773 If specified *msg* will be used as the error message on failure. | 772 If specified *msg* will be used as the error message on failure. |
774 | 773 |
775 .. versionadded:: 2.7 | 774 .. versionadded:: 2.7 |
776 | 775 |
777 | 776 |
778 .. method:: assertSequenceEquals(seq1, seq2, msg=None, seq_type=None) | 777 .. method:: assertSequenceEqual(seq1, seq2, msg=None, seq_type=None) |
779 | 778 |
780 Tests that two sequences are equal. If a *seq_type* is supplied, both | 779 Tests that two sequences are equal. If a *seq_type* is supplied, both |
781 *seq1* and *seq2* must be instances of *seq_type* or a failure will | 780 *seq1* and *seq2* must be instances of *seq_type* or a failure will |
782 be raised. If the sequences are different an error message is | 781 be raised. If the sequences are different an error message is |
783 constructed that shows the difference between the two. | 782 constructed that shows the difference between the two. |
784 | 783 |
785 If specified *msg* will be used as the error message on failure. | 784 If specified *msg* will be used as the error message on failure. |
786 | 785 |
787 This method is used to implement :meth:`assertListEquals` and | 786 This method is used to implement :meth:`assertListEqual` and |
788 :meth:`assertTupleEquals`. | 787 :meth:`assertTupleEqual`. |
789 | 788 |
790 .. versionadded:: 2.7 | 789 .. versionadded:: 2.7 |
791 | 790 |
792 | 791 |
793 .. method:: assertRaises(exception[, callable, ...]) | 792 .. method:: assertRaises(exception[, callable, ...]) |
794 failUnlessRaises(exception[, callable, ...]) | 793 failUnlessRaises(exception[, callable, ...]) |
795 | 794 |
796 Test that an exception is raised when *callable* is called with any | 795 Test that an exception is raised when *callable* is called with any |
797 positional or keyword arguments that are also passed to | 796 positional or keyword arguments that are also passed to |
798 :meth:`assertRaises`. The test passes if *exception* is raised, is an | 797 :meth:`assertRaises`. The test passes if *exception* is raised, is an |
(...skipping 13 matching lines...) Expand all Loading... |
812 | 811 |
813 .. method:: assertRaisesRegexp(exception, regexp[, callable, ...]) | 812 .. method:: assertRaisesRegexp(exception, regexp[, callable, ...]) |
814 | 813 |
815 Like :meth:`assertRaises` but also tests that *regexp* matches | 814 Like :meth:`assertRaises` but also tests that *regexp* matches |
816 on the string representation of the raised exception. *regexp* may be | 815 on the string representation of the raised exception. *regexp* may be |
817 a regular expression object or a string containing a regular expression | 816 a regular expression object or a string containing a regular expression |
818 suitable for use by :func:`re.search`. Examples:: | 817 suitable for use by :func:`re.search`. Examples:: |
819 | 818 |
820 self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', | 819 self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', |
821 int, 'XYZ') | 820 int, 'XYZ') |
822 | 821 |
823 or:: | 822 or:: |
824 | 823 |
825 with self.assertRaisesRegexp(ValueError, 'literal'): | 824 with self.assertRaisesRegexp(ValueError, 'literal'): |
826 int('XYZ') | 825 int('XYZ') |
827 | 826 |
828 .. versionadded:: 2.7 | 827 .. versionadded:: 2.7 |
829 | 828 |
830 | 829 |
831 .. method:: assertIsNone(expr[, msg]) | 830 .. method:: assertIsNone(expr[, msg]) |
832 | 831 |
833 This signals a test failure if *expr* is not None. | 832 This signals a test failure if *expr* is not None. |
834 | 833 |
835 .. versionadded:: 2.7 | 834 .. versionadded:: 2.7 |
836 | 835 |
837 | 836 |
838 .. method:: assertIsNotNone(expr[, msg]) | 837 .. method:: assertIsNotNone(expr[, msg]) |
839 | 838 |
840 The inverse of the :meth:`assertIsNone` method. | 839 The inverse of the :meth:`assertIsNone` method. |
841 This signals a test failure if *expr* is None. | 840 This signals a test failure if *expr* is None. |
842 | 841 |
843 .. versionadded:: 2.7 | 842 .. versionadded:: 2.7 |
844 | 843 |
845 | 844 |
846 .. method:: failIf(expr[, msg]) | 845 .. method:: assertFalse(expr[, msg]) |
847 assertFalse(expr[, msg]) | 846 failIf(expr[, msg]) |
848 | 847 |
849 The inverse of the :meth:`failUnless` method is the :meth:`failIf` method. | 848 The inverse of the :meth:`assertTrue` method is the :meth:`assertFalse` me
thod. |
850 This signals a test failure if *expr* is true, with *msg* or :const:`None` | 849 This signals a test failure if *expr* is true, with *msg* or :const:`None` |
851 for the error message. | 850 for the error message. |
852 | 851 |
853 | 852 |
854 .. method:: fail([msg]) | 853 .. method:: fail([msg]) |
855 | 854 |
856 Signals a test failure unconditionally, with *msg* or :const:`None` for | 855 Signals a test failure unconditionally, with *msg* or :const:`None` for |
857 the error message. | 856 the error message. |
858 | 857 |
859 | 858 |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
902 .. versionchanged:: 2.7 | 901 .. versionchanged:: 2.7 |
903 | 902 |
904 In earlier versions this only returned the first line of the test | 903 In earlier versions this only returned the first line of the test |
905 method's docstring, if available or the :const:`None`. That led to | 904 method's docstring, if available or the :const:`None`. That led to |
906 undesirable behavior of not printing the test name when someone was | 905 undesirable behavior of not printing the test name when someone was |
907 thoughtful enough to write a docstring. | 906 thoughtful enough to write a docstring. |
908 | 907 |
909 | 908 |
910 .. method:: addTypeEqualityFunc(typeobj, function) | 909 .. method:: addTypeEqualityFunc(typeobj, function) |
911 | 910 |
912 Registers a type specific :meth:`assertEquals` equality checking | 911 Registers a type specific :meth:`assertEqual` equality checking |
913 function to be called by :meth:`assertEquals` when both objects it has | 912 function to be called by :meth:`assertEqual` when both objects it has |
914 been asked to compare are exactly *typeobj* (not subclasses). | 913 been asked to compare are exactly *typeobj* (not subclasses). |
915 *function* must take two positional arguments and a third msg=None | 914 *function* must take two positional arguments and a third msg=None |
916 keyword argument just as :meth:`assertEquals` does. It must raise | 915 keyword argument just as :meth:`assertEqual` does. It must raise |
917 self.failureException when inequality between the first two | 916 self.failureException when inequality between the first two |
918 parameters is detected. | 917 parameters is detected. |
919 | 918 |
920 One good use of custom equality checking functions for a type | 919 One good use of custom equality checking functions for a type |
921 is to raise self.failureException with an error message useful | 920 is to raise self.failureException with an error message useful |
922 for debugging the by explaining the inequalities in detail. | 921 for debugging the by explaining the inequalities in detail. |
923 | 922 |
924 .. versionadded:: 2.7 | 923 .. versionadded:: 2.7 |
925 | 924 |
926 | 925 |
927 .. class:: functiontestcase(testfunc[, setup[, teardown[, description]]]) | 926 .. class:: FunctionTestCase(testFunc[, setUp[, tearDown[, description]]]) |
928 | 927 |
929 this class implements the portion of the :class:`testcase` interface which | 928 This class implements the portion of the :class:`TestCase` interface which |
930 allows the test runner to drive the test, but does not provide the methods wh
ich | 929 allows the test runner to drive the test, but does not provide the methods wh
ich |
931 test code can use to check and report errors. this is used to create test cas
es | 930 test code can use to check and report errors. This is used to create test cas
es |
932 using legacy test code, allowing it to be integrated into a :mod:`unittest`\ | 931 using legacy test code, allowing it to be integrated into a :mod:`unittest`\ |
933 -based test framework. | 932 -based test framework. |
934 | 933 |
935 | 934 |
936 .. _testsuite-objects: | 935 .. _testsuite-objects: |
937 | 936 |
938 grouping tests | 937 Grouping tests |
939 ~~~~~~~~~~~~~~ | 938 ~~~~~~~~~~~~~~ |
940 | 939 |
941 .. class:: testsuite([tests]) | 940 .. class:: TestSuite([tests]) |
942 | 941 |
943 this class represents an aggregation of individual tests cases and test suite
s. | 942 This class represents an aggregation of individual tests cases and test suite
s. |
944 the class presents the interface needed by the test runner to allow it to be
run | 943 The class presents the interface needed by the test runner to allow it to be
run |
945 as any other test case. running a :class:`testsuite` instance is the same as | 944 as any other test case. Running a :class:`TestSuite` instance is the same as |
946 iterating over the suite, running each test individually. | 945 iterating over the suite, running each test individually. |
947 | 946 |
948 if *tests* is given, it must be an iterable of individual test cases or other | 947 If *tests* is given, it must be an iterable of individual test cases or other |
949 test suites that will be used to build the suite initially. additional method
s | 948 test suites that will be used to build the suite initially. Additional method
s |
950 are provided to add test cases and suites to the collection later on. | 949 are provided to add test cases and suites to the collection later on. |
951 | 950 |
952 :class:`testsuite` (including :class:`classtestsuite`) objects behave much | 951 :class:`TestSuite` (including :class:`ClassTestSuite`) objects behave much |
953 like :class:`testcase` objects, except they do not actually implement a test. | 952 like :class:`TestCase` objects, except they do not actually implement a test. |
954 instead, they are used to aggregate tests into groups of tests that should be | 953 Instead, they are used to aggregate tests into groups of tests that should be |
955 run together. some additional methods are available to add tests to | 954 run together. Some additional methods are available to add tests to |
956 :class:`testsuite` instances: | 955 :class:`TestSuite` instances: |
957 | 956 |
958 | 957 |
959 .. method:: testsuite.addtest(test) | 958 .. method:: TestSuite.addTest(test) |
960 | 959 |
961 add a :class:`testcase` or :class:`testsuite` to the suite. | 960 Add a :class:`TestCase` or :class:`TestSuite` to the suite. |
962 | 961 |
963 | 962 |
964 .. method:: testsuite.addtests(tests) | 963 .. method:: TestSuite.addTests(tests) |
965 | 964 |
966 add all the tests from an iterable of :class:`testcase` and :class:`testsu
ite` | 965 Add all the tests from an iterable of :class:`TestCase` and :class:`TestSu
ite` |
967 instances to this test suite. | 966 instances to this test suite. |
968 | 967 |
969 this is equivalent to iterating over *tests*, calling :meth:`addtest` for
each | 968 This is equivalent to iterating over *tests*, calling :meth:`addTest` for
each |
970 element. | 969 element. |
971 | 970 |
972 :class:`testsuite` shares the following methods with :class:`testcase`: | 971 :class:`TestSuite` shares the following methods with :class:`TestCase`: |
973 | 972 |
974 | 973 |
975 .. method:: run(result) | 974 .. method:: run(result) |
976 | 975 |
977 run the tests associated with this suite, collecting the result into the | 976 Run the tests associated with this suite, collecting the result into the |
978 test result object passed as *result*. note that unlike | 977 test result object passed as *result*. Note that unlike |
979 :meth:`testcase.run`, :meth:`testsuite.run` requires the result object to | 978 :meth:`TestCase.run`, :meth:`TestSuite.run` requires the result object to |
980 be passed in. | 979 be passed in. |
981 | 980 |
982 | 981 |
983 .. method:: debug() | 982 .. method:: debug() |
984 | 983 |
985 run the tests associated with this suite without collecting the | 984 Run the tests associated with this suite without collecting the |
986 result. this allows exceptions raised by the test to be propagated to the | 985 result. This allows exceptions raised by the test to be propagated to the |
987 caller and can be used to support running tests under a debugger. | 986 caller and can be used to support running tests under a debugger. |
988 | 987 |
989 | 988 |
990 .. method:: counttestcases() | 989 .. method:: countTestCases() |
991 | 990 |
992 return the number of tests represented by this test object, including all | 991 Return the number of tests represented by this test object, including all |
993 individual tests and sub-suites. | 992 individual tests and sub-suites. |
994 | 993 |
995 in the typical usage of a :class:`testsuite` object, the :meth:`run` method | 994 In the typical usage of a :class:`TestSuite` object, the :meth:`run` method |
996 is invoked by a :class:`testrunner` rather than by the end-user test harness. | 995 is invoked by a :class:`TestRunner` rather than by the end-user test harness. |
997 | 996 |
998 | 997 |
999 .. class:: classtestsuite(tests, collected_from) | 998 .. class:: ClassTestSuite(tests, collected_from) |
1000 | 999 |
1001 this subclass of :class:`testsuite` repesents an aggregation of individuals | 1000 This subclass of :class:`TestSuite` repesents an aggregation of individuals |
1002 tests from one :class:`testcase` class. *tests* is an iterable of | 1001 tests from one :class:`TestCase` class. *tests* is an iterable of |
1003 :class:`testcase` instances created from the class. *collected_from* is the | 1002 :class:`TestCase` instances created from the class. *collected_from* is the |
1004 class they came from. | 1003 class they came from. |
1005 | 1004 |
1006 | 1005 |
1007 loading and running tests | 1006 Loading and running tests |
1008 ~~~~~~~~~~~~~~~~~~~~~~~~~ | 1007 ~~~~~~~~~~~~~~~~~~~~~~~~~ |
1009 | 1008 |
1010 .. class:: testloader() | 1009 .. class:: TestLoader() |
1011 | 1010 |
1012 the :class:`testloader` class is used to create test suites from classes and | 1011 The :class:`TestLoader` class is used to create test suites from classes and |
1013 modules. normally, there is no need to create an instance of this class; the | 1012 modules. Normally, there is no need to create an instance of this class; the |
1014 :mod:`unittest` module provides an instance that can be shared as | 1013 :mod:`unittest` module provides an instance that can be shared as |
1015 ``unittest.defaulttestloader``. using a subclass or instance, however, allows | 1014 ``unittest.defaultTestLoader``. Using a subclass or instance, however, allows |
1016 customization of some configurable properties. | 1015 customization of some configurable properties. |
1017 | 1016 |
1018 :class:`testloader` objects have the following methods: | 1017 :class:`TestLoader` objects have the following methods: |
1019 | 1018 |
1020 | 1019 |
1021 .. method:: loadtestsfromtestcase(testcaseclass) | 1020 .. method:: loadTestsFromTestCase(testCaseClass) |
1022 | 1021 |
1023 return a suite of all tests cases contained in the :class:`testcase`\ -der
ived | 1022 Return a suite of all tests cases contained in the :class:`TestCase`\ -der
ived |
1024 :class:`testcaseclass`. | 1023 :class:`testCaseClass`. |
1025 | 1024 |
1026 | 1025 |
1027 .. method:: loadtestsfrommodule(module) | 1026 .. method:: loadTestsFromModule(module) |
1028 | 1027 |
1029 return a suite of all tests cases contained in the given module. this | 1028 Return a suite of all tests cases contained in the given module. This |
1030 method searches *module* for classes derived from :class:`testcase` and | 1029 method searches *module* for classes derived from :class:`TestCase` and |
1031 creates an instance of the class for each test method defined for the | 1030 creates an instance of the class for each test method defined for the |
1032 class. | 1031 class. |
1033 | 1032 |
1034 .. warning:: | 1033 .. warning:: |
1035 | 1034 |
1036 while using a hierarchy of :class:`testcase`\ -derived classes can be | 1035 While using a hierarchy of :class:`TestCase`\ -derived classes can be |
1037 convenient in sharing fixtures and helper functions, defining test | 1036 convenient in sharing fixtures and helper functions, defining test |
1038 methods on base classes that are not intended to be instantiated | 1037 methods on base classes that are not intended to be instantiated |
1039 directly does not play well with this method. doing so, however, can | 1038 directly does not play well with this method. Doing so, however, can |
1040 be useful when the fixtures are different and defined in subclasses. | 1039 be useful when the fixtures are different and defined in subclasses. |
1041 | 1040 |
1042 | 1041 |
1043 .. method:: loadtestsfromname(name[, module]) | 1042 .. method:: loadTestsFromName(name[, module]) |
1044 | 1043 |
1045 return a suite of all tests cases given a string specifier. | 1044 Return a suite of all tests cases given a string specifier. |
1046 | 1045 |
1047 the specifier *name* is a "dotted name" that may resolve either to a | 1046 The specifier *name* is a "dotted name" that may resolve either to a |
1048 module, a test case class, a test method within a test case class, a | 1047 module, a test case class, a test method within a test case class, a |
1049 :class:`testsuite` instance, or a callable object which returns a | 1048 :class:`TestSuite` instance, or a callable object which returns a |
1050 :class:`testcase` or :class:`testsuite` instance. these checks are | 1049 :class:`TestCase` or :class:`TestSuite` instance. These checks are |
1051 applied in the order listed here; that is, a method on a possible test | 1050 applied in the order listed here; that is, a method on a possible test |
1052 case class will be picked up as "a test method within a test case class", | 1051 case class will be picked up as "a test method within a test case class", |
1053 rather than "a callable object". | 1052 rather than "a callable object". |
1054 | 1053 |
1055 for example, if you have a module :mod:`sampletests` containing a | 1054 For example, if you have a module :mod:`SampleTests` containing a |
1056 :class:`testcase`\ -derived class :class:`sampletestcase` with three test | 1055 :class:`TestCase`\ -derived class :class:`SampleTestCase` with three test |
1057 methods (:meth:`test_one`, :meth:`test_two`, and :meth:`test_three`), the | 1056 methods (:meth:`test_one`, :meth:`test_two`, and :meth:`test_three`), the |
1058 specifier ``'sampletests.sampletestcase'`` would cause this method to retu
rn a | 1057 specifier ``'SampleTests.SampleTestCase'`` would cause this method to retu
rn a |
1059 suite which will run all three test methods. using the specifier | 1058 suite which will run all three test methods. Using the specifier |
1060 ``'sampletests.sampletestcase.test_two'`` would cause it to return a test
suite | 1059 ``'SampleTests.SampleTestCase.test_two'`` would cause it to return a test
suite |
1061 which will run only the :meth:`test_two` test method. the specifier can r
efer | 1060 which will run only the :meth:`test_two` test method. The specifier can r
efer |
1062 to modules and packages which have not been imported; they will be importe
d as a | 1061 to modules and packages which have not been imported; they will be importe
d as a |
1063 side-effect. | 1062 side-effect. |
1064 | 1063 |
1065 the method optionally resolves *name* relative to the given *module*. | 1064 The method optionally resolves *name* relative to the given *module*. |
1066 | 1065 |
1067 | 1066 |
1068 .. method:: loadtestsfromnames(names[, module]) | 1067 .. method:: loadTestsFromNames(names[, module]) |
1069 | 1068 |
1070 similar to :meth:`loadtestsfromname`, but takes a sequence of names rather | 1069 Similar to :meth:`loadTestsFromName`, but takes a sequence of names rather |
1071 than a single name. the return value is a test suite which supports all | 1070 than a single name. The return value is a test suite which supports all |
1072 the tests defined for each name. | 1071 the tests defined for each name. |
1073 | 1072 |
1074 | 1073 |
1075 .. method:: gettestcasenames(testcaseclass) | 1074 .. method:: getTestCaseNames(testCaseClass) |
1076 | 1075 |
1077 return a sorted sequence of method names found within *testcaseclass*; | 1076 Return a sorted sequence of method names found within *testCaseClass*; |
1078 this should be a subclass of :class:`testcase`. | 1077 this should be a subclass of :class:`TestCase`. |
1079 | 1078 |
1080 the following attributes of a :class:`testloader` can be configured either by | 1079 The following attributes of a :class:`TestLoader` can be configured either by |
1081 subclassing or assignment on an instance: | 1080 subclassing or assignment on an instance: |
1082 | 1081 |
1083 | 1082 |
1084 .. attribute:: testmethodprefix | 1083 .. attribute:: testMethodPrefix |
1085 | 1084 |
1086 string giving the prefix of method names which will be interpreted as test | 1085 String giving the prefix of method names which will be interpreted as test |
1087 methods. the default value is ``'test'``. | 1086 methods. The default value is ``'test'``. |
1088 | 1087 |
1089 this affects :meth:`gettestcasenames` and all the :meth:`loadtestsfrom\*` | 1088 This affects :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*` |
1090 methods. | 1089 methods. |
1091 | 1090 |
1092 | 1091 |
1093 .. attribute:: sorttestmethodsusing | 1092 .. attribute:: sortTestMethodsUsing |
1094 | 1093 |
1095 function to be used to compare method names when sorting them in | 1094 Function to be used to compare method names when sorting them in |
1096 :meth:`gettestcasenames` and all the :meth:`loadtestsfrom\*` methods. the | 1095 :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*` methods. The |
1097 default value is the built-in :func:`cmp` function; the attribute can also | 1096 default value is the built-in :func:`cmp` function; the attribute can also |
1098 be set to :const:`none` to disable the sort. | 1097 be set to :const:`None` to disable the sort. |
1099 | 1098 |
1100 | 1099 |
1101 .. attribute:: suiteclass | 1100 .. attribute:: suiteClass |
1102 | 1101 |
1103 callable object that constructs a test suite from a list of tests. no | 1102 Callable object that constructs a test suite from a list of tests. No |
1104 methods on the resulting object are needed. the default value is the | 1103 methods on the resulting object are needed. The default value is the |
1105 :class:`testsuite` class. | 1104 :class:`TestSuite` class. |
1106 | 1105 |
1107 this affects all the :meth:`loadtestsfrom\*` methods. | 1106 This affects all the :meth:`loadTestsFrom\*` methods. |
1108 | 1107 |
1109 | 1108 |
1110 .. attribute:: classsuiteclass | 1109 .. attribute:: classSuiteClass |
1111 | 1110 |
1112 callable object that constructs a test suite for the tests cases from one | 1111 Callable object that constructs a test suite for the tests cases from one |
1113 class. the default value is :class:`classtestsuite`. | 1112 class. The default value is :class:`ClassTestSuite`. |
1114 | 1113 |
1115 | 1114 |
1116 .. class:: testresult | 1115 .. class:: TestResult |
1117 | 1116 |
1118 this class is used to compile information about which tests have succeeded | 1117 This class is used to compile information about which tests have succeeded |
1119 and which have failed. | 1118 and which have failed. |
1120 | 1119 |
1121 a :class:`testresult` object stores the results of a set of tests. the | 1120 A :class:`TestResult` object stores the results of a set of tests. The |
1122 :class:`testcase` and :class:`testsuite` classes ensure that results are | 1121 :class:`TestCase` and :class:`TestSuite` classes ensure that results are |
1123 properly recorded; test authors do not need to worry about recording the | 1122 properly recorded; test authors do not need to worry about recording the |
1124 outcome of tests. | 1123 outcome of tests. |
1125 | 1124 |
1126 testing frameworks built on top of :mod:`unittest` may want access to the | 1125 Testing frameworks built on top of :mod:`unittest` may want access to the |
1127 :class:`testresult` object generated by running a set of tests for reporting | 1126 :class:`TestResult` object generated by running a set of tests for reporting |
1128 purposes; a :class:`testresult` instance is returned by the | 1127 purposes; a :class:`TestResult` instance is returned by the |
1129 :meth:`testrunner.run` method for this purpose. | 1128 :meth:`TestRunner.run` method for this purpose. |
1130 | 1129 |
1131 :class:`testresult` instances have the following attributes that will be of | 1130 :class:`TestResult` instances have the following attributes that will be of |
1132 interest when inspecting the results of running a set of tests: | 1131 interest when inspecting the results of running a set of tests: |
1133 | 1132 |
1134 | 1133 |
1135 .. attribute:: errors | 1134 .. attribute:: errors |
1136 | 1135 |
1137 a list containing 2-tuples of :class:`testcase` instances and strings | 1136 A list containing 2-tuples of :class:`TestCase` instances and strings |
1138 holding formatted tracebacks. each tuple represents a test which raised an | 1137 holding formatted tracebacks. Each tuple represents a test which raised an |
1139 unexpected exception. | 1138 unexpected exception. |
1140 | 1139 |
1141 .. versionchanged:: 2.2 | 1140 .. versionchanged:: 2.2 |
1142 | 1141 |
1143 Contains formatted tracebacks instead of :func:`sys.exc_info` results. | 1142 Contains formatted tracebacks instead of :func:`sys.exc_info` results. |
1144 | 1143 |
1145 | 1144 |
1146 .. attribute:: failures | 1145 .. attribute:: failures |
1147 | 1146 |
1148 A list containing 2-tuples of :class:`TestCase` instances and strings | 1147 A list containing 2-tuples of :class:`TestCase` instances and strings |
(...skipping 147 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1296 | 1295 |
1297 A command-line program that runs a set of tests; this is primarily for making | 1296 A command-line program that runs a set of tests; this is primarily for making |
1298 test modules conveniently executable. The simplest use for this function is
to | 1297 test modules conveniently executable. The simplest use for this function is
to |
1299 include the following line at the end of a test script:: | 1298 include the following line at the end of a test script:: |
1300 | 1299 |
1301 if __name__ == '__main__': | 1300 if __name__ == '__main__': |
1302 unittest.main() | 1301 unittest.main() |
1303 | 1302 |
1304 The *testRunner* argument can either be a test runner class or an already | 1303 The *testRunner* argument can either be a test runner class or an already |
1305 created instance of it. | 1304 created instance of it. |
LEFT | RIGHT |