1 README FOR IDLE TESTS IN IDLELIB.IDLE_TEST 2 3 0. Quick Start 4 5 Automated unit tests were added in 2.7 for Python 2.x and 3.3 for Python 3.x. 6 To run the tests from a command line: 7 8 python -m test.test_idle 9 10 Human-mediated tests were added later in 2.7 and in 3.4. 11 12 python -m idlelib.idle_test.htest 13 14 15 1. Test Files 16 17 The idle directory, idlelib, has over 60 xyz.py files. The idle_test 18 subdirectory should contain a test_xyz.py for each, where 'xyz' is lowercased 19 even if xyz.py is not. Here is a possible template, with the blanks after 20 '.' and 'as', and before and after '_' to be filled in. 21 22 import unittest 23 from test.support import requires 24 import idlelib. as 25 26 class _Test(unittest.TestCase): 27 28 def test_(self): 29 30 if __name__ == '__main__': 31 unittest.main(verbosity=2) 32 33 Add the following at the end of xyy.py, with the appropriate name added after 34 'test_'. Some files already have something like this for htest. If so, insert 35 the import and unittest.main lines before the htest lines. 36 37 if __name__ == "__main__": 38 import unittest 39 unittest.main('idlelib.idle_test.test_', verbosity=2, exit=False) 40 41 42 43 2. GUI Tests 44 45 When run as part of the Python test suite, Idle GUI tests need to run 46 test.test_support.requires('gui') (test.support in 3.x). A test is a GUI test 47 if it creates a Tk root or master object either directly or indirectly by 48 instantiating a tkinter or idle class. For the benefit of test processes that 49 either have no graphical environment available or are not allowed to use it, GUI 50 tests must be 'guarded' by "requires('gui')" in a setUp function or method. 51 This will typically be setUpClass. 52 53 To avoid interfering with other GUI tests, all GUI objects must be destroyed and 54 deleted by the end of the test. The Tk root created in a setUpX function should 55 be destroyed in the corresponding tearDownX and the module or class attribute 56 deleted. Others widgets should descend from the single root and the attributes 57 deleted BEFORE root is destroyed. See https://bugs.python.org/issue20567. 58 59 @classmethod 60 def setUpClass(cls): 61 requires('gui') 62 cls.root = tk.Tk() 63 cls.text = tk.Text(root) 64 65 @classmethod 66 def tearDownClass(cls): 67 del cls.text 68 cls.root.destroy() 69 del cls.root 70 71 WARNING: In 2.7, "requires('gui') MUST NOT be called at module scope. 72 See https://bugs.python.org/issue18910 73 74 Requires('gui') causes the test(s) it guards to be skipped if any of 75 these conditions are met: 76 77 - The tests are being run by regrtest.py, and it was started without enabling 78 the "gui" resource with the "-u" command line option. 79 80 - The tests are being run on Windows by a service that is not allowed to 81 interact with the graphical environment. 82 83 - The tests are being run on Linux and X Windows is not available. 84 85 - The tests are being run on Mac OSX in a process that cannot make a window 86 manager connection. 87 88 - tkinter.Tk cannot be successfully instantiated for some reason. 89 90 - test.support.use_resources has been set by something other than 91 regrtest.py and does not contain "gui". 92 93 Tests of non-GUI operations should avoid creating tk widgets. Incidental uses of 94 tk variables and messageboxes can be replaced by the mock classes in 95 idle_test/mock_tk.py. The mock text handles some uses of the tk Text widget. 96 97 98 3. Running Unit Tests 99 100 Assume that xyz.py and test_xyz.py both end with a unittest.main() call. 101 Running either from an Idle editor runs all tests in the test_xyz file with the 102 version of Python running Idle. Test output appears in the Shell window. The 103 'verbosity=2' option lists all test methods in the file, which is appropriate 104 when developing tests. The 'exit=False' option is needed in xyx.py files when an 105 htest follows. 106 107 The following command lines also run all test methods, including 108 GUI tests, in test_xyz.py. (Both '-m idlelib' and '-m idlelib.idle' start 109 Idle and so cannot run tests.) 110 111 python -m idlelib.xyz 112 python -m idlelib.idle_test.test_xyz 113 114 The following runs all idle_test/test_*.py tests interactively. 115 116 >>> import unittest 117 >>> unittest.main('idlelib.idle_test', verbosity=2) 118 119 The following run all Idle tests at a command line. Option '-v' is the same as 120 'verbosity=2'. (For 2.7, replace 'test' in the second line with 121 'test.regrtest'.) 122 123 python -m unittest -v idlelib.idle_test 124 python -m test -v -ugui test_idle 125 python -m test.test_idle 126 127 The idle tests are 'discovered' by idlelib.idle_test.__init__.load_tests, 128 which is also imported into test.test_idle. Normally, neither file should be 129 changed when working on individual test modules. The third command runs 130 unittest indirectly through regrtest. The same happens when the entire test 131 suite is run with 'python -m test'. So that command must work for buildbots 132 to stay green. Idle tests must not disturb the environment in a way that 133 makes other tests fail (issue 18081). 134 135 To run an individual Testcase or test method, extend the dotted name given to 136 unittest on the command line. 137 138 python -m unittest -v idlelib.idle_test.test_xyz.Test_case.test_meth 139 140 141 4. Human-mediated Tests 142 143 Human-mediated tests are widget tests that cannot be automated but need human 144 verification. They are contained in idlelib/idle_test/htest.py, which has 145 instructions. (Some modules need an auxiliary function, identified with # htest 146 # on the header line.) The set is about complete, though some tests need 147 improvement. To run all htests, run the htest file from an editor or from the 148 command line with: 149 150 python -m idlelib.idle_test.htest 151
